Accounts Payable (Pix)

This service is available in v3 only, and in Brazil only.

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.

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.

A 202 means accepted for processing, never paid. Always poll the payment to learn its real outcome.

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.

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

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.

Create a Pix payment

Endpoint

POST /v3/accounts-payable/pix

Pix key
QR code
Bank details
Scheduled

cURL

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" }
}'

cURL

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"
  }
}'

cURL

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"
  }
}'

cURL

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"
  }
}'

Sample JSON Response — `202 Accepted`

JSON

{
  "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

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

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.

Get a payment

Endpoint

GET /v3/accounts-payable/{externalId}

cURL Request

cURL

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

{
  "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

Refunds are not exposed at launch. A refunded payment remains PAID.

When a payment fails

A FAILED payment carries an error object:

JSON

{
  "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`

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.

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

cURL Request

cURL

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

{
  "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
}

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.

Overview

Conventions

Guides

Resources

API Reference

MCP

VCN

Accounts Payable (Pix)

What is Accounts Payable?

Available Endpoints

How payment creation works

Idempotency with `externalId`

Choosing the destination

Scheduling

Create a Pix payment

Endpoint

Sample JSON Response — `202 Accepted`

Synchronous errors

Cancel a scheduled payment

Endpoint

cURL Request

Get a payment

Endpoint

cURL Request

Sample JSON Response

Statuses

When a payment fails

List payments

Endpoint

Query Parameters (Optional)

cURL Request

Sample JSON Response

Rate limits and outages

​What is Accounts Payable?

​Available Endpoints

​How payment creation works

​Idempotency with externalId

​Choosing the destination

​Scheduling

​Create a Pix payment

​Endpoint

​Sample JSON Response — 202 Accepted

​Synchronous errors

​Cancel a scheduled payment

​Endpoint

​cURL Request

​Get a payment

​Endpoint

​cURL Request

​Sample JSON Response

​Statuses

​When a payment fails

​List payments

​Endpoint

​Query Parameters (Optional)

​cURL Request

​Sample JSON Response

​Rate limits and outages

What is Accounts Payable?

Available Endpoints

How payment creation works

Idempotency with `externalId`

Choosing the destination

Scheduling

Create a Pix payment

Endpoint

Sample JSON Response — `202 Accepted`

Synchronous errors

Cancel a scheduled payment

Endpoint

cURL Request

Get a payment

Endpoint

cURL Request

Sample JSON Response

Statuses

When a payment fails

List payments

Endpoint

Query Parameters (Optional)

cURL Request

Sample JSON Response

Rate limits and outages