> ## Documentation Index
> Fetch the complete documentation index at: https://developers.clara.team/llms.txt
> Use this file to discover all available pages before exploring further.

# Accounts Payable (Pix)

> Create, cancel, and track Pix payments programmatically (Brazil only).

<Note>This service is available in **v3** only, and in **Brazil** only.</Note>

## What is Accounts Payable?

The **Accounts Payable API** lets you initiate and track **Pix payments** from your Clara digital account. Payments created through the API go through the same authorization, validation, and audit controls as payments made in the Clara web app.

You can use this API to:

* Pay to a **Pix key**, a **QR code**, or **bank details**
* Pay **immediately** or **schedule** a payment for a later date
* **Cancel** a scheduled payment before it runs
* **Track** each payment until it settles, and **list** payments with filters

## Available Endpoints

| Operation | Endpoint | Method |
| - | - | - |
| Create a Pix payment | `/v3/accounts-payable/pix` | POST |
| Cancel a scheduled payment | `/v3/accounts-payable/pix/{externalId}` | DELETE |
| Get a payment | `/v3/accounts-payable/{externalId}` | GET |
| List payments | `/v3/accounts-payable` | GET |

Creating and cancelling payments requires the `write:accounts-payable/pix` grant on your API credential. Getting and listing payments requires `read:digital-account`.

<br />

## How payment creation works

Creating a payment is **asynchronous**. The API answers `202 Accepted` as soon as it accepts the request. It does **not** wait for the money to move.

<Warning>A `202` means *accepted for processing*, never *paid*. Always poll the payment to learn its real outcome.</Warning>

* Observe the outcome by polling `GET /v3/accounts-payable/{externalId}`.
* Every payment reaches a terminal status (`PAID`, `FAILED`, or `CANCELLED`) within **3 hours** at worst.

### Idempotency with `externalId`

You generate the `externalId` (a UUID) yourself. It must be unique within your company.

* Sending the **same** `externalId` again answers `202` without creating a second payment. It is safe to retry a create that timed out.
* A **new payment always needs a new** `externalId`.

<Tip>If a create times out or returns `503`, poll the payment by its `externalId` before you send it again. It may already exist.</Tip>

<br />

## Choosing the destination

There is **no destination type field**. The API infers the destination from **which fields you populate**:

| Destination | What you send |
| - | - |
| **Pix key** | `paymentMethod.dictKey` and `paymentMethod.dictKeyType` |
| **QR code** | `paymentMethod.qrCode` |
| **Bank details** | A complete `beneficiary`, with neither `dictKey` nor `qrCode` |

`dictKey` and `qrCode` are mutually exclusive. Sending both, or no destination at all, is rejected with `INVALID_REQUEST`.

**`amount`** sits at the root of the request:

* **Required** for Pix-key and bank-details payments.
* **Optional** for QR payments, where the QR itself can define the amount.

`dictKeyType` is required whenever you send `dictKey`: `CPF`, `CNPJ`, `EMAIL`, `PHONE`, or `EVP`. CPF and CNPJ keys are both digit strings, so the type cannot be inferred from the value.

For a Pix-key or QR payment you can optionally send `beneficiary.documentNumber` as an owner assertion. For a bank-details payment the full `beneficiary` is required, and `accountType` uses the ISO 20022 values:

| `accountType` | Meaning |
| - | - |
| `CACC` | Checking / current account |
| `SVGS` | Savings account |
| `TRAN` | Payment account |
| `SLRY` | Salary account |

### Scheduling

Add `paymentMethod.desiredPaymentDate` (`YYYY-MM-DD`, `America/Sao_Paulo`) to schedule a payment. Omit it to pay immediately.

* The earliest date you can schedule is **D+1**.
* The payment provider decides how weekends and Brazilian bank holidays are handled.
* A dynamic immediate (`cob`) QR **cannot** be scheduled.

<br />

## Create a Pix payment

### Endpoint

`POST /v3/accounts-payable/pix`

<Tabs>
  <Tab title="Pix key">
    ```curl cURL theme={null}
    curl -X POST \
    "https://public-api.br.clara.com/api/v3/accounts-payable/pix" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "externalId": "a0c82a20-ac09-4cfd-b429-d0623585911e",
      "amount": 520.50,
      "description": "Invoice 2026-04 settlement",
      "paymentMethod": {
        "type": "PIX",
        "dictKey": "maria.silva@example.com",
        "dictKeyType": "EMAIL"
      },
      "beneficiary": { "documentNumber": "12345678901" }
    }'
    ```
  </Tab>

  <Tab title="QR code">
    ```curl cURL theme={null}
    curl -X POST \
    "https://public-api.br.clara.com/api/v3/accounts-payable/pix" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "externalId": "7c2e4a18-9d6b-4f35-a1c8-0e5b3d9f6a27",
      "description": "Supplier QR, amount defined by the QR",
      "paymentMethod": {
        "type": "PIX",
        "qrCode": "00020126580014br.gov.bcb.pix0136maria.silva@example.com5204000053039865802BR6009SAO PAULO62070503***6304ABCD"
      }
    }'
    ```
  </Tab>

  <Tab title="Bank details">
    ```curl cURL theme={null}
    curl -X POST \
    "https://public-api.br.clara.com/api/v3/accounts-payable/pix" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "externalId": "e91c07d4-2b58-4a6f-8d13-5c7e9a2b6f80",
      "amount": 3450.75,
      "description": "Contractor payment",
      "paymentMethod": { "type": "PIX" },
      "beneficiary": {
        "name": "Maria Silva",
        "documentNumber": "12345678901",
        "bank": "60701190",
        "bankName": "Itau Unibanco S.A.",
        "accountType": "CACC",
        "accountNumber": "123456",
        "branch": "0001"
      }
    }'
    ```
  </Tab>

  <Tab title="Scheduled">
    ```curl cURL theme={null}
    curl -X POST \
    "https://public-api.br.clara.com/api/v3/accounts-payable/pix" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "externalId": "3f1d9b6e-5c47-4a2b-8f0d-1b7a9c5e2d34",
      "amount": 1200.00,
      "description": "Rent, October",
      "paymentMethod": {
        "type": "PIX",
        "dictKey": "12345678901",
        "dictKeyType": "CPF",
        "desiredPaymentDate": "2026-10-01"
      }
    }'
    ```
  </Tab>
</Tabs>

### Sample JSON Response — `202 Accepted`

```json JSON theme={null}
{
  "externalId": "a0c82a20-ac09-4cfd-b429-d0623585911e",
  "status": "IN_PROCESS",
  "amount": 520.50,
  "paymentMethod": "PIX"
}
```

`amount` is `null` while an amount-less QR is still being resolved.

### Synchronous errors

| Status | `code` | When |
| - | - | - |
| `400` | `INVALID_REQUEST` | Two destinations or none, a missing amount on a key or bank-details payment, an incomplete beneficiary, or a date before D+1 |
| `409` | `INSUFFICIENT_FUNDS` / `LIMIT_EXCEEDED` | The balance or Pix-limit pre-check rejected the payment |

<br />

## Cancel a scheduled payment

Only **scheduled** payments that have not started executing can be cancelled.

### Endpoint

`DELETE /v3/accounts-payable/pix/{externalId}`

### cURL Request

```curl cURL theme={null}
curl -X DELETE \
"https://public-api.br.clara.com/api/v3/accounts-payable/pix/3f1d9b6e-5c47-4a2b-8f0d-1b7a9c5e2d34" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

A successful cancellation returns `204 No Content`.

| Status | `code` | When |
| - | - | - |
| `404` | `NOT_FOUND` | No payment with that `externalId` exists in your company |
| `409` | `NOT_CANCELLABLE` | The payment is not scheduled, or its execution already started |
| `409` | `ALREADY_CANCELLED` | The payment was already cancelled |

<Warning>A cancellation can lose a race against execution. If the payment started settling first, you get `NOT_CANCELLABLE`. Poll the payment to see its final status.</Warning>

<br />

## Get a payment

### Endpoint

`GET /v3/accounts-payable/{externalId}`

### cURL Request

```curl cURL theme={null}
curl -X GET \
"https://public-api.br.clara.com/api/v3/accounts-payable/a0c82a20-ac09-4cfd-b429-d0623585911e" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Sample JSON Response

```json JSON theme={null}
{
  "externalId": "a0c82a20-ac09-4cfd-b429-d0623585911e",
  "status": "PAID",
  "amount": 520.50,
  "currencyCode": "BRL",
  "paymentMethod": "PIX",
  "description": "Invoice 2026-04 settlement",
  "beneficiary": {
    "name": "Maria Silva",
    "documentNumber": "12345678901",
    "bank": "60701190",
    "bankName": "Itau Unibanco S.A.",
    "accountType": "CACC",
    "accountNumber": "123456",
    "branch": "0001"
  },
  "pixEndToEndId": "E6070119020260901120000000000001",
  "error": null,
  "creationDate": "2026-09-01T12:00:00Z",
  "paymentDate": "2026-09-01"
}
```

### Statuses

| Status | Terminal | Meaning |
| - | :-: | - |
| `IN_PROCESS` | | Accepted and being processed |
| `SCHEDULED` | | Accepted and waiting for its scheduled date |
| `PAID` | ✓ | Settled |
| `FAILED` | ✓ | Did not settle. `error` explains why |
| `CANCELLED` | ✓ | Cancelled before execution |

<Info>Refunds are not exposed at launch. A refunded payment remains `PAID`.</Info>

### When a payment fails

A `FAILED` payment carries an `error` object:

```json JSON theme={null}
{
  "externalId": "3f1d9b6e-5c47-4a2b-8f0d-1b7a9c5e2d34",
  "status": "FAILED",
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "The account balance is insufficient to complete the payment."
  }
}
```

**Integrate against `code`, not `message`.** The code is the stable contract. The message is informational: it may be reworded without a version change, and it is English-only at launch.

| Group | Codes |
| - | - |
| Amount | `AMOUNT_REQUIRED`, `AMOUNT_MISMATCH` |
| Destination | `BENEFICIARY_MISMATCH`, `QR_INVALID`, `QR_EXPIRED`, `QR_NOT_FOUND`, `PIX_KEY_INVALID`, `PIX_KEY_NOT_FOUND`, `BENEFICIARY_ACCOUNT_ERROR`, `PAYMENT_DATA_INVALID` |
| Funds & rules | `INSUFFICIENT_FUNDS`, `LIMIT_EXCEEDED`, `PAYMENT_NOT_ALLOWED`, `PAYMENT_REJECTED` |
| Scheduling | `NOT_SCHEDULABLE`, `SCHEDULE_DATE_INVALID`, `SCHEDULE_FAILED` |
| Execution | `SETTLEMENT_FAILED`, `PROVIDER_UNAVAILABLE`, `PROCESSING_TIMEOUT`, `PAYMENT_FAILED` |

<br />

## List payments

### Endpoint

`GET /v3/accounts-payable`

### Query Parameters (Optional)

| Parameter | Type | Description |
| - | - | - |
| `externalId` | uuid | Exact match |
| `status` | string | Repeatable. Pass it more than once to match several statuses |
| `minAmount` / `maxAmount` | decimal | Amount range |
| `createdFrom` / `createdTo` | date | Filters by **creation** date |
| `paidFrom` / `paidTo` | date | Filters by **settlement** date. Matches `PAID` payments only |
| `beneficiaryName` | string | Case-insensitive **substring** match |
| `beneficiaryDocumentNumber` | string | Case-insensitive **substring** match |
| `sort` | string | `"<field>,<direction>"`. See below |
| `page` | integer | Zero-based page index |
| `size` | integer | Page size. Default `20`, maximum `100` |

Dates are `YYYY-MM-DD` in `America/Sao_Paulo`, and range bounds are **inclusive**.

**Sorting:** one key per request. Allowed fields are `creationDate`, `amount`, and `status`; direction is `asc` or `desc`. The default is `creationDate,desc`.

<Warning>`paymentDate` can be filtered on (through `paidFrom`/`paidTo`) and is returned on every payment, but it is **not sortable**.</Warning>

### cURL Request

```curl cURL theme={null}
curl -X GET \
"https://public-api.br.clara.com/api/v3/accounts-payable?status=PAID&status=SCHEDULED&createdFrom=2026-09-01&createdTo=2026-09-30&sort=creationDate,desc&page=0&size=20" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Sample JSON Response

```json JSON theme={null}
{
  "items": [
    {
      "externalId": "a0c82a20-ac09-4cfd-b429-d0623585911e",
      "status": "PAID",
      "amount": 520.50,
      "currencyCode": "BRL",
      "paymentMethod": "PIX",
      "description": "Invoice 2026-04 settlement",
      "pixEndToEndId": "E6070119020260901120000000000001",
      "creationDate": "2026-09-01T12:00:00Z",
      "paymentDate": "2026-09-01"
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 1,
  "totalPages": 1
}
```

<br />

## Rate limits and outages

* A `429` comes from the gateway with **no body**. The `X-RateLimit-Remaining`, `X-RateLimit-Replenish-Rate`, `X-RateLimit-Burst-Capacity`, and `X-RateLimit-Requested-Tokens` headers carry the quota state. There is no `Retry-After` header.
* A `503` means the payment service could not be reached or answered outside its contract. Retry later, and **poll the payment by `externalId` before you submit it again**.

**⚠️ Note:** The sample data shown is for illustration only and does not represent real payments or account details.


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