> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fincle.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash theme={null}
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": "helena.andrade@example.com",
      "documentType": "cpf",
      "document": "31845792041"
    }
  }'
```

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](https://docs.fincle.com.br/guides/infractions-and-med.md).

## Return

A Pix received may be returned to the payer through the [refund](https://docs.fincle.com.br/guides/refunds.md) operation or as a result of an infraction upheld under the [Special Return Mechanism](https://docs.fincle.com.br/guides/infractions-and-med.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.