The example below shows how to use the Card on File feature when the card is being stored for the first time.
This process allows the card to be reused in future transactions, offering greater convenience and security for the user.
Learn more about this feature in the documentation.
| Environment | Method | Endpoint |
|---|---|---|
| Sandbox | post | https://apisandbox.braspag.com.br/v2/sales/ |
| Production | post | https://api.braspag.com.br/v2/sales/ |
Request
{
"MerchantOrderId":"2014111701",
"Customer":{
"Name":"Aline de Souza",
"Email":"[email protected]",
"Birthdate":"1990-01-01"
},
"Payment":{
"Provider":"Simulado",
"Type":"CreditCard",
"Amount":15700,
"Currency":"BRL",
"Country":"BRA",
"Installments":1,
"Capture":true,
"SoftDescriptor":"123456789ABCD",
"CreditCard":{
"CardNumber":"4091688625337641",
"Holder":"Teste Holder",
"ExpirationDate":"12/2035",
"SecurityCode":"333",
"SaveCard":"false",
"Brand":"Visa",
"CardOnFile":{
"Usage": "First"
}
}
}
}
| PROPERTY | TYPE | SIZE | REQUIRED | DESCRIPTION |
|---|---|---|---|---|
MerchantOrderId | Text | 50 | Yes | Order identification number. Warning: Allowed characters are a-z, A-Z, 0-9. Special characters and blank spaces are not allowed. |
Customer.Name | Text | 255 | No | Customer's name. Size: 255. Warning: Only a-z, A-Z characters are allowed. Special characters and numbers are not allowed. |
Customer.Status | Text | 255 | No | The customer’s registration status on the store. (NEW / EXISTING) |
Customer.Email | Text | 255 | No | Customer's email |
Customer.Birthdate | Date | 10 | No | Customer's birthdate (AAAA/MM/DD). |
Payment.Provider | Text | 15 | Yes | Name of payment method provider. |
Payment.Type | Text | 100 | Yes | Type of the Payment Method. |
Payment.Amount | Number | 15 | Yes | Order Amount (to be sent in cents). |
Payment.Currency | Text | 3 | No | Currency in which the payment will be made (BRL). |
Payment.Country | Text | 3 | No | Country in which the payment will be made. |
Payment.SoftDescriptor | Text | 13 | No | The store’s name that will be on the shopper’s bank invoice. Does not allow special characters. |
Payment.Installments | Number | 2 | Yes | Number of installments. If the transaction is a recurrence, the number of installments will be 1. For installment transactions, the number of installments will be greater than 1. |
Payment.Capture | Boolean | — | No (Default false) | Boolean that identifies if the authorization should be done by authomatic capture (true) or posterior capture (false). |
CreditCard.CardNumber | Text | 19 | Yes | Shopper’s card number. |
CreditCard.Holder | Text | 25 | Yes | Name of the shopper that’s printed on the card. Does not accept special characters. |
CreditCard.ExpirationDate | Text | 7 | Yes | Expiration date printed on the card. Example: MM/AAAA. |
CreditCard.SecurityCode | Text | 4 | No | Security code printed on the back of the card. |
CreditCard.SaveCard | Boolean | — | No (Default false) | Boolean that identifies if the card will be saved to generate a CardToken. Find out more about Tokenization of Cards |
CreditCard.Brand | Text | 10 | Yes | Card brand. Possible values: Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover / Hipercard / Hiper. |
CreditCard.CardOnFile.Usage | Text | - | No | "First" if the card was stored and it’s your first use. "Used" if the card was stored and has been used for another transaction before. |
Response
{
"MerchantOrderId": "2014111701",
"Customer":{
"Name":"Aline de Souza",
"Email":"[email protected]",
"Birthdate":"1990-01-01"
},
"Payment": {
"ServiceTaxAmount": 0,
"Installments": 1,
"Interest": 0,
"Capture": true,
"CreditCard": {
"CardNumber": "4091688625337641",
"Holder": "Teste Holder",
"ExpirationDate": "12/2035",
"SaveCard": false,
"Brand": "Visa",
"CardOnFile": {
"Usage": "First"
},
"PaymentAccountReference": "JZHOZJHNZH87KQXM3G60B9I21GVZN"
},
"Tid": "0928084922246",
"ProofOfSale": "652515",
"AuthorizationCode": "927181",
"SoftDescriptor": "123456789ABCD",
"Provider": "Simulado",
"IsQrCode": false,
"DynamicCurrencyConversion": false,
"Amount": 15700,
"ReceivedDate": "2022-09-28 08:49:22",
"CapturedAmount": 15700,
"CapturedDate": "2022-09-28 08:49:22",
"Status": 2,
"IsSplitted": false,
"ReturnMessage": "Operation Successful",
"ReturnCode": "6",
"PaymentId": "91bad53a-9198-4738-a280-f51dddc34988",
"Type": "CreditCard",
"Currency": "BRL",
"Country": "BRA",
"Links": [
{
"Method": "GET",
"Rel": "self",
"Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/91bad53a-9198-4738-a280-f51dddc34988"
},
{
"Method": "PUT",
"Rel": "void",
"Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/91bad53a-9198-4738-a280-f51dddc34988/void"
}
]
}
}
| PROPERTY | DESCRIPTION | TYPE | SIZE | FORMAT |
|---|---|---|---|---|
ProofOfSale | Authorization number, identical to NSU. | Text | 6 | Alphanumeric text |
Tid | Transaction Id on the acquirer. | Text | 20 | Alphanumeric text |
AuthorizationCode | Authorization code. | Text | 6 | Alphanumeric text |
SoftDescriptor | Text that will be printed on the carrier’s bank invoice. Does not allow special characters. | Text | 13 | Alphanumeric text |
PaymentId | Payment ID number, needed for future operations like Consulting, Capture and Cancellation. | Guid | 36 | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
ECI | Eletronic Commerce Indicator. Indicates how safe a transaction is. | Text | 2 | Example: 7 |
Status | Transaction status. | Byte | — | 2 |
ReturnCode | Acquiring return code. | Text | 32 | Alphanumeric text |
ReturnMessage | Acquiring return message. | Text | 512 | Alphanumeric text |
Payment.MerchantAdviceCode | Card brand’s return code that defines the period for transaction submission retry. Valid only for Mastercard. | Text | 2 | Numeric |
CreditCard.PaymentAccountReference | PAR (payment account reference) is the number that associates different tokens to the same card. It will be returned by the Master and Visa brands and passed on to Cielo e-commerce customers. If the card brand doesn’t send the information the field will not be returned. | Alphanumeric | 29 | — |