API PIX Cash-in Introduction

Welcome to CDC's API Pix.

This API standardizes the Pix services offered by the receiver PSP, like the creation of charges, verification of the received Pix, chargebacks and consultation. The receiver PSP's exposed services allow the receiver user to integrate their own automation with the PSP Pix services.

Available Services

Pix Charges Via Dynamic QRCodes

Allows the receiver user to generate a Pix Charge, configuring it's amount, partial payment, expiring, fees, fines, discounts, rebates and expire dates

The Pix Charge subdivides into two types:

• Immediate Charges (Cob)
• Charges With Due Dates (Cobv)

After the generation of a new Pix Charge, the receiver user is able to consult the liquidation of the transaction using the transaction's unique code (txid) generated on the creation of the Pix Charge.

📘

The possible states of a Pix Charge are:

State	Description
ATIVA	The Pix Charge was generated e is ready to be liquidated
CONCLUIDA	The Pix Charge was liquidated. A liquidated Charge can't be altered nor cancelled.
REMOVIDA_PELO_USUARIO_RECEBEDOR	The Pix Charge were cancelled by the receiver user
REMOVIDA_PELO_PSP	The Pix Charge was cancelled by the PSP

📘

Observations:

• After being generated, a Pix Charge gets it's own unique code called txid. This code can be defined by the receiver user, but if none is passed it will be automatic generated.
• After creating a Pix Charge, the receiver user gets all the information necessary for the creation of a Dynamic QRCode Image, together with the transaction's Pix Copia-e-Cola.
• The API Pix does not create Static QR Codes.

Review/Update of Pix Charges

The receiver user can receive and update any field of a Pix Charge that has the ATIVO state

Retrieval of Pix Charges

This functionality allows searches of transaction by status, period and/or txid. Also by end2end for Pix already liquidated.

There's many possible applications for this query type, mainly relative to the processes of conciliation between receiver user and PSP, always using the txid as the principal element.

📘

Observations:

• The consultation of Received Pix GET /pix retrieves all received Pix in the period specified by the receiver user, independent of the Pix key used in the Pix Charge.
• The consultation filtering by period is limited, by requisition, to an interval of 5 calendar days. Consultations of periods of more than 3 months ago must consider the same month and year.

Webhook

This is a service that allows the PSP to inform the receiver user directly when a Pix associated with a txid was credited in his account. Using this logic, instead of the receiver user needing to keep sending many consultation requests to the API Pix (polling), the API will inform the receiver user when a Pix Charge is liquidated.

🚧

Only Pix Charges associated with a txid will be informed via webhook

The receiver user can create, configure and delete webhooks directly via API requests using the /webhook endpoint

Refund

The receiver user can refund the Pix transaction to the payer, partially or totally.

📘

The possible states of a Pix Refund are:

State	Description
EM_PROCESSAMENTO	Solicited the refund but it is still being processed by the SPI
DEVOLVIDO	Refund processed by the SPI
NAO_REALIZADO	Refund couldn't be performed because of an error during liquidation (Eg.: Insufficient Funds)

Location

The /loc endpoint allows the receiver user to "set aside" an URL, building a Dynamic QRCode before generating a Pix Charge. Typically, it is used when the receiver user needs a printed Dynamic QRCode (Eg.: Electricity Distributors).

📘

A "booked" URL doesn't have an expiration date, it will remain active until the receiver user deletes it.