Pix

Creation of immediate and due-date Pix charges.

Pix is the instant payment scheme established by the Central Bank of Brazil through BCB Resolution No. 1 of 12 August 2020. The API offers two charge types: the immediate charge, intended for payment on the spot, and the charge with a due date, which admits late charges and rebates.

​

Concepts

Term	Definition
BR Code	Brazilian QR Code standard for payment initiation, based on the EMV QRCPS specification.
Pix Copia e Cola	Text representation of the BR Code, entered by the payer in the application of their institution.
endToEndId	End-to-end identifier of the payment in the Instant Payment System, with 32 characters. It uniquely identifies the transaction across all participating institutions.

​

Immediate charge

The POST /pix/in/qrcode operation creates the charge. The amount (amountInCents) and the identification of the payer (customer.documentType and customer.document) are required.

curl -X POST https://api.fincle.com.br/pix/in/qrcode \
  -H "Authorization: Bearer $FINCLE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c1f0b9e-3a52-4d6c-9e1b-5f2a8c4d7e10" \
  -d '{
    "amountInCents": 125000,
    "description": "Invoice no. 2026/001042",
    "customer": {
      "name": "Helena Martins Andrade",
      "email": "[e-mail]",
      "documentType": "cpf",
      "document": "31845792041"
    }
  }'

{
  "success": true,
  "message": "Transação criada com sucesso",
  "data": {
    "id": "cmddiqpxo09zf1yju2kqkhgga",
    "pix": {
      "emv": "00020126870014br.gov.bcb.pix2565pix.example.com/qr/v3/at/7fab0715...6304F801",
      "qrCode": "data:image/png;base64,iVBORw0KGgo..."
    },
    "status": "pending",
    "fees": 1250
  }
}

Field	Description
id	Transaction identifier.
pix.emv	BR Code in text representation, for use as Pix Copia e Cola.
pix.qrCode	Image of the corresponding QR Code.
status	Status of the transaction. The initial value is pending.
fees	Fee charged on the transaction, in cents.

​

Charge with due date

The POST /pix/in/cob operation accepts the same fields as the immediate charge, plus the cob block. The cob.expirationDate field is required, uses the YYYY-MM-DD format and cannot be earlier than the current date.

{
  "amountInCents": 480000,
  "description": "Installment 11/12 of agreement no. 4587",
  "customer": {
    "name": "Distribuidora Vale Verde Ltda",
    "documentType": "cnpj",
    "document": "27481396000192"
  },
  "cob": {
    "expirationDate": "2026-12-10",
    "daysAfterDueDate": 5,
    "fine": { "type": "percent", "value": 2 },
    "interest": { "type": "percent", "basis": "month", "calendar": "calendar", "value": 1 }
  }
}

Field	Description
cob.expirationDate	Due date of the charge.
cob.daysAfterDueDate	Number of days, limited to 30, during which the charge remains payable after the due date.
cob.fine	Late payment fine, as a fixed amount or a percentage.
cob.interest	Late payment interest. The basis field defines the base (day, month or year), and the calendar field, whether days are counted as calendar days (calendar) or business days (business).
cob.discount	Early payment discount, proportional to the days of anticipation or tied to specific dates.
cob.rebate	Rebate on the original amount.

In the charge blocks, the type field takes the value fixed, for an amount in cents, or percent, for a percentage.

​

Validation rules

The payer’s registration number is validated according to the type provided, with verification of the check digits of the CPF or CNPJ. The phone number is optional and, when provided, must contain the area code and the number. When the list of items (items) is sent, the sum of amountInCents × quantity must be exactly equal to amountInCents. Validation failures result in a 400 response.

​

Idempotency

Both operations accept the Idempotency-Key header. Repeating the request with the same key returns the charge already created, without generating a new BR Code.

​

Payment confirmation

Settlement of the Pix is communicated by the transaction_paid event, which contains the endToEndId of the payment. It is recommended to store this identifier, as it is the reference used by the participating institutions in any infraction report.

​

Return

A Pix received may be returned to the payer through the refund operation or as a result of an infraction upheld under the Special Return Mechanism.