Koywe
What's new
On this page
BreakingAPI

Brazil contacts now require a document and accept alphanumeric CNPJ

Published on

What to do: if your integration creates Brazil contacts without a document, send documentType (CPF or CNPJ) and documentNumber. If you validate the CNPJ on your side, update your validator to accept letters in the first 12 characters. Existing contacts don’t change.

What was happening

When you created a contact with countrySymbol: "BR" and no document, the contact was created anyway and the payment failed later, at the provider.

What changed

The document is required. Creating a contact with countrySymbol: "BR" and no CPF or CNPJ now returns 400 with code CT00048:

JSON
{
  "ok": false,
  "error": {
    "code": "CT00048",
    "message": "documentType and documentNumber (CPF or CNPJ) are required for Brazil contacts"
  }
}

CNPJ can be alphanumeric. Since July 2026, the Receita Federal assigns alphanumeric CNPJs to new companies: 12 characters that can be letters or digits, followed by 2 numeric check digits. Numeric CNPJs remain valid, so the API accepts both formats, with or without formatting and also in lowercase.

A company contact with an alphanumeric CNPJ is created like this:

Terminal
curl -X POST 'https://api.koywe.com/api/v1/organizations/{organizationId}/merchants/{merchantId}/contacts' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "firstName": "Example Company Ltda",
    "countrySymbol": "BR",
    "businessType": "COMPANY",
    "type": "BUSINESS",
    "documentType": "CNPJ",
    "documentNumber": "12.ABC.345/01DE-35"
  }'

The full rules (when it’s validated on create and on update, formats and duplicates) are in Contacts and bank accounts.