Recurrence

The example below shows how to use the Card on File feature in a recurring transaction, when the card has already been stored and used previously.

ℹ️
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":"Recurring"
      }
    }
  }
}

{
  "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":"Recurring"
      }
    }
  }
}

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.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 / Dinners / 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":"Recurring"
          }
      },
      "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/1/RecurrentPayment/`{RecurrentPaymentId}`"
          },
          "AuthorizeNow": true
      },
      "Links": [
          {
              "Method": "GET",
              "Rel": "self",
              "Href": "https://apiquerysandbox.cieloecommerce.cielo.com/1/sales/`{PaymentId}`"
          },
          {
              "Method": "PUT",
              "Rel": "capture",
              "Href": "https://apiquerysandbox.cieloecommerce.cielo.com/1/sales/`{PaymentId}`/capture"
          },
          {
              "Method": "PUT",
              "Rel": "void",
              "Href": "https://apiquerysandbox.cieloecommerce.cielo.com/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":"Recurring"
      }
    },
    "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/1/RecurrentPayment/`{RecurrentPaymentId}`"
      },
      "AuthorizeNow": true
    },
    "Links": [
      {
        "Method": "GET",
        "Rel": "self",
        "Href": "https://apiquerysandbox.cieloecommerce.cielo.com/1/sales/`{PaymentId}`"
      },
      {
        "Method": "PUT",
        "Rel": "capture",
        "Href": "https://apiquerysandbox.cieloecommerce.cielo.com/1/sales/`{PaymentId}`/capture"
      },
      {
        "Method": "PUT",
        "Rel": "void",
        "Href": "https://apiquerysandbox.cieloecommerce.cielo.com/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
`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	—
`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.RecurrentPayment to 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.InitiatedTransactionIndicator node to indicate the transaction initiator.