The example below shows how to use the Card on File feature in a recurring transaction with installments, when the card has already been stored and used previously.
This type of transaction allows the total amount to be split into installments, while maintaining the convenience of recurring billing and the 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": "2014113245231706",
"Customer":{
"Name":"Aline de Souza",
"Email":"[email protected]",
"Birthdate":"1990-01-01"
},
"Payment": {
"Provider":"Simulado",
"Type": "CreditCard",
"Amount": 1500,
"Installments": 1,
"SoftDescriptor": "123456789ABCD",
"Recurrent": true,
"CreditCard": {
"CardNumber": "4091688625337641",
"Holder": "Teste Holder",
"ExpirationDate": "12/2035",
"SecurityCode": "333",
"SaveCard": "false",
"Brand": "Visa",
"CardOnFile":{
"Usage": "Used",
"Reason":"Installments"
}
}
}
}
{
"MerchantOrderId": "Loja123456",
"Customer":{
"Name":"Aline de Souza",
"Email":"[email protected]",
"Birthdate":"1990-01-01"
},
"Payment": {
"Provider":"Simulado",
"Type": "CreditCard",
"Amount": 1500,
"Installments": 1,
"SoftDescriptor": "123456789ABCD",
"Capture": "false",
"RecurrentPayment": {
"AuthorizeNow": "true",
"EndDate": "2030-12-01",
"Interval": "Monthly"
},
"CreditCard": {
"CardNumber": "4091688625337641",
"Holder": "Teste Holder",
"ExpirationDate": "12/2035",
"SecurityCode": "333",
"SaveCard": "false",
"Brand": "Visa",
"CardOnFile":{
"Usage": "Used",
"Reason":"Installments"
}
}
}
}
| 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.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). |
Payment.Recurrent | Boolean | 5 | Yes*| | Indicates that a transaction is own recurrence. ⚠️ Required for own recurrence. |
RecurrentPayment.AuthorizeNow | Boolean | - | Yes | Boolean to know if the first recurrence will already be authorized or not. ⚠️For scheduled recursion, send AuthorizeNow = true.. |
RecurrentPayment.EndDate | Text | 10 | Yes*| | End date of the recurring charge. Format: 12/2030 (MM/YYYY).`` ⚠️ Required for scheduled recurrence. |
RecurrentPayment.Interval | Text | 10 | Yes*| | Recurrence interval: Monthly (monthly is the standard) Bimonthly Quarterly SemiAnnual (half-yearly) Annual_. ⚠️ Required for scheduled recurrence. |
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. |
CreditCard.CardOnFile.Reason | Text | - | Conditional | Indicates the motive for card storage, if the "Usage" field is "Used". Recurring - Programmed recurring transaction (e.g. Subscriptions). If it is a recurring transaction, use Payment.Recurrent = true (merchant recurrence) or Recurrent.Payment = true (scheduled recurrence). Unscheduled - Recurring transaction with no fixed date (e.g. service apps) Installments - Installments through recurring transactions. |
Response
{
"MerchantOrderId": "2014113245231706",
"Customer":{
"Name":"Aline de Souza",
"Email":"[email protected]",
"Birthdate":"1990-01-01"
},
"Payment": {
"ServiceTaxAmount": 0,
"Installments": 1,
"Interest": "ByMerchant",
"Capture": false,
"Authenticate": false,
"Recurrent": true,
"CreditCard": {
"CardNumber": "4091688625337641",
"Holder": "Teste Holder",
"ExpirationDate": "12/2035",
"SaveCard": false,
"Brand": "Visa",
"CardOnFile":{
"Usage": "Used",
"Reason":"Installments"
}
},
"ProofOfSale": "3827556",
"Tid": "0504043827555",
"AuthorizationCode": "149867",
"SoftDescriptor":"123456789ABCD",
"PaymentId": "737a8d9a-88fe-4f74-931f-acf81149f4a0",
"Type": "CreditCard",
"Amount": 1500,
"Currency": "BRL",
"Country": "BRA",
"Provider": "Simulado",
"ExtraDataCollection": [],
"Status": 1,
"ReturnCode": "4",
"ReturnMessage": "Operation Successful",
"Link": {
"Method": "GET",
"Rel": "recurrentPayment",
"Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}"
},
"AuthorizeNow": true
},
"Links": [
{
"Method": "GET",
"Rel": "self",
"Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
},
{
"Method": "PUT",
"Rel": "capture",
"Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
},
{
"Method": "PUT",
"Rel": "void",
"Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
}
]
}
{
"MerchantOrderId": "Loja123456",
"Customer":{
"Name":"Aline de Souza",
"Email":"[email protected]",
"Birthdate":"1990-01-01"
},
"Payment": {
"ServiceTaxAmount": 0,
"Installments": 1,
"Interest": "ByMerchant",
"Capture": false,
"Authenticate": false,
"Recurrent": false,
"CreditCard": {
"CardNumber": "4091688625337641",
"Holder": "Teste Holder",
"ExpirationDate": "12/2035",
"SaveCard": false,
"Brand": "Visa",
"CardOnFile":{
"Usage": "Used",
"Reason":"Installments"
}
},
"ProofOfSale": "3827556",
"Tid": "0504043827555",
"AuthorizationCode": "149867",
"SoftDescriptor": "123456789ABCD",
"PaymentId": "737a8d9a-88fe-4f74-931f-acf81149f4a0",
"Type": "CreditCard",
"Amount": 1500,
"Currency": "BRL",
"Country": "BRA",
"Provider": "Simulado",
"ExtraDataCollection": [],
"Status": 1,
"ReturnCode": "4",
"ReturnMessage": "Operation Successful",
"RecurrentPayment": {
"RecurrentPaymentId": "61e5bd30-ec11-44b3-ba0a-56fbbc8274c5",
"NextRecurrency": "2015-11-04",
"EndDate": "2019-12-01",
"Interval": "SemiAnnual",
"Link": {
"Method": "GET",
"Rel": "recurrentPayment",
"Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{RecurrentPaymentId}"
},
"AuthorizeNow": true
},
"Links": [
{
"Method": "GET",
"Rel": "self",
"Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
},
{
"Method": "PUT",
"Rel": "capture",
"Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/capture"
},
{
"Method": "PUT",
"Rel": "void",
"Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/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 |
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 | — |
RecurrentPaymentId | Next recurrence Identifier field. | Guid | 36 | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
NextRecurrency | Date of next recurrence. | Text | 7 | 12/2030 (MM/YYYY) |
EndDate | End date of recurrence. | Text | 7 | 12/2030 (MM/YYYY) |
Interval | Interval between recurrences. | Text | 10 | Monthly Bimonthly Quarterly SemiAnnual Annual |
AuthorizeNow | Boolean to know if the first recurrence is about to be Authorized or not. | Boolean | - | true ou false |
Warning:
- Send the parameters in
Payment.RecurrentPaymentto create a Scheduled Recurrence;- Send the parameter
Payment.Recurrent=“true” to create an Own Recurrence;- For the Mastercard and Hipercard brands, it is necessary to send the
Payment.InitiatedTransactionIndicatornode to indicate the transaction initiator.