Quickstart

Minimum sequence to create a Pix charge and confirm the payment.

This guide presents the minimum sequence of operations to create a Pix charge and confirm its settlement. The data used in the examples is fictitious.

​

Prerequisites

The integration requires an API key, composed of a public identifier and a secret. The secret is displayed only once, when the key is generated, and must be kept in a secure credential store.

​

Sequence of operations

1. Issue the access token

   The API key is exchanged for an access token using HTTP Basic authentication. The public identifier takes the position of the username, and the secret, that of the password.

   curl -X POST https://api.fincle.com.br/auth \
     -u "$FINCLE_API_KEY:$FINCLE_API_SECRET"
   

   The token field of the response must be presented in subsequent requests. The token is valid for one minute, as stated in milliseconds in the expiresIn field.

2. Create the charge

   The charge is created with the amount, in cents, and the identification of the payer.

   curl -X POST https://api.fincle.com.br/pix/in/qrcode \
     -H "Authorization: Bearer $FINCLE_TOKEN" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: 7c1f0b9e-3a52-4d6c-9e1b-5f2a8c4d7e10" \
     -d '{
       "amountInCents": 125000,
       "description": "Invoice no. 2026/001042",
       "postbackUrl": "https://api.example.com/webhooks/fincle",
       "customer": {
         "name": "Helena Martins Andrade",
         "email": "[e-mail]",
         "documentType": "cpf",
         "document": "31845792041"
       }
     }'
   

   The response contains the transaction identifier (id), the initial status pending and, in the pix.emv field, the BR Code to be presented to the payer.

3. Receive the notification

   Once the Pix is settled, the platform sends the transaction_paid event to the URL given in postbackUrl and to the webhooks registered on the account. The endpoint must respond with a 2xx status.

4. Verify the transaction

   The status of the transaction can be verified at any time through the retrieval operation.

   curl https://api.fincle.com.br/transactions/cmddiqpxo09zf1yju2kqkhgga \
     -H "Authorization: Bearer $FINCLE_TOKEN"
   

​

Next steps

Once the Pix integration is complete, the guides on credit card and boleto are recommended, as well as the procedures for refunds and for handling infractions. The general rules on idempotency, pagination and error handling are set out in API conventions.