If the merchant uses a gateway or another partner that already offers the network token solution, it is necessary to send some specific parameters in the request to the Gateway de Pagamento so that the card network receives the token data.
Payment.CreditCard.Cryptogram: this is the token cryptogram generated by the card network for each transaction and associates the token with a specific transaction;Payment.IssuerTransactionId: this is the card network's identifier for transactions in a series of recurrences (stored credentials). Send thePayment.IssuerTransactionIdin each recurring MIT, because sending is mandatory: it allows the card brand and issuer to identify the previous CIT with that token.
Mastercard transactionsFor tokenized MIT transactions on the Mastercard card brand, you do not need to send the cryptogram, because the token was previously validated in the original CIT transaction. In other words:
- in CIT transactions, the cryptogram must be sent in the
Payment.CreditCard.Cryptogramfield;- in MIT transactions, the cryptogram must not be sent.
If the cryptogram is not sent, you must provide the
Payment.IssuerTransactionId.See more about CIT and MIT transactions at Transaction Initiator Indicator.
Warning
- Available only for Cielo, Rede, and Getnet.
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.
Check out the example request for using a card token with external integration:
Request
| Environment | Method | Endpoint |
|---|---|---|
| Sandbox | post | https://apisandbox.braspag.com.br/v2/Sales/ |
| Production | post | https://api.braspag.com.br/v2/Sales/ |
Header parameters
| Parameter | Description | Type | Size | Required |
|---|---|---|---|---|
| Content-Type | Media type accepted by the resource. | String | 40 | Yes |
| MerchantId | Store identifier in Cielo. | String | 36 | Yes |
| MerchantKey | Public key for dual authentication in Cielo. | String | 40 | Yes |
| RequestId | Request identifier, used when the store uses different servers for each GET/POST/PUT. | String | 36 | No |
Body Parameters
Check the standard credit card request to verify all mandatory fields. The table below presents the exclusive parameters for tokenization via external integration.
| Parameter | Type | Size | Required | Description |
|---|---|---|---|---|
Payment.CreditCard.CardNumber | Text | 19 | Yes | Token generated by the brand (DPAN). Indication that the CardNumber should be filled with the DPAN in case of brand tokenization |
Payment.CreditCard.CardNumberType | Text | -- | Conditional | This field supports the values PAN and DPAN.
|
Payment.CreditCard.Holder | Text | 25 | Yes | Buyer's Name printed on the card. |
Payment.CreditCard.Cryptogram | Text | 28 | Conditional | Cryptogram generated by the brand. Must be sent if tokenization is done by the brand (external integration). |
Payment.CreditCard.ExpirationDate | Text | 7 | Yes | Expiration date of the token generated by the brand. |
Payment.CreditCard.SecurityCode | Text | 4 | No | Security code printed on the back of the card - See Attachment. |
Payment.CreditCard.SaveCard | Boolean | No (Default false) | Boolean that identifies if the card will be saved to generate the CardToken. Learn more about Tokenization. | |
Payment.CreditCard.Brand | Text | 10 | Yes | Card brand (Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover / Hipercard). |
Must be sent if tokenization is done by the brand (external integration).
Example of the request
{
"MerchantOrderId": "Loja123456",
"Customer": {
"Name": "Comprador Teste",
"Email": "[email protected]",
"Birthdate": "1991-01-02",
"Address": {
"Street": "Rua Teste",
"Number": "123",
"Complement": "AP 123",
"ZipCode": "12345987",
"City": "Rio de Janeiro",
"State": "RJ",
"Country": "BRA"
},
"DeliveryAddress": {
"Street": "Rua Teste",
"Number": "123",
"Complement": "AP 123",
"ZipCode": "12345987",
"City": "Rio de Janeiro",
"State": "RJ",
"Country": "BRA"
}
},
"Payment": {
"Type": "CreditCard",
"Amount": 15700,
"Currency": "BRL",
"Country": "BRA",
"ServiceTaxAmount": 0,
"Installments": 1,
"Interest": "ByMerchant",
"Capture": true,
"Authenticate": false,
"SoftDescriptor": "123456789ABCD",
"CreditCard": {
"CardNumber": "1234123412341231",
"CardNumberType":"DPAN",
"Holder": "Teste Holder",
"Cryptogram": "abcdefghijklmnopqrstuvw==",
"ExpirationDate": "12/2030",
"SecurityCode": "123",
"SaveCard": "true",
"Brand": "Visa"
}
}
}Response
{
"MerchantOrderId": "Loja123456",
"Customer": {
"Name": "Comprador Teste",
"Identity":"11225468954",
"IdentityType":"CPF",
"Email": "[email protected]",
"Birthdate": "1991-01-02",
"Address": {
"Street": "Rua Teste",
"Number": "123",
"Complement": "AP 123",
"ZipCode": "12345987",
"City": "Rio de Janeiro",
"State": "RJ",
"Country": "BRA"
},
"DeliveryAddress": {
"Street": "Rua Teste",
"Number": "123",
"Complement": "AP 123",
"ZipCode": "12345987",
"City": "Rio de Janeiro",
"State": "RJ",
"Country": "BRA"
}
},
"Payment": {
"ServiceTaxAmount": 0,
"Installments": 1,
"Interest": "ByMerchant",
"Capture": true,
"Authenticate": false,
"CreditCard": {
"CardNumber": "455187******0183",
"Holder": "Teste Holder",
"ExpirationDate": "12/2030",
"SaveCard": true,
"CardToken": "d37bf475-307d-47be-b50a-8dcc38c5056c",
"Brand": "Visa"
},
"ProofOfSale": "674532",
"Tid": "0305020554239",
"AuthorizationCode": "123456",
"SoftDescriptor":"123456789ABCD",
"PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
"Type": "CreditCard",
"Amount": 15700,
"CapturedAmount": 15700,
"Country": "BRA",
"ExtraDataCollection": [],
"Status": 2,
"ReturnCode": "6",
"ReturnMessage": "Operation Successful",
"Links": [
{
"Method": "GET",
"Rel": "self",
"Href": "https://apisandbox.braspag.com.br/v2/sales/{PaymentId}"
},
{
"Method": "PUT",
"Rel": "void",
"Href": "https://apisandbox.braspag.com.br/v2/sales/{PaymentId}/void"
}
]
}
}Response property
| Parâmetro | Descrição | Tipo | Tamanho | Formato |
|---|---|---|---|---|
ProofOfSale | Authorization number, identical to NSU. | Text | 6 | Alphanumeric text |
Tid | Transaction ID at the acquirer. | Text | 20 | Alphanumeric text |
AuthorizationCode | Authorization code. | Text | 6 | Alphanumeric text |
SoftDescriptor | Text to be printed on the cardholder's bank statement - available only for VISA/MASTER - does not allow special characters | Text | 13 | Alphanumeric text |
PaymentId | Payment identification number, required for operations such as Query, Capture, and Cancellation. | GUID | 36 | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
ECI | Electronic Commerce Indicator. Represents how secure a transaction is. | Text | 2 | Example: 7 |
Status | Transaction Status. | Byte | 2 | |
ReturnCode | Acquirer return code. | Text | 32 | Alphanumeric text |
ReturnMessage | Acquirer return message. | Text | 512 | Alphanumeric text |
Cardtoken | Card identification token. | GUID | 36 | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
Payment.IssuerTransactionId | 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 IssuerTransactionId. | string | 30 | Alphanumeric text |
Payment.TransactionLinkId | Unique identifier (TLID) generated by Mastercard and returned in the response, used to link the CIT to subsequent MITs. For Mastercard, send the original TransactionLinkId together with IssuerTransactionId: both are mandatory, and sending the TransactionLinkId is mandatory starting Oct 23, 2026. See more details in Brand identifiers for Cielo acquirerFormat: 22 alphanumeric characters (A–Z, a–z), case-sensitive, and may include hyphens (-) and underscores ()._ | string | 22 | Alphanumeric text |