Create a debit transaction
| Environment | Method | Endpoint |
|---|---|---|
| Sandbox | post | https://apisandbox.braspag.com.br/v2/sales/ |
| Production | post | https://api.braspag.com.br/v2/sales/ |
Warning
- To validate if the authentication was accepted in the authorization response, consider the ECI outside the
Payment.ExternalAuthenticationnode.
For the Sandbox environment, use the value "Simulado" in the
Payment.Providerfield.
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.
3DS Authentication in debit card payments
- 3DS authentication is required for debit transactions. In a standard debit transaction (with authentication), send
Authenticate= "true"; - Provide the data received from the script output in the
Payment.ExternalAuthenticationnode; - For transactions with 3DS Data Only authentication, the
ExternalAuthentication.DataOnlyparameter must be send as true. - 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 (VerifyCard). See more details in IssuerTransactionId.
TLID Mastercard
The Transaction Link Identifier (TLID), sent and returned in the TransactionLinkId field, is a unique identifier generated by the Mastercard card brand during a CIT, used to link related MITs. The TLID applies to the VerifyCard response (response only) and to credit, debit, and recurring transactions.
For Mastercard, send IssuerTransactionId and TransactionLinkId together in MITs: both parameters are mandatory.
| Phase | Description |
|---|---|
| Phase 1 | Current. The TransactionLinkId field is available in the responses of VerifyCard by card number, 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 Oct 23, 2026. |
Scheduled recurrence: in subsequent transactions, the
IssuerTransactionIdandTransactionLinkIdfields are sent automatically.
The TransactionLinkId sent in the request must have exactly 22 characters (A-Z, a-z, 0-9, hyphen, and underscore). If the value is outside this format, Cielo ignores it without returning an error. When Cielo sends the TLID to the card brand, the response also includes SentTransactionLinkId, with the value that was sent. The VerifyCard request does not accept the field.
See more details in Brand identifiers for Cielo acquirer.
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 | Type | Syze |
|---|---|---|---|
| Transaction ID in the payment provider. | string | 40 |
| Sales receipt number, identical to the NSU (Unique Sequential Number). | string | 20 |
| Indicates which order number was sent to the acquirer.
| GUID | |
| Authorization code | string | 300 |
| Payment identifier field. | GUID | 36 |
| Date the transaction was received by Cielo. | string | 19 |
| API return code to indicate success or error in the operation. | string | 32 |
| Message corresponding to the | string | 512 |
| Transaction status. See the complete list of transaction status list. | byte | 2 |
| Code returned by the payment provider (acquirer or issuer). | string | 32 |
| Message returned by the payment provider (acquirer or issuer). | string | 512 |
| Brand return code that defines the retry period. Valid for Mastercard brand. Learn more at Merchant Advice Code (MAC) – Mastercard | string | 2 |
|
| string | 28 |
|
| string | 28 |
|
| integer | 1 |
| 3DS version used in the authentication process. | string | 1 |
| RequestID returned in the authentication process. | GUID | 36 |
| Transaction identifier generated by the card brand and returned in the CIT response. Store the value to send it in subsequent MITs: sending is mandatory, for all card brands, in recurring, incremental, and re-authorized transactions. See more details in Brand identifiers for Cielo acquirer. | string | 30 |
| Unique identifier (TLID) generated by Mastercard and returned in the response, used to link the CIT to subsequent MITs. For Mastercard, send the original | string | 22 |
| TLID that the merchant sent in the request and that Cielo forwarded to the card brand. The field only appears when Cielo sent the TLID. See more details in Brand identifiers for Cielo acquirer. | string | 22 |