Webhook V2 (Recommended)

Real-time event notifications for your application

Webhook V2 is our latest and most advanced webhook implementation, designed with modern integration needs in mind. It provides a more robust, organized, and feature-rich experience compared to V1.

Why choose Webhook V2?

Enhanced Data Structure

  • Event-based architecture with clear event names
  • Standardized field naming with snake_case
  • Separate payer and receiver information
  • Comprehensive banking institution details (ISPB)

    • Improved Organization

  • Clear separation between event type and payload
  • Consistent structure across all webhook types
  • Better null handling and optional fields
  • More predictable data formats

    • More Event Types

  • cashin.paid - Transaction successfully paid
  • cashin.refunded - Transaction refunded
  • cashout.success - Withdrawal completed successfully
  • cashout.failed - Withdrawal failed
  • cashout.returned - Withdrawal returned to origin
  • infraction.updated - Infraction status updated

    • We strongly recommend using Webhook V2 for all new integrations.

    1Webhook Structure

    All V2 webhooks follow a consistent structure with two main components: the event type and the payload.

    json
    {
  "event": "event.name",
  "payload": {
    // Event-specific data
  }
}

    2Cash-In Events (Transactions)

    Cash-in webhooks are triggered when transactions (deposits/payments) are processed.

    Event Types:

  • cashin.paid - Transaction successfully paid and credited
  • cashin.refunded - Transaction was refunded to the payer

    • Payload Example:

    json
    {
  "event": "cashin.paid",
  "payload": {
    "transaction_id": "17615714245971918718644287",
    "external_id": "your-business-transaction-id",
    "amount": 1100,
    "end_to_end_id": "E18236120202510271324s05499b347c",
    "payer": {
      "name": "Rafael Arantes da Silva",
      "document": "43363629800",
      "ispb": "19318318",
      "institution": "NU PAGAMENTOS"
    },
    "receiver": {
      "name": "Your Business Name",
      "document": "12345678000190",
      "ispb": "18236120",
      "institution": "BANCO EXEMPLO"
    }
  }
}

    Field Descriptions:

  • transaction_id: Internal transaction identifier
  • external_id: Your business transaction ID (set during transaction creation)
  • amount: Transaction amount in cents (1100 = R$ 11,00)
  • end_to_end_id: Unique PIX identifier for tracking
  • payer: Information about who made the payment
  • receiver: Information about who received the payment
  • ispb: Bank identification code (Brazilian banking system)
  • institution: Bank name

    • 3Cash-Out Events (Withdrawals)

    Cash-out webhooks are triggered when withdrawal operations are processed.

    Event Types:

  • cashout.success - Withdrawal completed successfully
  • cashout.failed - Withdrawal failed (includes error message)
  • cashout.returned - Withdrawal was returned to the original account

    • Success/Returned Payload Example:

    json
    {
  "event": "cashout.success",
  "payload": {
    "withdrawal_id": "17615714245971918718644287",
    "external_id": "your-business-withdrawal-id",
    "amount": 5000,
    "end_to_end_id": "E18236120202510271324s05499b347c",
    "receiver": {
      "name": "João Silva",
      "document": "12345678900",
      "ispb": "60701190",
      "institution": "ITAU UNIBANCO"
    },
    "payer": {
      "name": "Your Business Name",
      "document": "12345678000190",
      "ispb": "18236120",
      "institution": "BANCO EXEMPLO"
    }
  }
}

    Failed Payload Example:

    json
    {
  "event": "cashout.failed",
  "payload": {
    "withdrawal_id": "17615714245971918718644287",
    "external_id": "your-business-withdrawal-id",
    "amount": 5000,
    "end_to_end_id": "E18236120202510271324s05499b347c",
    "error_message": "Invalid PIX key or account closed"
  }
}

    Field Descriptions:

  • withdrawal_id: Internal withdrawal identifier
  • external_id: Your business withdrawal ID
  • amount: Withdrawal amount in cents
  • end_to_end_id: Unique PIX identifier
  • receiver: Who receives the withdrawal (destination)
  • payer: Who is sending the withdrawal (your business)
  • error_message: Error details (only present in failed events)

    • 4Infraction Events

    Infraction webhooks are sent when there are compliance or dispute-related updates on transactions.

    Event Type:

  • infraction.updated - Infraction status or details changed

    • Payload Example:

    json
    {
  "event": "infraction.updated",
  "payload": {
    "transaction_id": "17615714245971918718644287",
    "external_id": "your-business-transaction-id",
    "amount": 1100,
    "end_to_end_id": "E18236120202510271324s05499b347c",
    "payer": {
      "name": "Rafael Arantes da Silva",
      "document": "43363629800",
      "ispb": "19318318",
      "institution": "NU PAGAMENTOS"
    },
    "receiver": {
      "name": "Your Business Name",
      "document": "12345678000190",
      "ispb": "18236120",
      "institution": "BANCO EXEMPLO"
    },
    "infraction": {
      "id": "dd0b2c77-8dd6-4eb5-b254-a46417eac46d",
      "status": "AWAITING_CUSTOMER_RESPONSE",
      "reason_details": "Payer reported unauthorized transaction",
      "analysis_result": null,
      "analysis_details": "Under investigation by compliance team",
      "created_at": "2025-10-27T14:30:00.000Z",
      "closed_at": null,
      "cancelled_at": null,
      "response_at": null,
      "defended_at": null
    }
  }
}

    Infraction Status Values:

  • AWAITING_CUSTOMER_RESPONSE: Waiting for your response or additional information
  • UNDER_REVIEW: Being reviewed by compliance team
  • AWAITING_ADDITIONAL_INFO: Additional information required
  • CLOSED: Infraction resolved and closed
  • CANCELLED: Infraction cancelled

    • Analysis Result Values:

  • AGREED: Analysis agreed with the infraction claim
  • DISAGREED: Analysis disagreed with the infraction claim
  • null: Analysis not yet completed

    • 5Important Notes

    General Guidelines:

  • All amounts are expressed in cents (centavos): 1000 = R$ 10,00
  • Timestamps are in ISO 8601 format (UTC)
  • The external_id is your business identifier set during creation
  • The end_to_end_id is unique across the entire PIX ecosystem

    • Webhook Security:

  • Validate webhook signatures to ensure authenticity
  • Implement idempotency to handle duplicate webhooks
  • Return HTTP 200 status to acknowledge receipt
  • Process webhooks asynchronously to avoid timeouts

    • Best Practices:

  • Store transaction_id or withdrawal_id for reconciliation
  • Use external_id to match with your internal system
  • Log all webhook events for audit purposes
  • Implement retry logic for failed webhook processing
  • Monitor webhook delivery status through our dashboard

    • Need more help?

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

    View API Reference →Contact Support →