Criar QR Code para recorrência com Pix Automático

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

A API E-commerce Cielo oferece duas jornadas de autorização possíveis para o Pix Automático. A loja deverá determinar qual jornada irá aplicar para cada venda:

Criar QR Code para confirmação do Pix Automático: nessa opção, o comprador irá ler o QR Code para confirmar a autorização de uma série de cobranças de Pix Automático para o futuro. Não há cobrança nesse momento.

Quando há apenas a confirmação do Pix Automático, é necessário indicar que não haverá cobrança no momento da criação do QR Code com Payment.RecurrentPayment.AuthorizeNow = false.

Criar QR Code com pagamento imediato e confirmação do Pix Automático: nessa opção, o comprador irá ler o QR Code, realizar o pagamento imediato da primeira cobrança e confirmar a autorização para uma série de cobranças de Pix Automático para o futuro.

Indicar que a primeira cobrança será realizada no momento da criação do QR Code com Payment.RecurrentPayment.AuthorizeNow = true.

Requisição

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

{
    "MerchantOrderId": "1234567890",
    "OrderDescription": "Academia",
    "Customer": {
        "Name": "Aline de Souza",
        "Identity": "123...",
        "IdentityType": "CPF"
    },
    "Payment": {
        "Type": "Pix",
        "Amount": 100,
        "Provider": "Cielo2",
        "RecurrentPayment": {
            "RecurrentType": "SelfManagedConsent",
            "AuthorizeNow": true,
            "StartDate": "2025-01-01",
            "EndDate": "2030-12-31",
            "Interval": "Monthly",
            "RetryPolicy": "Allowed_3R_7D",
            "Amount": 200,
            "MinimumAmount": 100,
            "Plan": "Convênio"
        }     
    }
}

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

Parâmetro	Descrição	Tipo	Tamanho	Obrigatório?
`MerchantOrderId`	Número de identificação do pedido. O `MerchantOrderId` será encaminhado para o provedor de Pix como o número do contrato de recorrência, ou código que representa a autorização. 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	35	Sim
`OrderDescription`	É a descrição do objeto a ser contratado de forma recorrente. Ex.: serviço de streaming, matrícula de academia, conta recorrente de energia elétrica etc.	string	35	Não
`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	140	Sim
`Customer.Identity`	Número do CPF ou CNPJ do comprador.	enum	-	Sim
`Customer.IdentityType`	Tipo de documento de identificação do comprador (CPF ou CNPJ).	string	14	Sim
`Payment.Type`	Tipo do meio de pagamento. Neste caso, use "Pix".	enum	-	Sim
`Payment.Amount`	Valor do pedido. Condicional: envie somente quando há uma cobrança no momento da confirmação da recorrência.	number	15	Condicional
`Payment.Provider`	Nome do provedor do meio de pagamento. Neste caso, use "Cielo2".	enum	-	Sim
`Payment.RecurrentPayment.RecurrenceType`	Identificador do tipo de recorrência. Neste caso, use "SelfManagedConsent".	enum	-	Sim
`Payment.RecurrentPayment.AuthorizeNow`	Indica se é uma recorrência com cobrança inicial ("true") ou não ("false"). Neste caso, use "false".	boolean	-	Sim
`Payment.RecurrentPayment.StartDate`	Data da primeira cobrança da recorrência. Formato: 2030-12-31 (YYYY-MM-DD).	date	10	Sim
`Payment.RecurrentPayment.EndDate`	Data para término da recorrência. Se não for enviado, a recorrência será cobrada até ser cancelada. Formato: 2030-12-31 (YYYY-MM-DD).	date	10	Não
`Payment.RecurrentPayment.Interval`	Intervalo da recorrência. Valores possíveis: Weekly (semanal) Monthly (mensal) Quarterly (trimestral) SemiAnnual (semestral) Annual (anual)	enum	10	Sim
`Payment.RecurrentPayment.RetryPolicy`	Indica se permitirá retentativa da cobrança. Valores possíveis: - NotAllowed: não permite retentativa no caso de falha na cobrança; - Allowed_3R_7D: permite três retentativas durante sete dias conforme regras do BACEN.	enum	-	Sim
`Payment.RecurrentPayment.Amount`	Valor fixo da cobrança recorrente. Condicional: envie apenas quando o valor não está sujeito a alteração por toda a duração da recorrência.	number	-	Condicional
`Payment.RecurrentPayment.MinimumAmount`	É o valor mínimo de cobrança definido para loja. Se o comprador atribuir um valor máximo para as cobranças recorrentes, esse valor não poderá ser inferior ao valor mínimo definido neste campo. Não pode ser enviado em recorrências de valor fixo, ou seja, quando `Payment.RecurrentPayment.Amount` for informado	number	-	Opcional e condicional
`Payment.RecurrentPayment.Plan`	Convênio entre usuário pagador e recebedor, se houver.	string	60	Não

Resposta

{
    "MerchantOrderId": "1234567890",
    "Customer": {
        "Name": "Aline de Souza",
        "Identity": "123...",
        "IdentityType": "CPF"
    },
    "Payment": {
        "QrCodeBase64Image": "iVBORw0...",
        "QrCodeString": "00020101021226180014br.gov.bcb.pix5204000053039865802BR5903PIX6009SAO PAULO62070503***80910014br.gov.bcb.pix2569qrcodes-h.cielo.com.br/qr-pix/v1/rec/656b234637e24e81b2d09b9a6dedbcc8630485E1",
        "SentOrderId": "cbf1e8988ba9451bbba31d0e77d7d5f2",
        "RecurrentPayment": {
            "RecurrenceType": "SelfManagedConsent",
            "Amount": 200,
            "MinimumAmount": 100,
            "RetryPolicy": "Allowed_3R_7D",
            "Plan": "Convênio",
            "RecurrenceId": "13cb0f47-bfe2-4857-be36-f098be07f0b5",
            "ReasonCode": 0,
            "ReasonMessage": "OPERACAO REALIZADA COM SUCESSO",
            "StartDate": "2025-01-01",
            "EndDate": "2026-12-31",
            "Interval": "Monthly",
            "AuthorizeNow": true
        },
        "Amount": 100,
        "ReceivedDate": "2025-08-01 10:07:12",
        "Provider": "Cielo2",
        "Status": 12,
        "IsSplitted": false,
        "ReturnMessage": "OPERACAO REALIZADA COM SUCESSO",
        "ReturnCode": "0",
        "PaymentId": "cbf1e898-8ba9-451b-bba3-1d0e77d7d5f2",
        "Type": "Pix",
        "Currency": "BRL",
        "Country": "BRA",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/cbf1e898-8ba9-451b-bba3-1d0e77d7d5f2"
            }
        ]
    },
    "OrderDescription": "Academia"
}

O Pix Automático não tem ambiente sandbox disponível no momento.

A resposta segue o padrão para as respostas de criação de QRCode da API E-commerce Cielo, com destaque para os parâmetros a seguir:

Parâmetro	Descrição	Tipo
`Payment.QrCodeString`	QR Code composto pela recorrência, com ou sem o pagamento inicial.	string
`Payment.QrCodeStringBase64`	Representa a imagem do QR Code composto pela recorrência	string
`Payment.RecurrentPayment.RecurrenceId`	Identificador da recorrência, retornado pela API no momento da criação do QR Code do Pix Automático. Importante: salve o `Payment.RecurrentPayment.RecurrenceId`, porque será usado posteriormente na criação das cobranças recorrentes.	string
`Payment.PaymentId`	Identificador do pagamento, só será retornado se houver cobrança inicial, ou seja, se `Payment.RecurrentPayment.AuthorizeNow` = true.	string