Pix

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 /v1/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/v1/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": "helena.andrade@example.com",
      "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 /v1/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.

Introduction

Fundamentals

Charges

Post-payment

Compliance

Concepts

Immediate charge

Charge with due date

Validation rules

Idempotency

Payment confirmation

Return

​Concepts

​Immediate charge

​Charge with due date

​Validation rules

​Idempotency

​Payment confirmation

​Return

Concepts

Immediate charge

Charge with due date

Validation rules

Idempotency

Payment confirmation

Return