Agendar recorrência programada

post

É possível criar uma recorrência programada que não autoriza a transação imediatamente, mas sim agenda uma transação futura. Essa ação é chamada de agendar recorrência, e tem duas características:

Para não autorizar a transação no momento em que é criada, envie AuthorizeNow como “false”;
Envie o parâmetro StartDate, que determina a data de início da cobrança recorrente.

ℹ️
Ao configurar uma recorrência com uma data de início (StartDate) anterior à data atual, o sistema realizará cobranças retroativas diárias, uma para cada pagamento pendente até a data atual. Esse processo continua até que a próxima data de cobrança seja futura.

ℹ️
Antes de agendar uma recorrência programada, use o Zero Auth para validar o cartão. Desta forma, você garante que está agendando a recorrência com um cartão válido.

Meio de pagamento aceito: cartão de crédito.

⚠️
Identificação de transações oriundas de link de pagamento para cartões da bandeira Elo
A partir de 17 de outubro de 2025 será obrigatório identificar transações oriundas de link de pagamento para cartões da bandeira Elo. Envie o parâmetro Payment.SolutionType = "ExternalLinkPay".

Requisiçã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`

{
    "MerchantOrderId": "2014113245231706",
    "Customer": {
        "Name": "Comprador rec programada",
        "Identity": "12345678909",
        "IdentityType": "CPF",
        "Email": "[email protected]",
        "Birthdate": "1990-01-01",
        "Address": {
            "Street": "Rua das Rosas",
            "Number": "123",
            "Complement": "apartamento 101",
            "ZipCode": "12345987",
            "City": "São Paulo",
            "State": "SP",
            "Country": "BRA",
            "District": "Jardim das Flores",
            "AddressType": 0
        },
        "DeliveryAddress": {
            "Street": "Rua das Rosas",
            "Number": "123",
            "Complement": "apartamento 101",
            "ZipCode": "12345987",
            "City": "São Paulo",
            "State": "SP",
            "Country": "BRA",
            "District": "Jardim das Flores",
            "AddressType": 0
        }
    },
    "Payment": {
    "Type": "CreditCard",
    "Amount": 1500,
    "Installments": 1,
    "SoftDescriptor": "123456789ABCD",
    "SolutionType": "ExternalLinkPay",
    "RecurrentPayment": {
      "AuthorizeNow": "false",
      "EndDate": "2030-12-01",
      "Interval": "SemiAnnual",
      "StartDate": "2025-12-01"
    },
    "CreditCard": {
      "CardNumber": "1234123412341231",
      "Holder": "Teste Holder",
      "ExpirationDate": "12/2030",
      "SecurityCode": "262",
      "Brand": "Visa"
    }
  }
}

curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--header "MerchantKey: 0123456789012345678901234567890123456789"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
   "MerchantOrderId":"2014113245231706",
   "Customer":{
      "Name":"Comprador rec programada"
   },
   "Payment":{
     "Type":"CreditCard",
     "Amount":1500,
     "Installments":1,
     "SoftDescriptor":"123456789ABCD",
     "RecurrentPayment":{
       "AuthorizeNow":"false",
       "EndDate":"2019-12-01",
       "Interval":"SemiAnnual",
       "StartDate":"2015-06-01"
     },
     "CreditCard":{
         "CardNumber":"1234123412341231",
         "Holder":"Teste Holder",
         "ExpirationDate":"12/2030",
         "SecurityCode":"262",
         "Brand":"Visa"
     }
   }
}
--verbose

Parâmetros no header

Propriedade	Descrição	Tipo	Tamanho	Obrigatório
`MerchantId`	Identificador da loja na API E-commerce Cielo.	GUID	36	Sim
`MerchantKey`	Chave pública para autenticação dupla na API E-commerce Cielo.	string	40	Sim
`RequestId`	Identificador da requisição, usado quando a loja usa diferentes servidores para cada GET/POST/PUT.	GUID	36	Não

Parâmetros no body

Propriedade	Descrição	Tipo	Tamanho	Obrigatório
`MerchantOrderId`	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.	String	50	Sim
`Customer.Name`	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.	String	255	Sim
`Payment.Type`	Tipo do Meio de Pagamento.	String	100	Sim
`Payment.Amount`	Valor do Pedido (ser enviado em centavos).	Número	15	Sim
`Payment.Installments`	Número de parcelas. Como se trata de uma recorrência, o número de parcelas será 1.	Número	2	Sim
`Payment.SoftDescriptor`	Texto que será impresso na fatura bancaria do portador - Disponivel apenas para VISA/MASTER - não permite caracteres especiais	String	13	Não
`Payment.RecurrentPayment.AuthorizeNow`	Booleano que indica se a primeira recorrência já vai ser autorizada ou não. Para agendar uma recorrência, envie como "true".	Boolean		Sim
`Payment.RecurrentPayment.StartDate`	Data de início da recorrência.	Boolean		Sim
`Payment.RecurrentPayment.EndDate`	Data para término da recorrência.	String	10	Não
`Payment.RecurrentPayment.Interval`	Intervalo da recorrência. Monthly (mensal, é o padrão) Bimonthly (bimensal) Quarterly (trimestral) SemiAnnual (semestral) Annual (anual)	String	10	Não
`Payment.SolutionType`	Origem do pagamento. Obrigatório para transação de cartão da bandeira Elo oriunda de link de pagamento. Enviar como "ExternalLinkPay".	String	15	Não
`CreditCard.CardNumber`	Número do Cartão do Comprador.	String	19	Sim
`CreditCard.Holder`	Nome do Comprador impresso no cartão.	String	25	Sim
`CreditCard.ExpirationDate`	Data de validade impresso no cartão.	String	7	Sim
`CreditCard.SecurityCode`	Código de segurança impresso no verso do cartão.	String	4	Não
`CreditCard.Brand`	Bandeira do cartão.	String	10	Sim

Resposta

{
    "MerchantOrderId": "2014113245231706",
    "Customer": {
        "Name": "Comprador rec programada",
        "Identity": "12345678909",
        "IdentityType": "CPF",
        "Email": "[email protected]",
        "Birthdate": "1990-01-01",
        "Address": {
            "Street": "Rua das Rosas",
            "Number": "123",
            "Complement": "apartamento 101",
            "ZipCode": "12345987",
            "City": "São Paulo",
            "State": "SP",
            "Country": "BRA",
            "District": "Jardim das Flores",
            "AddressType": 0
        },
        "DeliveryAddress": {
            "Street": "Rua das Rosas",
            "Number": "123",
            "Complement": "apartamento 101",
            "ZipCode": "12345987",
            "City": "São Paulo",
            "State": "SP",
            "Country": "BRA",
            "District": "Jardim das Flores",
            "AddressType": 0
        }
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": 0,
        "Capture": false,
        "Authenticate": false,
        "Recurrent": false,
        "SolutionType": "ExternalLinkPay",
        "CreditCard": {
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa"
        },
        "SoftDescriptor": "123456789ABCD",
        "Provider": "Simulado",
        "IsQrCode": false,
        "RecurrentPayment": {
            "ReasonCode": 7,
            "ReasonMessage": "Denied",
            "StartDate": "2025-12-01",
            "EndDate": "2030-12-01",
            "Interval": 6,
            "AuthorizeNow": false
        },
        "Amount": 1500,
        "Status": 13,
        "IsSplitted": false,
        "Type": "CreditCard",
        "Currency": "BRL",
        "Country": "BRA"
    }
}

--header "Content-Type: application/json"
--header "RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
--data-binary
{
    "MerchantOrderId": "2014113245231706",
    "Customer": {
        "Name": "Comprador rec programada"
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": false,
        "Authenticate": false,
        "Recurrent": false,
        "CreditCard": {
            "CardNumber": "123412******1231",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": false,
            "Brand": "Visa"
        },
        "SoftDescriptor":"123456789ABCD",
        "Type": "CreditCard",
        "Amount": 1500,
        "Currency": "BRL",
        "Country": "BRA",
        "Provider": "Simulado",
        "ExtraDataCollection": [],
        "Status": 20,
        "RecurrentPayment": {
            "RecurrentPaymentId": "0d2ff85e-594c-47b9-ad27-bb645a103db4",
            "NextRecurrency": "2015-06-01",
            "StartDate": "2015-06-01",
            "EndDate": "2019-12-01",
            "Interval": "SemiAnnual",
            "Link": {
                "Method": "GET",
                "Rel": "recurrentPayment",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/RecurrentPayment/{PaymentId}"
            },
            "AuthorizeNow": false
        }
    }
}

Propriedade	Descrição	Tipo	Tamanho	Formato
`RecurrentPaymentId`	Campo identificador da recorrência.	GUID	36	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
`NextRecurrency`	Data da próxima recorrência.	String	7	12/2030 (MM/YYYY)
`StartDate`	Data do início da recorrência.	String	7	12/2030 (MM/YYYY)
`EndDate`	Data do fim da recorrência.	String	7	12/2030 (MM/YYYY)
`Interval`	Intervalo entre as recorrências.	Número	10	- Monthly (mensal, é o padrão) - Bimonthly (bimensal) - Quarterly (trimestral) - SemiAnnual (semestral) - Annual (anual)
`AuthorizeNow`	Booleano para saber se a primeira recorrência já vai ser autorizada ou se será apenas agendada.	Boolean	***	false