Webhooks

Webhooks are the mechanism by which the platform communicates, asynchronously, the events relating to transactions, infractions and transfers. For each event, the platform sends an HTTP POST request to the URL designated by the integrator.

Endpoint types

There are two types of endpoint, which may be used together.

Type	Configuration	Coverage
Per transaction	`postbackUrl` field, sent when creating the charge.	Events of the corresponding transaction. The notification body contains `scope: "postback"`.
Per account	Registration through `POST /v1/webhooks`, with the list of subscribed events.	Selected events of all transactions of the account. The notification body contains `scope: "user"`.

Registration

The POST /v1/webhooks operation registers the endpoint. The URL is verified at registration, and the absence of a response results in rejection of the request with status 400. The endpoint must therefore be published beforehand.

curl -X POST https://api.fincle.com.br/v1/webhooks \
  -H "Authorization: Bearer $FINCLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Financial management system",
    "url": "https://api.example.com/webhooks/fincle",
    "events": ["transaction_paid", "transaction_refunded", "infraction"]
  }'

Events

Event	Occurrence
`transaction_created`	Creation of a transaction.
`transaction_paid`	Confirmation of a payment.
`transaction_updated`	Change in the status of a transaction.
`card_declined`	Decline of a card charge.
`refund_requested`	Refund request submitted by the payer.
`transaction_refunded`	Return of a payment.
`infraction`	Opening or update of an infraction.
`transfer_created`	Creation of a transfer.
`transfer_updated`	Change in the status of a transfer.
`transfer_completed`	Completion of a transfer.
`transfer_canceled`	Cancellation of a transfer.

Notification structure

The notification body is a JSON object. The top-level fields are common to all events.

Field	Description
`id`	Unique identifier of the notification.
`type`	Source of the event: `transaction`, `transfer` or `infraction`.
`event`	Event that occurred.
`scope`	Endpoint type: `user` or `postback`.

Transaction event

{
  "id": "0d6e13bf-d348-4282-aebd-769f142ebcee",
  "type": "transaction",
  "event": "transaction_paid",
  "scope": "user",
  "transaction": {
    "id": "cmddiqpxo09zf1yju2kqkhgga",
    "amount": 125000,
    "netAmount": 123750,
    "status": "paid",
    "pix": {
      "endToEndId": "E18236120202611121410s12e9976c00",
      "payerInfo": null
    },
    "paidAt": "2026-11-12T14:10:17.000Z"
  },
  "customer": {
    "name": "Helena Martins Andrade",
    "email": "helena.andrade@example.com",
    "phone": "11932104567",
    "document": "31845792041",
    "documentType": "cpf",
    "purchaseDate": "2026-11-12T14:08:06.000Z"
  }
}

Field	Description
`transaction.id`	Transaction identifier.
`transaction.amount`	Gross amount, in cents.
`transaction.netAmount`	Net amount, after fees, in cents.
`transaction.status`	Status of the transaction at the time of the event.
`transaction.pix`	Pix data, when applicable: end-to-end identifier and payer information reported by the institution.
`transaction.paidAt`	Time at which the payment was confirmed.
`customer`	Identification of the payer.

For declined card charges, the transaction block additionally contains the refuseReason, acquirerCode and acquirerMessage fields.

Transfer event

{
  "id": "5b8e2c41-7d93-4f06-b2a8-1e6c9d3f7a52",
  "type": "transfer",
  "event": "transfer_completed",
  "scope": "user",
  "transfer": {
    "id": "cmdeqa3g300051wjn7gtacf1t",
    "amount": 1500000,
    "status": "completed",
    "pix": {
      "endToEndId": "E35713491202611121607s29656e25f1",
      "creditorAccount": null
    }
  }
}

The structure of the infraction event is set out in Infractions and MED.

Acknowledgement

The endpoint must respond with a 2xx status to acknowledge receipt. Any other response, as well as the absence of a response, is recorded as a delivery failure. It is recommended that the endpoint acknowledge receipt immediately and perform processing asynchronously.

Retries

In the event of failure, the platform repeats the delivery, up to a limit of five attempts per notification. Once the limit is exhausted, the delivery remains recorded as failed and may be resent at the integrator’s request.

Endpoint requirements

Notification delivery follows at-least-once semantics. The endpoint must therefore meet the following requirements:

process each notification idempotently, using the id field to identify repetitions
not assume the order of arrival of notifications, and base decisions on the status reported in transaction.status
confirm the status of the transaction through GET /v1/transactions/{transactionId} before any irreversible act, as set out in Security and data protection

Testing

The POST /v1/webhooks/{webhookId}/test operation sends test notifications, with fictitious data, to the registered URL and returns the HTTP status returned by the endpoint for each delivery. No real transaction is created or changed.

Audit and redelivery

The GET /v1/webhook-deliveries operation lists the delivery attempts, with the event, the status and the destination URL. The status=error filter identifies the deliveries rejected by the endpoint. The GET /v1/webhook-deliveries/{deliveryId} operation returns the body sent and the response received in each attempt, which makes it possible to determine the origin of the failure. Once the endpoint is corrected, the POST /v1/webhook-deliveries/{deliveryId}/retry operation requests redelivery with the same body.

Introduction

Fundamentals

Charges

Post-payment

Compliance

Endpoint types

Registration

Events

Notification structure

Transaction event

Transfer event

Acknowledgement

Retries

Endpoint requirements

Testing

Audit and redelivery

​Endpoint types

​Registration

​Events

​Notification structure

​Transaction event

​Transfer event

​Acknowledgement

​Retries

​Endpoint requirements

​Testing

​Audit and redelivery

Endpoint types

Registration

Events

Notification structure

Transaction event

Transfer event

Acknowledgement

Retries

Endpoint requirements

Testing

Audit and redelivery