Introduction

Development of the Pix API (Application Programming Interface) by Cielo as payment service provider and transactional account provider and direct participant of Pix, considering the standards defined by the Central Bank of Brazil (“Central Bank”) in the Pix Regulation and other related documents.

The Pix API is an application programming interface standardized by the Central Bank to enable the end user to automate the interaction with the Pix participant that provides payment services.

The Pix API includes the necessary functionalities to enable the receipt of charges in business cases focused on immediate payments, such as points of sale in physical stores and e-commerce solutions.

The Cielo API’s responsibility is to generate a QR Code for payments via Pix, following the security standards required by the Central Bank and identifying some information during the transaction: date and time of the transaction, name of the person carrying out the transaction, as well as the name of the recipient and the amount involved.

Main audience

Customers who have TEF, LIO Integrated and E-commerce capture solutions and wish to transact Pix through these capture solutions.

• TEF (Electronic Funds Transfer): TEF solutions integrate the establishment’s commercial automation with the Cielo system, enabling sales with cards through magnetic stripe readers and chip readers.
• Lio Integrated: is an open platform that allows the integration of all your store management systems. For those who already have a complete management system, it allows for much simpler and faster integration. For those who do not work with a management system, Cielo LIO delivers payment reports, product catalogue, barcode reader, among other exclusive benefits.
• E-commerce: transfer of information over the internet for online payment, with hundreds of resources. A more complete digital solution. Your business is always available, Anti-fraud shielding, more conversion, simple, modular and flexible, Data intelligence.

What is Pix?

Pix is ​​the payment method created by the Central Bank in which resources are transferred between accounts in a few seconds, at any time or day. Pix is ​​a new way of selling in a instant, secure and simple way through Cielo solutions.

How does receiving Pix work at Cielo?

To use Pix, Cielo customers can choose the Pix Account option they prefer, being Simplified Management or Free Movement Management.

• Simplified Management: the balance is automatically transferred to the bank account registered at the commercial establishment. In addition, it is possible to access the Pix statement and information about operations.

• Free Movement Management: the customer has access to all Pix functions, through the Cielo Gestão App. Additionally, the balance can be used for transfers and payments via Pix. In this option, the balance of sales made with Pix is not transferred automatically.

Important: all customers enabled for Pix Cielo, as well as new customers, will have the Simplified Management option automatically activated. If desired, Cielo customers can change this option at any time.

If the Cielo customer opts for Free Movement Management, the automatic transfer functionality will be deactivated.

The Pix API includes the necessary features to enable:

Receiving charges in business cases focused on immediate payments, such as points of sale in physical stores and e-commerce solutions;

We are making the APIs available

• 1. Billing API: Available for generation of QR Code by the receiving user, to be used once, initiating instant payment. At this point we will make the dynamic QR Code available with immediate payment. Deadline for the qrcode to expire (60min).

• two. Conciliation API: Available for generating reports (Optional for the customer).

• 3. Returns API: Available to return transactions. Always individual, identifying the transaction to be returned. Represents a request to return a Pix made, whose funds are already available in the receiving user’s transactional account.

The Cielo-Pix-v1 API works as follows: The automation/Front-end software used by the receiving user (EC) will access the Cielo-Pix-v1 API and, with the data received as an API response, will present a Dynamic QR Code on a device so that the paying user can read the QR Code through their mobile device to make the payment.

Pix API context

The Pix API is the component of the arrangement that aims to enable the paying or receiving user, in the P2B64 or B2B65 context, to automate the interaction with their payment service provider (PSP), in order to carry out or receive transactions within the scope of the arrangement Pix.

In this context, this version of the Pix API seeks to automate the receiving user’s interaction with their payment service provider (PSP), in order to generate charges and confirm receipt of payment of these charges through Pix.

In the figure above, you can see possible integration paths for the receiving user’s systems with the API PSP Pix.

The receiving user will be able, via the Pix API:

• i. Generate charges that can be paid via QR Code by your customers;
• ii. Change billing details;
• iii. Check payment settlement through Pix received;
• iv. Carry out payment reconciliation in an easy manner;
• v. Support the refund process, which can be triggered depending, for example, on the return of a purchase.

The general aspects relating to the Pix API are detailed below.

General concepts

For the purposes of this document, related expressions and terms are defined as follows:

• I - client_ID: Pix API access component that identifies a user’s client software element. To access the API, it is necessary to use, for example, the Client_ID and a secret, both provided by the user’s PSP during the registration process. There may be more than one client software element in the user’s infrastructure and, therefore, for a user there may be more than one client_ID.
• II - Scopes: define the authorizations associated with each of the API services. In turn, Client_IDs have access to one or more scopes, which will define which services can be accessed by each Client_ID;
• III – Payload JSON: content retrieved from the call to the URL, read from the dynamic QR Code and representing a charge;
• IV - Paying PSP: Pix participant in which the paying user has a transactional account;
• V – Receiving PSP: Pix participant in which the receiving user has a transactional account that will be used to receive Pix. The Receiving PSP that wants to provide its customers with an automated integration solution with the Pix arrangement must do so through the Pix API, following the business and technical specifications defined by the Central Bank of Brazil in this document and in the other documents provided in the section two.
• VI - transactionId (txid): transaction identifier, from the perspective of the receiving user. This number is generated by the receiving user and passed on to the receiving PSP in the Pix API call, when the charge is created, in order to uniquely identify that charge66. Thus, txid is used by the receiving user, in their processes of reconciling payments received through Pix. In the case of charges created through the Pix API, the receiving PSP must ensure that the txid is unique for a given receiving user (CPF/CNPJ).
• VII - paying user: the one who pays a charge through Pix and has their transactional account debited.
• VIII - receiving user: natural or legal person who wishes to receive charges – for immediate or due payments – through Pix and uses the Pix API to automate their processes for generating these charges and for reconciling payments received through Pix.
• IX – withdrawal service facilitator (FSS): Pix participant who is classified as a transactional account provider and is authorized to operate by the Central Bank of Brazil on an optional basis, will provide the withdrawal service directly , or through a withdrawal agent, upon establishment of a contractual relationship for this purpose.
• X – Key: The mandatory key field determines the Pix key registered with the Central Bank that will be used for the charge, identifying the receiving user, as well as the details of the transactional account to which the charge must be linked .

Pix API features

Entity definitions

The Pix API is structured around some business entities, which group sets of attributes, as defined below:

I - Billing (/cob): represents each of the charges generated through the Pix API, in order to allow the paying user to make an identified payment to the receiving user. Billing is characterized by a set of information that is used for the paying user to make a payment through Pix, generally as a result of a commercial agreement between the paying user and the receiving user, without being confused with the Pix payment itself. . The billing model used is for immediate payment.

Billing states:

• a) ACTIVE: indicates that the charge has been generated and ready to be paid;
• b) COMPLETED:: indicates that the charge has already been paid and, therefore, cannot accept another payment67;
• c) REMOVED_BY_RECEIVER_USER: indicates that the receiving user requested the removal of the charge; It is
• d) REMOVED_BY_PSP: indicates that the Receiving PSP requested the removal of the charge.

II - Pix (/pix): represents a payment received through the Pix payment arrangement.

III - Return: represents a request to return a Pix made, the funds of which are already available in the receiving user’s transactional account.

Return status:

• a) IN_PROCESSING: indicates that the return was requested, but is still being processed in the SPI;
• b) RETURNED: indicates that the return was settled by SPI; It is
• c) NOT_PERFORMED: indicates that the refund cannot be made due to an error during settlement (example: insufficient balance).

Cardinality between entities

• I - A Charge can be associated with one or more Pix (same txid);
• II - A Pix can be associated with a single Charge. Pix, however, can exist independently of the existence of a Charge;
• III - A Pix can have one or more Returns associated with it. A Return is always associated with a Pix.
• IV – A Charge can only be associated with one PayloadLocation and, at any given time, the PayloadLocation can only be associated with one charge.

TransactionID lifecycle (txid)

There are two usage situations for the TransactionId (txid) field, which involve different rules for filling it out, as discussed below.

txid in the context of Collections:

Charges for immediate or due payments created through the Pix API are uniquely identified using a txid. The txid can be sent by the receiving user when the charge is generated, and cannot be repeated between different charges, in order to guarantee the correct reconciliation of payments. Alternatively, in the case of charges for immediate payment, it is possible for the receiving user to delegate the generation of the txid to their PSP.

Once a charge is requested to be created through the Pix API, the Receiving PSP must ensure that there is no repetition of the txid for the same receiving user, whether sent by the user or generated by the PSP itself. Therefore, the set of CNPJ or CPF and txid must be unique for a given PSP.

The txid must be a minimum of 26 characters and a maximum of 35 characters in length. The characters accepted in this context are: A-Z, a-z, 0-9.

Feature groups

Features and respective endpoints

The Pix API functionalities, in the current version, are defined in six groups:

I – Collection Management with immediate payment (Cob), which deals with the life cycle of the Billing entity:

II – Management of Pix Received (Pix), which deals with the life cycle of Pix and Return entities:

Use cases

The objective of this section is to provide examples of how the Pix API can be used to automate interactions between receiving users and their respective PSPs in transactions associated with Pix. These use cases are NOT intended to exhaust the ways of using or functions made available by the Pix API.

Immediate payment (at the time of purchase) with Dynamic QR Code

Application: Merchants with medium or high sales volumes. Online commerce.

1. The paying user, when making the purchase, informs that they wish to pay with Pix;

2. The automation software used by the receiving user accesses the Pix API to create a charge and, with the data received in response, generates a Dynamic QR Code, which is displayed on any display device:

• The. in an in-person purchase, typically a screen near the cashier or even a POS;
• B. for online purchases, on the device used by the payer.

Service invoked: PUT /cob/{txid}  All data necessary to create the billing payload must be entered, according to the detailed specification. Alternatively, if the receiving user does not want to identify the immediate charge with their own {txid} number, they can choose to use the POST /cob method.

3. The paying user then reads the QR Code with their PSP App and makes the payment;

4. The receiving user, in an automated way, through a new query to the Pix API, checks whether the payment was made: Service invoked: GET /cob/{txid};

5. The receiving user releases the products to the paying user or, in the case of online purchases, confirms receipt of payment. Alternatively, step 4 can be performed using webhooks configured in the corresponding service. In this case, the receiving user would be informed by the Receiving PSP of the credit of a Pix associated with a txid in their transactional account.

Make a return

Application: various (product returns, billing error, product unavailability in stock, etc.) Premise: When the buyer and seller agree, it will be possible to carry out the return process for a Pix transaction. This process must be initiated by the seller, that is, by the person who received the Pix transaction. It is important to pay attention to the deadlines (in accordance with Central Bank regulations).

• For Pix Withdraw or Pix Change: the return must be completed within a maximum period of up to 1 hour after completing the transaction.
• For transfers, sales and other transactions with Pix: up to 90 days after completion of the transaction.

Important: the return is available exclusively to customers who have free movement of the account and must be carried out through the Cielo Gestão App or, if the customer has one, through the means of capture via the Central Bank Pix API (TEF, LIO Integrada or E-commerce) or via API 3.0 (E-commerce). Customers who choose automatic transfer will not be able to complete the return operation due to lack of balance in their account. To access the promotion, you must change your profile to Free Movement.

The paying user requests the receiving user, via some suitable means of communication, to return all or part of a payment made;

The receiving user agrees and identifies the original payment made by Pix. There are two possible situations:

A. When Pix is ​​associated with a Charge:

• Service invoked: GET /cob/{txid}  As a result, a Billing entity will be received that contains a list of the Pix received, each with its identification (EndToEndId).

B. When Pix is ​​not associated with a Charge. In this case, it is necessary to know, by other means, the EndToEndId of the original Pix. Alternatively, it can be a broad query, bringing a list of Pix received.

• Service invoked: GET /pix/  Parameters can be entered to limit the query temporally (start and “end” parameters can be used). Furthermore, you can limit the search to a specific paying user, using the payer’s CNPJ/CPF.

The receiving user’s automation software activates the Pix API to perform the return.

• Service invoked: PUT /pix/{e2eid}/devolucao/{id}  In this case, “id” is a code generated by the receiving user’s system that identifies the return associated with the original Pix. Please note that a Pix can have several returns associated with it, as long as the amount of the returns does not exceed the value of the original Pix. The “id” must be unique per EndToEndID Pix. The receiving user’s automation software triggers the Pix API to check whether the return has been settled:

• Service invoked: GET /pix/{e2eid}/devolucao/{id} The paying user receives a Pix with the agreed return value.

Membership Day

The subscription journey is understood as the process through which a receiving user begins to use the services of a specific PSP. From the Pix API point of view, this process must include providing access credentials (Client_IDs and passwords) and certificates to the receiving user.

In the subscription process, the Client_ID provided by the PSP must have a set of scopes that will determine the functionalities to which the Receiving User will have access. The authorization criteria in the scopes are the responsibility of the PSP, which can create different criteria depending on the characteristics of the Receiving User.

In this way, it is possible, for example, that certain functionalities are only accessible by users who meet additional security requirements stipulated by each PSP.

Credential request for development/integration

To use the PIX API, requests must be executed using the respective credentials from the Approval and Production environments.

Environment description:

Production: is the transactional environment integrated into Cielo’s environment. The operations carried out in this environment are real and cannot be undone.

Approval: is the environment intended for testing. Operations are performed in a real, but non-productive, environment.

Homologation

Credentials for the approval environment are requested directly on our Developers Portal

Simply select the APIs below:

After creation, you will be able to view your client_id and client_secret, access: My Credentials

Production

Production: For partners to access Cielo’s customer data, customers need to provide the “keys” to the partner.

And how does the credential creation flow work in production?

Important: New credentials must be generated for each commercial establishment.

1st: On the Cielo website, the Cielo customer accesses the [My Account] portal (https://minhaconta2.cielo.com.br/minha-conta/home) and clicks on My Registration.

2nd: In the Authorizations tab, click on Pix.

3rd: To create credentials, select the New access option.

4th: Then, click on Create credential.

5th: Select the partner.

6th: And click Create.

7th: Accept the terms of use and check the box.

8th: And then click the Authenticate and continue button.

9th: Insert the security token.

Important: token activation must be carried out through Cielo Gestão.

10th: Ready! Credential created successfully.

After this step, the customer will be able to copy the Customer ID, Client Secret and Transactional Key to perform onboarding on the partner portal.

Important: Credentials need to be copied/downloaded within 3 minutes. Otherwise, you will need to generate a new credential.

Pix API: Technical Specification

Protocols and technologies

The Pix API will adopt the following protocols and technologies:

API Definition: The Pix API is detailed in the OpenAPI 3.077 format. Format: The data format used is JSON. Protocol: the receiving user’s automation interacts with the API using web services based on REST over HTTPS.

Security

PSPs must develop and implement the API following good security practices, meeting the mandatory requirements below and the recommendations detailed in this section.

Mandatory security requirements

The PSP must comply with the following requirements:

1. The customer registration/onboarding process for access to the API must be carried out in an environment logged into the PSP, and must include a secure channel for sending credentials to the user, in order to allow traceability of the actions performed.
2. The API must support multiple authorization levels or roles, segregating functionalities according to profiles (OAuth scopes) of client users.
3. The PSP must implement technology that ensures the high availability of the API.
4. The API must guarantee the confidentiality and integrity of user information and transactions, both in transit and at rest.
5. The PSP must maintain audit logs of API access for a minimum period of 1 year.
6. The access credential used in authentication (Client_ID) must be linked to the CNPJ or CPF of the receiving user and must allow access to resources only from transactional accounts held by the associated CNPJ or CPF.

Security

They must be observed to develop and implement the API following good security practices, meeting the mandatory requirements below.

Mandatory security requirements:

1. The connection to the API must be encrypted using the TLS protocol version 1.2 or higher, only allowing cipher suites that meet the forward secrecy requirement.
2. The PSP must implement the OAuth 2.0 framework (RFC 6749) with mutual TLS (mTLS – RFC 8705) for API authentication, according to the specifications below:

A. Digital certificates for API clients may be issued by the PSP itself or by external CAs, as defined by each PSP. Certificates self-signed by the client should not be accepted. B. Each PSP must have its own Authorization Server and Resource Server associated with the Pix API, and both must implement mutual TLS. w. The PSP Authorization Server must implement the technique for linking the client certificate to the issued access tokens (“Client Certificate-Bound Access Tokens”), according to section 3 of RFC 8705. d. The PSP Resource Server must confirm that the thumbprint of the certificate associated with the access token presented by the client is the same as that used in TLS (proof-of-possession) authentication. It is. The OAuth flow to be used is the “Client Credentials Flow”. f. OAuth scopes will be defined in the Pix API Open API 3.0 specification and will allow different authorization profiles to be associated with the client software.

1. The customer registration/onboarding process for access to the API must be carried out in an environment logged into the PSP, and must include a secure channel for sending credentials to the user, in order to allow traceability of the actions performed.
2. The API must support multiple authorization levels or roles, segregating functionalities according to profiles (OAuth scopes) of client users.
3. The PSP must implement technology that ensures the high availability of the API.
4. The API must guarantee the confidentiality and integrity of user information and transactions, both in transit and at rest.
5. The PSP must maintain audit logs of API access for a minimum period of 1 year.
6. The access credential used in authentication (Client_ID) must be linked to the CNPJ or CPF of the receiving user and must allow access to resources only from transactional accounts held by the associated CNPJ or CPF.
7. For the webhooks functionality, notifications from the receiving PSP to the receiving user will travel using an mTLS channel.

The. It is recommended that the certificates used for mutual authentication in the webhook’s TLS channel are the same as those used in the Pix API. In any case, there is no objection to the use of other certificates, subject to agreement between the PSP and the receiving user.

The BC understands that PSPs will be able to adopt the technologies and security solutions for the API that they deem most appropriate, as long as the mandatory security requirements are met and, whenever possible, the recommendations described above, also paying attention to the elements listed in the topics Next.

Swagger API PIX

Access our Developers Portal to view the technical specification of the API in Swagger format