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
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 answers202 Accepted as soon as it accepts the request. It does not wait for the money to move.
- Observe the outcome by polling
GET /v3/accounts-payable/{externalId}. - Every payment reaches a terminal status (
PAID,FAILED, orCANCELLED) 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
externalIdagain answers202without creating a second payment. It is safe to retry a create that timed out. - A new payment always needs a new
externalId.
Choosing the destination
There is no destination type field. The API infers the destination from which fields you populate: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.
Phone keys (dictKeyType: PHONE)
Phone keys must be E.164: a leading +, a non-zero country code, then the subscriber number — up to 15 digits in total. The number may belong to any country, not only Brazil.
- Brazil mobile:
+55+ 2-digit DDD + 9 digits →+5562991767531 - Brazil landline:
+55+ 2-digit DDD + 8 digits →+551133334444 - United States:
+1+ area code + number →+14155552671 - United Kingdom:
+44+ number →+447911123456 - Pattern:
^\+[1-9]\d{1,14}$
A PHONE key that does not normalize to a value matching
^\+[1-9]\d{1,14}$ is rejected synchronously with 400 INVALID_REQUEST, before any DICT lookup. Always send the canonical form.
For a Pix-key or QR payment you can optionally send beneficiary.documentNumber as an owner assertion. It is checked against the key or QR code holder and is not echoed back. See Beneficiary in responses. For a bank-details payment the full beneficiary is required, and accountType uses the ISO 20022 values:
Scheduling
AddpaymentMethod.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
Sample JSON Response — 202 Accepted
JSON
amount is null while an amount-less QR is still being resolved.
Synchronous errors
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
204 No Content.
Get a payment
Endpoint
GET /v3/accounts-payable/{externalId}
cURL Request
cURL
Sample JSON Response
Whatbeneficiary contains depends on the destination the payment was created with. See Beneficiary in responses below.
- Pix key
- QR code
- Bank details
JSON
Beneficiary in responses
beneficiary always contains the same seven fields. Which ones are filled depends on how you created the payment:
Pix key and QR code payments
- The beneficiary is the holder of the Pix key or QR code, as identified by Pix when the payment is created. It is not an echo of the
beneficiaryyou sent. Abeneficiary.documentNumbersent on create is only used to check the holder. - The destination’s bank account details are never returned. All five bank fields are always
null. - A CPF is masked: only the middle six digits are shown, in the format
***.456.789-**. - A CNPJ is returned in full, digits only:
12345678000195.
- All seven fields are returned as you sent them on create.
documentNumberis returned as digits only, even if you sent it with punctuation:123.456.789-01comes back as12345678901.
The same rules apply to every payment returned by List payments.
Statuses
Refunds are not exposed at launch. A refunded payment remains
PAID.When a payment fails
AFAILED payment carries an error object:
JSON
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.
List payments
Endpoint
GET /v3/accounts-payable
Query Parameters (Optional)
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.
cURL Request
cURL
Sample JSON Response
JSON
Rate limits and outages
- A
429comes from the gateway with no body. TheX-RateLimit-Remaining,X-RateLimit-Replenish-Rate,X-RateLimit-Burst-Capacity, andX-RateLimit-Requested-Tokensheaders carry the quota state. There is noRetry-Afterheader. - A
503means the payment service could not be reached or answered outside its contract. Retry later, and poll the payment byexternalIdbefore you submit it again.
