Overview

Scope, architecture and conventions of the Fincle payments API.

The Fincle API is a programming interface for processing payments by Pix, credit card and boleto. This documentation describes the full lifecycle of a transaction: creation of the charge, confirmation of payment, retrieval, refund, handling of infractions under the Special Return Mechanism (Mecanismo Especial de Devolução, MED) and transfer of the balance to the payee.

​

Scope

This documentation is intended for engineering teams responsible for integrating their own systems with the platform. It assumes familiarity with the HTTP protocol, the JSON format and the basic concepts of the Brazilian payment schemes.

Domain	Content
Charges	Creation of charges by Pix, credit card and boleto, and recurring billing through subscriptions.
Transactions	Statuses of a transaction and the transitions between them, described in Transaction lifecycle.
Notifications	Asynchronous communication of events through webhooks.
Post-payment	Refunds, infractions and MED and balance and transfers.
Compliance	Security and data protection and regulatory references.

​

Interface characteristics

The API follows the REST architectural style over HTTPS. Messages are exchanged in JSON (RFC 8259), encoded in UTF-8. The production base URL is https://api.fincle.com.br.

Monetary amounts are integers expressed in cents of Brazilian real (BRL, ISO 4217). Dates and times follow ISO 8601. Authentication relies on a short-lived access token issued from an API key.

​

Operating model

Creation of a charge is synchronous: the response contains the transaction identifier and the data required for payment. Confirmation of payment is asynchronous for Pix and boleto, and the platform communicates it to the integrator’s system by notification. It is recommended that the integration treat the notification as the trigger for releasing the product or service and use retrieval of the transaction as the reference source for verification.

Quickstart

From issuance of the token to confirmation of the first payment.

Transaction lifecycle

Statuses, transitions and associated events.

Infractions and MED

Effects of an infraction report on the transaction and the balance.

Regulatory references

Applicable laws, regulations and technical standards.