Webhook V1

Real-time event notifications for your application

Webhooks are HTTP callbacks that notify your application in real-time when specific events occur in our system. The V1 version is our legacy webhook implementation that has been serving our customers reliably.

Important Notice: While Webhook V1 remains fully operational and supported, we highly recommend migrating to Webhook V2 for new integrations. V2 offers enhanced features, better organization, more comprehensive data, and improved reliability.

What's included in V1:

  • Transaction status updates
  • Withdraw status notifications
  • Basic infraction information
  • Standard payload structure

    • 1Transaction Webhook

    Webhooks are sent when transaction statuses are updated. There are two types of webhook payloads depending on whether the transaction has an associated infraction.

    Standard Transaction Update

    When a transaction is updated, the following webhook will be sent:

    json
    {
  "transactionId": "23456789",
  "externalId": "your-business-id",
  "payerDocument": "payer-document",
  "payerFullName": "payer-name",
  "status": "APPROVED",
  "endToEnd": "end-to-end-id",
  "amount": 5000,
  "type": "TRANSACTION"
}

    Transaction Update with Infraction

    When a transaction is updated WITH INFRACTION, the following webhook will be sent:

    json
    {
  "transactionId": "23456789",
  "externalId": "your-business-id",
  "payerDocument": "payer-document",
  "payerFullName": "payer-name",
  "status": "APPROVED",
  "infraction": {
    "id": "dd0b2c77-8dd6-4eb5-b254-a46417eac46d",
    "status": "AWAITING_CUSTOMER_RESPONSE",
    "closedAt": null,
    "createdAt": "2025-06-29T00:18:00.580Z",
    "defendedAt": null,
    "responseAt": null,
    "cancelledAt": null,
    "reasonDetails": "reason details",
    "analysisResult": null,
    "analysisDetails": "analysis details"
  },
  "endToEnd": "end-to-end-id",
  "amount": 5000,
  "type": "TRANSACTION"
}

    Transaction Status Values:

  • APPROVED: Transaction has been approved and processed successfully
  • BLOCKED: Transaction has been placed under precautionary hold due to security or compliance verification procedures
  • PENDING: Transaction is awaiting processing
  • REJECTED: Transaction has been rejected
  • REFUNDED: Transaction has been successfully refunded
  • REFUNDED_PROCESSING: Refund is currently being processed
  • CHARGEBACK: Transaction has been successfully chargedback

    • Infraction Status Values:

  • AWAITING_CUSTOMER_RESPONSE: Waiting for customer to provide a response
  • UNDER_REVIEW: Infraction is currently being reviewed
  • AWAITING_ADDITIONAL_INFO: Additional information is required
  • CLOSED: Infraction has been resolved and closed
  • CANCELLED: Infraction has been cancelled

    • 2Withdraw Webhook

    Webhooks are sent when withdraw statuses are updated. The webhook provides comprehensive information about the withdraw operation including status, receiver details, and any error messages.

    Withdraw Update

    When a withdraw is updated, the following webhook will be sent:

    json
    {
  "withdrawId": "123456789",
  "externalId": "your-business-id",
  "receiverName": "receiver-name",
  "receiverDocument": "receiver-document",
  "errorMessage": "Invalid pix",
  "status": "WITHDRAW_APPROVED",
  "endToEnd": "end-to-end-id",
  "voucher": "voucher-url",
  "amount": 5000,
  "type": "WITHDRAW"
}

    Withdraw Status Values:

  • WITHDRAW_APPROVED: Withdraw has been approved and processed successfully
  • WITHDRAW_ERROR: Withdraw encountered an error during processing
  • WITHDRAW_REQUEST: Withdraw request has been submitted and is awaiting processing
  • WITHDRAW_PROCESSING: Withdraw is currently being processed
  • WITHDRAW_RETURNED: Withdrawal was refunded and the funds were returned to the original account

    • Important Notes:

  • The errorMessage field provides specific details when a withdraw fails
  • The voucher field contains a URL to access the receipt
  • The amount field is always expressed in cents
  • All timestamps are in ISO 8601 format (UTC)

    • Need more help?

    Check our complete API reference or contact our support team for assistance.

    View API Reference →Contact Support →