Criar pagamento com QR Code Pix

Válido para a integração com o provedor "Cielo2".

✅
Essa é a nova integração Pix que você deve seguir a partir de 01/09.

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

ℹ️
CNPJs alfanuméricos serão implementados pela Receita Federal em julho de 2026
Essa mudança afeta apenas novas inscrições, não havendo mudanças em CNPJs existentes.
O CNPJ alfanumérico já está sendo suportado pela Cielo, sem mudanças na sua integração.
Recomendamos verificar a necessidade de possíveis ajustes nos sistemas próprios de checkout de sua loja.

Para gerar um QR code Pix através da API E-commerce Cielo, faça a integração conforme a especificação a seguir.

O campo obrigatório Payment.Type deve ser enviado como "Pix". A resposta da requisição irá retornar o código base64 da imagem do QR Code Pix, que a loja deverá disponibilizar ao comprador.

⚠️
O tempo de expiração máximo do QR Code Pix pela Cielo é 24 horas. Esse tempo de expiração pode ser alterado no campo Payment.QrCode.Expiration.

Requisição

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

{
    "MerchantOrderId": "123456789asdf",
    "Customer": {
        "Name": "Aline de Souza",
        "Identity": "066...",
        "IdentityType": "CPF"
    },
    "Payment": {
        "Type": "Pix",
        "Provider": "Cielo2",
        "Amount": 100,
        "QrCode": {
            "Expiration": 86400
        }
    }
}

Parâmetros do cabeçalho

Parâmetros do corpo

Campo	Tipo	Descrição
`MerchantOrderId`	string	Número de identificação do pedido. Caracteres especiais não são permitidos. Tamanho: 25
`Customer.Name`	string	Nome do comprador. Tamanho: 255.
`Customer.Identity`	string	Número do CPF ou CNPJ do comprador. Tamanho: 14. Permite envio de CNPJs alfanuméricos.
`Payment.Type`	string	Tipo do meio de pagamento. Neste caso, insira “Pix”. Tamanho: 15.
`Payment.Provider`	string	Nome do provedor do meio de pagamento. Neste caso, “Cielo2”.
`Payment.Amount`	number	Valor do pedido, em centavos.
`Payment.QrCode`	object	Objeto contendo informações adicionais para o QR Code.
`Payment.QrCode.Expiration`	number	Tempo de expiração do QR Code, em segundos. (Ex: 30 minutos = 1800). O envio é opcional. Caso não seja informado, o valor padrão será 86400 segundos (24 horas).

Resposta

{
    "MerchantOrderId": "********************************",
    "Customer": {
        "Name": "Aline de Souza",
        "Identity": "066....",
        "IdentityType": "CPF"
    },
    "Payment": {
        "QrCode": {
            "Expiration": 86400
        },
        "QrCodeBase64Image": "iVBg3[...]",
        "QrCodeString": "00020[...]",
        "SentOrderId": "********************************",
        "Amount": 100,
        "ReceivedDate": "2024-11-28 16:29:52",
        "Provider": "Cielo2",
        "Status": 12,
        "IsSplitted": false,
        "ReturnMessage": "QRCode gerado com sucesso",
        "ReturnCode": "0",
        "PaymentId": "********-****-****-****-************",
        "Type": "Pix",
        "Currency": "BRL",
        "Country": "BRA",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/********-****-****-****-************"
            }
        ]
    }
}

Parâmetros da resposta

A tabela a seguir apresenta os principais parâmetros que podem ser retornados pela API na geração de um QR code para pagamento em Pix:

Campo	Tipo	Descrição
`Payment.QrCodeBase64Image`	string	Base64 da imagem do QRCode gerado para pagamento do Pix.
`Payment.QrCodeString`	string	Código do Pix (copia e cola) que pode ser usado para pagamento.
`Payment.SentOrderId`	string	Identificador da transação Pix, representa o `txid`.
`Payment.ReturnCode`	string	Código de retorno.
`Payment.ReturnMessage`	string	Mensagem de retorno.
`Payment.PaymentId`	string	Identificador da transação usado para consulta.

A nova integração Pix ainda não tem ambiente sandbox disponível.

Mudanças nos campos

Confira as mudanças nos campos retornados ao atualizar o provedor Cielo para Cielo2: