On this page
Brazil contacts now require a document and accept alphanumeric CNPJ
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:
{
"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:
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.