Webhooks¶

Webhooks provide server-to-server notifications when a payin or payout order reaches a final status.

Webhooks allow the merchant system to receive the final order result asynchronously, without continuously polling the order retrieval endpoints.

Overview¶

A webhook is an HTTP request sent to a merchant-provided URL when an order reaches a final status.

When a payin or payout order reaches a final status, a webhook request is sent to notify the merchant of the completed order result.

The merchant can use this notification to update the order state in its own system, release goods or services to the customer, or perform another business action based on the final order status.

Webhook URL¶

The webhook request is sent to one of the merchant URLs configured for order status notifications.

The webhook URL can use either http or https.

URL Selection Priority¶

The webhook destination URL is selected using the following priority:

Priority	URL source	Description
1	Order-level `callback_url`	Used when the merchant provides `callback_url` in the create order request.
2	Merchant-level webhook URL	Used when `callback_url` is not provided for the specific order.

Merchant-level webhook URLs are configured separately for payin and payout notifications:

Order type	Merchant-level URL
Payin order	Payin webhook URL
Payout order	Payout webhook URL

If callback_url is provided for a specific order, it overrides the corresponding merchant-level webhook URL for that order.

When Webhooks Are Sent¶

A webhook is sent when an order reaches a final status.

Currently, webhooks are sent for the following final statuses:

Status	Description
`SUCCESS`	The order was completed successfully.
`FAILED`	The order failed and was not completed successfully.
`CLOSED`	The order was closed after its lifecycle was completed or after the waiting time was exceeded.

Intermediate statuses, such as CREATED, IN_PROGRESS, or PROCESS_PENDING, do not trigger webhook notifications.

Webhook Request¶

Webhooks are sent as HTTP POST requests.

The webhook request body is sent in JSON format and contains an array of order objects.

The array can contain one or multiple order objects. Multiple objects can be included when several related orders are associated with the same reference_id.

Request Headers¶

Content-Type string required

Indicates that the webhook request body is sent in JSON format.

Example: application/json

X-Signature string required

Webhook request signature generated from the raw webhook request body using the same signature algorithm as regular API requests.

Webhook signature

The signature is calculated from the webhook request body and sent in the X-Signature header.

The merchant should verify the received webhook by calculating the signature from the raw webhook request body and comparing it with the X-Signature header value.

For signature generation rules, see Request Signature Authentication.

Webhook Payload¶

The webhook request body contains an array of order objects.

The payload structure depends on the order type:

Order type	Webhook payload structure
Payin order	Same structure as the response body of the Get Payin Orders by Reference ID endpoint.
Payout order	Same structure as the response body of the Get Payout Orders by Reference ID endpoint.

The merchant should process each object in the array and use the status field to determine the final order result.

Get Payin Order by Reference›

Get Payout Order by Reference›

Payin Webhook Example¶

This example shows a webhook request sent when a payin order reaches the SUCCESS status.

POST https://merchant.example.com/webhooks/payin HTTP/1.1
Content-Type: application/json
X-Signature: <generated-signature>

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "reference_id": "merchant-order-12345",
    "status": "SUCCESS",
    "payment_source": "CARD",
    "currency": "USD",
    "amount": 100,
    "fee_percent": 1,
    "fee_fixed": 0,
    "fee_min": 0,
    "fee_max": 0,
    "hold_amount": 80,
    "rolling_percent": 20,
    "rolling_amount": 20,
    "fee_total": 1,
    "total": 99,
    "company_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "merchant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "gate_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "payment_method_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "payment_method_data": {
      "bank_id": "mbfygyv1gwi3-yocoiesaybdoexliswi0h0rkz97uinw0misx-sw5t",
      "cpf": "02093598630",
      "date_of_birth": "2026-06-09",
      "iban": "VEVX1P1YSDY7GI3UP5QOM",
      "ifsc": "10-pj0h9as8q5onjrnjbms7ouwd0u-h_9818",
      "payment_url": "string",
      "pix_key": "string",
      "tckn": "37319194678"
    },
    "terminal_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "routing_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "comment_internal": "string",
    "comment_external": "string",
    "customer": {
      "reference_id": "customer-12345",
      "first_name": "John",
      "last_name": "Doe",
      "email": "[user@example.com](mailto:user@example.com)",
      "phone": "+46138753016",
      "address": {
        "country": "FR",
        "city": "Paris",
        "street": "Example Street 1",
        "post_code": "75001"
      }
    },
    "pay_url": "string",
    "return_url": "string",
    "create_date": "2026-06-09T13:41:58.588Z",
    "update_date": "2026-06-09T13:41:58.588Z"
  }
]

Payout Webhook Example¶

This example shows a webhook request sent when a payout order reaches the SUCCESS status.

POST https://merchant.example.com/webhooks/payout HTTP/1.1
Content-Type: application/json
X-Signature: <generated-signature>

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "reference_id": "merchant-payout-12345",
    "status": "SUCCESS",
    "resolution": "OK",
    "resolution_message": "string",
    "provider_error_message": "string",
    "payment_source": "CARD",
    "currency": "USD",
    "amount": 100,
    "destination_account": "string",
    "fee_percent": 1,
    "fee_fixed": 0,
    "fee_min": 0,
    "fee_max": 0,
    "fee_total": 1,
    "total": 101,
    "payment_method_data": {
      "bank_id": "mbfygyv1gwi3-yocoiesaybdoexliswi0h0rkz97uinw0misx-sw5t",
      "cpf": "02093598630",
      "date_of_birth": "2026-06-09",
      "iban": "VEVX1P1YSDY7GI3UP5QOM",
      "ifsc": "10-pj0h9as8q5onjrnjbms7ouwd0u-h_9818",
      "payment_url": "string",
      "pix_key": "string",
      "tckn": "37319194678"
    },
    "customer": {
      "reference_id": "customer-12345",
      "first_name": "John",
      "last_name": "Doe",
      "email": "[user@example.com](mailto:user@example.com)",
      "phone": "+46138753016",
      "address": {
        "country": "FR",
        "city": "Paris",
        "street": "Example Street 1",
        "post_code": "75001"
      }
    },
    "create_date": "2026-06-09T13:41:58.588Z",
    "update_date": "2026-06-09T13:41:58.588Z",
    "comment": "string"
  }
]

Merchant Response¶

To confirm successful webhook delivery, the merchant webhook endpoint must return any 2xx HTTP status code.

No response body is required.

Examples of successful response statuses:

Status code	Meaning
`200 OK`	Webhook received successfully.
`201 Created`	Webhook received successfully.
`202 Accepted`	Webhook accepted for processing.
`204 No Content`	Webhook received successfully without response body.

Any non-2xx response is treated as an unsuccessful delivery.

Merchant Response Example¶

HTTP/1.1 204 No Content

Implementation Notes¶

The merchant should verify the X-Signature header before processing the webhook payload.

The merchant should process all objects in the webhook payload array.

The merchant should use the id, reference_id, and status fields to identify the order and apply the final result in its own system.