API conventions

This page consolidates the rules applicable to all operations of the API.

Protocol and format

Requests and responses are exchanged over HTTPS, in JSON (RFC 8259) encoded in UTF-8. Requests with a body must send the Content-Type: application/json header.

Quantity	Representation
Monetary amount	Integer, in cents of Brazilian real (BRL, ISO 4217). The amount of R$ 1,250.00 is represented by `125000`.
Fee percentage	Integer, in hundredths of a percent. The percentage of 2.99% is represented by `299`.
Date and time	Text in ISO 8601 format, in UTC. Example: `2026-11-12T14:10:17.000Z`.
Date	Text in `YYYY-MM-DD` format.
Document	CPF or CNPJ, accompanied by its type in `documentType` (`cpf` or `cnpj`).

Response envelope

Successful responses contain success: true and, when there is content, the data field. Failure responses adopt a single envelope, in which the message field describes the cause.

{
  "success": false,
  "message": "Documento inválido para o tipo selecionado"
}

The text of the message field is returned in Portuguese. Integrations must base their logic on the HTTP status and, where present, on the code field, and not on the message text.

Idempotency

Idempotency ensures that repeating a request, as a result of a network failure or a timeout, does not produce a duplicate financial effect. In Pix, card and subscription charge operations, the idempotency key is sent in the Idempotency-Key header. Repeating the request with the same key returns the transaction already recorded.

curl -X POST https://api.fincle.com.br/v1/card \
  -H "Authorization: Bearer $FINCLE_TOKEN" \
  -H "Idempotency-Key: 7c1f0b9e-3a52-4d6c-9e1b-5f2a8c4d7e10" \
  -H "Content-Type: application/json" \
  -d '{ "amountInCents": 125000, "card": { "cardToken": "tok_9f2c1a7b4d6e" }, "customer": { "documentType": "cpf", "document": "31845792041" } }'

In the transfer operation, the key is sent in the body, in the idempotencyKey field of POST /v1/transfers, and is mandatory. It is recommended to generate a universally unique identifier (UUID) for each payment intent and to reuse it in every retry of the same intent.

Pagination

Listing operations accept the page parameter, starting at 1, and the pageSize parameter, limited to 100 records. The response contains the records in data and the totals in pagination.

{
  "success": true,
  "data": [],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 0,
    "totalPages": 0
  }
}

Two operations are exceptions. GET /v1/transactions paginates by offset, through the offset parameter, and reports the total number of records in totalRows. GET /v1/subscriptions uses the limit parameter in place of pageSize.

Rate limit

Up to 1000 requests per minute are allowed per source IP address. Every response reports the state of the limit in the headers below.

Header	Description
`x-ratelimit-limit`	Maximum number of requests in the window.
`x-ratelimit-remaining`	Requests remaining in the current window.
`x-ratelimit-reset`	Time, in seconds, until the window resets.

When the limit is exceeded, the response is 429, accompanied by the retry-after header, which states the waiting time, in seconds, before a new request.

Response codes

Code	Meaning
`200`	Request processed successfully. In card charges, the outcome of the authorization is given in the body.
`201`	Resource created.
`400`	Request rejected by a business rule. In charge operations, it also covers validation failures.
`401`	Access token missing, invalid or expired.
`403`	Operation not permitted for the account.
`404`	Resource nonexistent or belonging to another account.
`422`	Request not in conformity with the validation schema.
`429`	Rate limit exceeded or, in card charges, payer temporarily blocked.
`500`	Internal failure. The request may be repeated, provided the idempotency key is preserved.

Retry policy

Network failures and 5xx responses may be retried, provided the idempotency key is preserved. 4xx responses indicate a condition that does not change with mere repetition and require correction of the request, with the exception of the 429 response, which must be repeated after the interval stated in retry-after. Increasing intervals between retries are recommended.

Introduction

Fundamentals

Charges

Post-payment

Compliance

API conventions

Protocol and format

Response envelope

Idempotency

Rate limit

Response codes

Retry policy

​Protocol and format

​Response envelope

​Idempotency

​Pagination

​Rate limit

​Response codes

​Retry policy

Protocol and format

Response envelope

Idempotency

Pagination

Rate limit

Response codes

Retry policy