Unscheduled recurrence

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

ℹ️
Learn more about this feature in the documentation.

post

Environment	Method	Endpoint
Sandbox	post	`https://apisandbox.cieloecommerce.cielo.com.br/1/sales/`
Production	post	`https://api.cieloecommerce.cielo.com.br/1/sales/`

Request

{
  "MerchantOrderId": "2014113245231706",
  "Customer":{  
      "Name":"Aline de Souza",
      "Email":"[email protected]",
      "Birthdate":"1990-01-01"
   },
  "Payment": {
    "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":"Unscheduled"
      }
    }
  }
}

{
  "MerchantOrderId": "Loja123456",
  "Customer":{  
      "Name":"Aline de Souza",
      "Email":"[email protected]",
      "Birthdate":"1990-01-01"
   },
  "Payment": {
    "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":"Unscheduled"
      }
    }
  }
}

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. 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 automatic 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":"Unscheduled"
          }
      },
      "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":"Unscheduled"
      }
    },
    "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"
      }
    ]
  }
}

⚠️
Warning:

Send the parameters in Payment.RecurrentPayment to create a Scheduled Recurrence;

Send the parameter Payment.Recurrent = “true” to create an Own Recurrence.