Recorrência

O exemplo abaixo mostra como utilizar a funcionalidade Card on File em uma transação recorrente, quando o cartão já foi armazenado e utilizado anteriormente.

ℹ️
Saiba mais sobre essa funcionalidade na documentação.

Ambiente	Método	Endpoint
Sandbox	post	`https://apisandbox.cieloecommerce.cielo.com.br/1/sales`
Produção	post	`https://api.cieloecommerce.cielo.com.br/1/sales`

Requisição

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

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

PROPRIEDADE	TIPO	TAMANHO	OBRIGATÓRIO	DESCRIÇÃO
`MerchantOrderId`	Texto	50	Sim	Número de identificação do pedido. Atenção: Os caracteres permitidos são apenas a-z, A-Z, 0-9. Não são permitidos caracteres especiais e espaços em branco.
`Customer.Name`	Texto	255	Não	Nome do comprador. Atenção: Os caracteres permitidos são apenas a-z, A-Z. Não são permitidos caracteres especiais e números.
`Customer.Email`	Texto	255	Não	E-mail do comprador.
`Customer.Birthdate`	Date	10	Não	Data de nascimento do comprador (AAAA/MM/DD).
`Payment.Type`	Texto	100	Sim	Tipo do meio de pagamento.
`Payment.Amount`	Número	15	Sim	Valor do pedido (ser enviado em centavos).
`Payment.Currency`	Texto	3	Não	Moeda na qual o pagamento será feito (BRL).
`Payment.Country`	Texto	3	Não	País na qual o pagamento será feito.
`Payment.Installments`	Número	2	Sim	Número de parcelas. Se a transação for uma recorrência, o número de parcelas será 1. Para transações parceladas, o número de parcelas será sempre maior que 1.
`Payment.Capture`	Booleano		Não (Default false)	Booleano que identifica que a autorização deve ser com captura automática (“true”) ou captura posterior (“false”).
`Payment.SoftDescriptor`	Texto	13	Não	O complemento do nome da loja que aparecerá na fatura do cartão. Não permite caracteres especiais.
`Payment.Recurrent`	Booleano	5	Sim* \|	Indica que uma transação é de recorrência própria. ⚠️Obrigatório para recorrência própria.
`RecurrentPayment.AuthorizeNow`	Booleano		Sim	Booleano para saber se a primeira recorrência já vai ser autorizada ou não. ⚠️Para recorrência programada, envie`AuthorizeNow` = true..
`RecurrentPayment.EndDate`	Texto	10	Sim* \|	Data para término da cobrança recorrente. Formato: 12/2030 (MM/YYYY). ⚠️Obrigatório para recorrência programada.
`RecurrentPayment.Interval`	Texto	10	Sim* \|	Intervalo da recorrência: Monthly (mensal, é o padrão) Bimonthly (bimestral) Quarterly (trimestral) SemiAnnual_ (semestral) Annual_ (anual). ⚠️Obrigatório para recorrência programada.
`CreditCard.CardNumber`	Texto	19	Sim	Número do cartão do comprador.
`CreditCard.Holder`	Texto	25	Sim	Nome do comprador impresso no cartão. Não aceita caracteres especiais ou acentuação.
`CreditCard.ExpirationDate`	Texto	7	Sim	Data de validade impressa no cartão. Ex. MM/AAAA.
`CreditCard.SecurityCode`	Texto	4	Não	Código de segurança impresso no verso do cartão.
`CreditCard.SaveCard`	Booleano		Não (Default false)	Booleano que identifica se o cartão será salvo para gerar o `CardToken`. Saiba mais sobre Tokenização
`CreditCard.Brand`	Texto	10	Sim	Bandeira do cartão. Valores possíveis: Visa / Master / Amex / Elo / Aura / JCB / Dinners / Discover.
`CreditCard.CardOnFile.Usage`	Texto		Não	"First" se o cartão foi armazenado e é seu primeiro uso. "Used" se o cartão foi armazenado e ele já foi utilizado anteriormente em outra transação
`CreditCard.CardOnFile.Reason`	Texto		Condicional	Indica o propósito de armazenamento de cartões, caso o campo CardOnFile.Usage for “Used”. Recurring: *compra recorrente programada (ex. assinaturas). Se for transação recorrente, usar Payment.Recurrent = true (recorrência própria) ou Recurrent.Payment = true (recorrência programada). Unscheduled: compra recorrente sem agendamento (ex. aplicativos de serviços). Installments:* parcelamento através da recorrência.

Resposta

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

Propriedade	Descrição	Tipo	Tamanho
`ProofOfSale`	Número da autorização, idêntico ao NSU.	string	6
`Tid`	Identificador da transação na adquirente.	string	20
`AuthorizationCode`	Código de autorização.	string	6
`PaymentId`	Número de identificação do pagamento. O `PaymentId` será usado em futuras operações como consulta, captura e cancelamento.	GUID	36
`Status`	Status da Transação. Veja a tabela completa de Status transacional	byte
`ReturnCode`	Código de retorno. Veja a tabela completa de ReturnCode	string	32
`ReturnMessage`	Mensagem de retorno. Veja a tabela completa de ReturnMessage	string	512
`Payment.MerchantAdviceCode`	Código de retorno da bandeira que define período para retentativa. Válido somente para bandeira Mastercard. Saiba mais Programa de retentativa das bandeiras para Mastercard	string	2
`Payment.CreditCard.PaymentAccountReference`	O PAR (Payment Account Reference) é o número que associa diferentes tokens a um mesmo cartão. Será retornado pelas bandeiras Master e Visa e repassado para os clientes do e-commerce Cielo. Caso a bandeira não envie a informação, o campo não será retornado.	string	29
`RecurrentPaymentId`	Campo Identificador da próxima recorrência.	GUID	36
`NextRecurrency`	Data da próxima recorrência.	string	7
`EndDate`	Data de término da recorrência.	string	7
`Interval`	Intervalo entre as recorrências.	integer	10
`AuthorizeNow`	Booleano para saber se a primeira recorrência já vai ser autorizada ou não.	boolean

⚠️
Atenção:

Envie os parâmetros em Payment.RecurrentPayment para criar uma Recorrência Programada;

Envie o parâmetro Payment.Recurrent= "true" para criar uma Recorrência Própria;

Para a bandeira Mastercard é necessário enviar o nó Payment.InitiatedTransactionIndicator para indicar o iniciador de transação.