Alphanumeric CNPJ Support

Starting in July 2026, Brazil's Receita Federal (Federal Revenue Service) will issue alphanumeric CNPJs alongside the traditional numeric-only format. EBANX fully supports this new format across all APIs and payment methods.

This guide describes the API changes, the new validation algorithm, possible error codes, and best practices for updating your integration.

No action required for numeric CNPJs

Existing numeric CNPJs continue to work unchanged. The validation algorithm is fully backward-compatible. However, we recommend updating your integration proactively to avoid hard declines when a customer with an alphanumeric CNPJ attempts a transaction.

API changes

Document field format

The document field in all EBANX APIs now accepts alphanumeric CNPJs.

Format	Raw example	Formatted example
Numeric CNPJ (existing)	12345678000195	12.345.678/0001-95
Alphanumeric CNPJ (new)	12ABC34501DE35	12.ABC.345/01DE-35
CPF (unchanged)	52998224725	529.982.247-25

Key rules:

• CNPJ remains 14 characters after removing formatting characters (dots, slashes, dashes).
• The first 12 positions may contain digits (0-9) and uppercase ASCII letters (A-Z).
• The last 2 positions (check digits) are always numeric (0-9).
• Regex after stripping formatting: ^[0-9A-Za-z]{12}[0-9]{2}$.
• CPF format is unchanged (11 numeric digits).

Affected endpoints

All endpoints that accept a Brazilian document are affected:

API	Endpoint / Field	Notes
Pay-in Direct	payment.document	All Brazil payment methods (Boleto, PIX, Credit Card, Debit Card, Nu Pay)
Pay-in Query	Response payment.document	May return an alphanumeric CNPJ in responses
Document Balance	document query parameter	Accepts formatted or unformatted alphanumeric CNPJ
Refund (PIX)	refund.bank_info.pix_key	PIX key may be an alphanumeric CNPJ
Refund (Bank Transfer)	refund.bank_info.document	Bank account holder document
Payout - Create Payee	document	Payee identification
Payout - Create Payout	payee.document	Payee document in payout request

Input normalization

EBANX automatically normalizes the document field:

• Formatting characters (. - / and spaces) are stripped.
• Letters are preserved when the result is 14 characters (CNPJ length).
• Letters are uppercased automatically.
• For 11-character results (CPF), only digits are kept (unchanged behavior).

All of the following inputs produce the same normalized value 12ABC34501DE35:

"12.ABC.345/01DE-35"
"12abc34501de35"
"12ABC34501DE35"

Validation algorithm

Character value mapping

The Receita Federal defined a backward-compatible algorithm for computing the two check digits (positions 13 and 14). Each character is converted to a numeric value using its ASCII code:

character_value = ASCII(character) - 48

This maps:

Character	ASCII	Value
0	48	0
1	49	1
...	...	...
9	57	9
A	65	17
B	66	18
...	...	...
Z	90	42

For purely numeric CNPJs, this produces the same result as the traditional algorithm (ASCII('5') - 48 = 5).

Check digit calculation

Given the first 12 characters of a CNPJ, compute the two check digits:

First check digit (D1):

1. Multiply each character value by the weight factors [5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2].
2. Sum all products.
3. Compute remainder = sum % 11.
4. If remainder < 2, then D1 = 0; otherwise D1 = 11 - remainder.

Second check digit (D2):

1. Append D1 as the 13th character.
2. Multiply each of the 13 character values by [6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2].
3. Apply the same modulo-11 rule.

Worked example

For the CNPJ body 12ABC34501DE:

Position	Char	Value (ASCII - 48)	Weight	Product
0	1	1	5	5
1	2	2	4	8
2	A	17	3	51
3	B	18	2	36
4	C	19	9	171
5	3	3	8	24
6	4	4	7	28
7	5	5	6	30
8	0	0	5	0
9	1	1	4	4
10	D	20	3	60
11	E	21	2	42

Sum = 459 → remainder = 459 % 11 = 8 → D1 = 11 - 8 = 3

Repeating with 13 weights produces D2 = 5, giving the complete CNPJ: 12ABC34501DE35.

Blocklist

The following all-same-digit CNPJs are blocked (unchanged):

00000000000000, 11111111111111, 22222222222222, ..., 99999999999999

These only apply to fully numeric CNPJs. Alphanumeric CNPJs containing letters cannot match these patterns.

Error codes

When sending a Brazilian document in your API request, the following error codes may be returned if validation fails:

Error code	Message	When it occurs
BP-DR-22	Field payment.document is required	The document field is missing or empty.
BP-DR-23	Field payment.document must be a valid CNPJ	CNPJ failed format or check-digit validation.
BP-DR-23	Field payment.document must be a valid CPF	CPF failed validation (when person_type is personal).
BP-DR-39	Document, name and birth date do not match	Bureau check returned an irregular status for the CNPJ.
BP-DR-111	Could not validate document. Please try again.	Transient error during document validation. Retry the request.
BP-DOC-01	Invalid document: <document>	Document is invalid for the given country or type.

Common causes of BP-DR-23 with alphanumeric CNPJ

1. Letters in check-digit positions. The last 2 characters must always be digits. 12ABC34501DEXY is invalid.
2. Wrong length. After stripping formatting, the result must be exactly 14 characters.
3. Incorrect check digits. If your system computes check digits using the old digit-only formula, it will produce wrong results for alphanumeric CNPJs. Use ASCII(char) - 48 for all characters.
4. Stripping letters before sending. If your system removes all non-digit characters from the document before calling EBANX, alphanumeric CNPJs will be corrupted. For example, 12ABC34501DE35 becomes 123450135 (9 characters), which is neither a valid CPF nor CNPJ.

Most common integration issue

The number one cause of failures is stripping letters from the document field before sending it to EBANX. Update your sanitization logic to preserve alphanumeric characters.

Best practices

Update document sanitization

If your system sanitizes the document field before sending it to EBANX, update the logic to preserve letters:

JavaScript

// Before (breaks alphanumeric CNPJ)
document.replace(/[^0-9]/g, '');

// After (correct)
document.replace(/[^0-9A-Za-z]/g, '');

PHP

// Before (breaks alphanumeric CNPJ)
preg_replace('/\D/', '', $document);

// After (correct)
preg_replace('/[^0-9A-Za-z]/', '', $document);

Python

# Before (breaks alphanumeric CNPJ)
re.sub(r'\D', '', document)

# After (correct)
re.sub(r'[^0-9A-Za-z]', '', document)

Update format validation

If your system validates the CNPJ format before sending it to EBANX:

Old regex:  /^\d{14}$/
New regex:  /^[0-9A-Za-z]{12}[0-9]{2}$/

If you validate check digits locally, update the algorithm to use ASCII(char) - 48 for each character value instead of direct numeric conversion.

Update database schemas

If you store CNPJs in your database:

Check	Action
Column type	Ensure the column is VARCHAR or TEXT, not a numeric type.
Column length	14 characters minimum (unchanged).
Character set	Must support ASCII letters (standard in UTF-8).
Case sensitivity	Store CNPJs in uppercase for consistency. EBANX always returns uppercase.

Update input masks

If your checkout or back-office UI has CNPJ input masks:

Old mask	New mask
99.999.999/9999-99	XX.XXX.XXX/XXXX-99

Where X accepts any alphanumeric character and 9 accepts digits only. The exact syntax depends on your masking library.

Handle case sensitivity

• EBANX normalizes all letters to uppercase before validation and storage.
• You may send lowercase letters and they will be accepted.
• API responses always return uppercase.
• For document comparison or matching, always compare in uppercase.

Detect document type

To determine whether a Brazilian document is a CPF or CNPJ:

1. Strip formatting characters (keep alphanumeric characters).
2. If the result is 11 characters and all digits: CPF.
3. If the result is 14 characters (may contain letters): CNPJ.

Avoid is_numeric checks

Do not use is_numeric() or equivalent functions to determine whether a document is a valid CNPJ. Alphanumeric CNPJs are not numeric strings.

Test vectors

Use these values to verify your integration handles alphanumeric CNPJs correctly:

Input	Normalized	Type	Valid
12.ABC.345/01DE-35	12ABC34501DE35	CNPJ	Yes
12abc34501de35	12ABC34501DE35	CNPJ	Yes
12.345.678/0001-95	12345678000195	CNPJ	Yes
529.982.247-25	52998224725	CPF	Yes
12ABC34501DE99	12ABC34501DE99	CNPJ	No (wrong check digits)
12.ABC.345/01DE-XY	Invalid	CNPJ	No (letters in check-digit positions)

FAQ

Will existing numeric CNPJs stop working?

No. All existing numeric CNPJs continue to work exactly as before. The algorithm is backward-compatible.

Can I send the CNPJ with formatting characters?

Yes. EBANX strips ., -, /, and spaces automatically. 12.ABC.345/01DE-35 is equivalent to 12ABC34501DE35.

Do I need to update my check-digit validation?

Only if you validate CNPJ check digits locally before calling EBANX. The new algorithm uses ASCII(char) - 48, which produces the same results for digits but also handles letters correctly.

What about PIX keys that are CNPJs?

PIX keys that are CNPJs follow the same rules. EBANX accepts alphanumeric CNPJ PIX keys in refund and payout flows.

Does this affect the person_type field?

No. CNPJs (both numeric and alphanumeric) correspond to person_type: "business". CPFs correspond to person_type: "personal". The logic is unchanged.

What happens if I send a CNPJ with letters stripped?

If the original CNPJ is alphanumeric, stripping letters corrupts the document. For example, 12ABC34501DE35 becomes 123450135 (9 characters), which is neither a valid CPF nor CNPJ. You will receive a BP-DR-23 hard decline.

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.