Create a payment with Pix QR Code

✅
This is the new Pix integration you should follow starting from 09/01.

ℹ️
Learn more about this feature in the documentation.

To create a Pix QR code through the Cielo E-commerce API, integrate according to the specification below.

The required field Payment.Type must be sent as "Pix". The response will return the base64 code of the Pix QR Code image, which merchant should provide to the shopper.

⚠️
The maximum expiration time for the Pix QR Code by Cielo is 24 hours. This expiration time can be changed using the Payment.QrCode.Expiration field.

Request

Environment	Method	Endpoint
Produção	post	`https://api.cieloecommerce.cielo.com.br/1/sales`

The new Pix integration does not yet have a sandbox environment available.

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

Header parameters

Property	Description	Type	Size	Required
`MerchantId`	Merchant identifier in the Cielo E-commerce API.	GUID	36	Yes
`MerchantKey`	Public key for dual authentication in the Cielo E-commerce API.	string	40	Yes
`RequestId`	Request identifier, used when the merchant uses different servers for each GET/POST/PUT.	GUID	36	No

Body parameters

Field	Type	Description
`MerchantOrderId`	string	Order identification number. Special characters are not allowed. Size: 25
`Customer.Name`	string	Shopper's name. Size: 255.
`Customer.Identity`	string	Shopper's CPF or CNPJ number. Size: 18.
`Payment.Type`	string	Payment method type. In this case, enter “Pix”. Size: 15.
`Payment.Provider`	string	Payment provider name. In this case, “Cielo2”.
`Payment.Amount`	number	Order amount, in cents.
`Payment.QrCode.Expiration`	number	QR Code expiration time, in seconds. (E.g.: 30 minutes = 1800). This field is optional. If not provided, the default value will be 86400 seconds (24 hours).

Response

{
    "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": "OPERACAO REALIZADA 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/********-****-****-****-************"
            }
        ]
    }

Response parameters

The following table presents the main parameters that can be returned by the API when generating a QR code for Pix payment:

Field	Type	Description
`Payment.QrCodeBase64Image`	string	Base64 of the QR Code image generated for Pix payment.
`Payment.QrCodeString`	string	Pix code ("copy and paste") that can be used for payment.
`Payment.SentOrderId`	string	Pix transaction identifier, represents the `txid`.
`Payment.ReturnCode`	string	Return code.
`Payment.ReturnMessage`	string	Return message.
`Payment.PaymentId`	string	Transaction identifier used for queries.

Field updates

See the changes in the fields returned when updating the Cielo provider to Cielo2:

Fields	Previous integration	New integration (Cielo2)
`Payment.QrCode.Expiration`	Did not exist. Previously, the default expiration time for the Pix QR Code was two hours.	Represents the expiration time of the Pix QR Code in seconds and can be set by the merchant. If not specified, the default expiration time will be 24 hours.
`Tid`	Represented the QR Code ID.	No longer exists.
`ProofOfSale`	Represented the Pix NSU.	No longer exists.
`SentOrderId`	Represented the `Ecommerce Order Id`.	Now represents the `txid`.

All other fields remain unchanged.

✅This is the new Pix integration you should follow starting from 09/01.

ℹ️

⚠️

Request

Response

Field updates

✅
This is the new Pix integration you should follow starting from 09/01.