Ambiente | Método | Endpoint |
|---|---|---|
Sandbox | post |
|
Produção | post |
|
Alphanumeric CNPJs will be implemented by the Brazilian Federal Revenue Service in July 2026This change applies only to new registrations. There will be no changes to existing CNPJs.
The alphanumeric CNPJ is already supported by Cielo, with no changes required to your integration.
We recommend checking whether adjustments are needed in your merchant’s own checkout systems.
Warning
- In a standard debit card transaction (with authentication), send
Authenticate= "true". - Mastercard debit transactions with stored credentials: Mastercard requires the Transaction Initiation Indicator for credit and debit card purchases using stored card data. The goal is to indicate whether the transaction was initiated by the cardholder (Cardholder-Initiated Transaction - CIT) or by the merchant (Merchant-Initiated Transaction - MIT). In this scenario, it is mandatory to send the
InitiatedTransactionIndicatornode with theCategoryandSubCategoryparameters for Mastercard transactions, within thePaymentnode. Check the list of categories in theCategoryparameter description and the complete table of subcategories in Mastercard Transaction Initiation Indicator. - It is not possible to perform a transaction with an
Amount= 0. To verify if a card is valid, use Zero Auth. - To confirm if authentication was accepted in the authorization, check the ECI value returned in
Payment.Eci. The API replicates the ECI informed by the merchant in thePayment.ExternalAuthenticationfield. However, the value actually used by the brand in the authorization is the one shown inPayment.Eci.
ImportantThe validation and return of the
Payment.Ecifield occur only in the production environment at this initial stage.
Stored credential transaction identifiers
According to card brand rules, recurring transactions and those with stored credentials may require additional identification fields, such as IssuerTransactionId and TransactionLinkId. See more details below.
Card brand identifier: IssuerTransactionId
IssuerTransactionIdThe card brand identifier is an identification code for recurring or stored credential transactions, returned in the authorization response or in the card verification response (Zero Auth). See more details in IssuerTransactionId.
TLID Mastercard
The Transaction Link Identifier (TLID) is a unique identifier generated by the Mastercard card brand during a transaction. It is used to ensure continuity between related transactions.
| Phase | Description |
|---|---|
| Phase 1 | TransactionLinkId returns in the responses of card validation by Zero Auth, credit card payment creation, debit card payment creation, and in the query by PaymentId. |
| Phase 2 | Required inclusion of the TransactionLinkId in the request (MIT) starting October 10 2026. |
See more details in Card Brand Identifiers.
Cancellation guarantee
When a transaction returns with the status Not Finalized and the Void Guarantee feature is enabled for the merchant, do not reuse the same MerchantOrderID value in new transaction attempts.
For subsequent attempts, generate a new order identifier. Resubmitting a transaction using the same MerchantOrderID from an attempt that returned as Not Finalized can cause processing errors.
Debit card transaction response
Following table presents the main parameters that may be returned by the API when creating a debit card payment.
Property | Description | Type | Syze |
|---|---|---|---|
| Authorization number, identical to NSU | string | 6 |
| Acquirer transaction identifier | string | 20 |
| Authorization code | string | 6 |
| Payment identification number. | GUID | 36 |
| Transaction Status. See the complete table of transactional status. | byte | |
| Return code | string | 32 |
| Return message | string | 512 |
| Indicates which order number was sent to the acquirer.
| GUID | |
| Brand return code that defines the retry period. Valid only for Mastercard brand. Learn more about Merchant Advice Code (MAC) – Mastercard and card brands retry programs | string | 2 |
| Returns "true" if the Void Guarantee is enabled and an error occurs during authorization (status Not Finalized - "0"). | boolean | |
| PAR (Payment Account Reference) is the number that associates different tokens to the same card. It will be returned by Master and Visa card brands and passed on to Cielo e-commerce clients. If the card brand does not send the information, the field will not be returned. | string | 29 |
| Transaction identifier generated by the card brand; it must be sent to reference the original/previous transaction in related operations, such as recurring payments. See more details in IssuerTransactionId. | string | 30 |
|
| string | 22 |