Use webhooks to get automatic, real-time updates on your transactions. Subscribe with the Webhooks API. When a payment status changes, Bitso sends a notification to your URL via an HTTP POST request.

📘
Important Guidelines

We don't guarantee the order of event delivery. Your application should be able to process events that may arrive out of sequence.

The same event might be delivered multiple times. Your application must be idempotent to handle this possibility.

Your endpoint must respond in under five seconds to avoid a timeout. For best performance, we recommend storing the notification and processing it asynchronously.

For transport, signing, and subscription details, see Webhooks.

How to Register Your Webhook

Subscribe with Create webhook subscriptions. For Pay with Bitso, pass payment_intent in events. See Managing Subscriptions and Webhook Signatures.

Webhook Payload Structure

When any of the payment_intent events listed below occur, Bitso sends a JSON object to your registered URL.

CREATED: Payment intent was successfully created.
PENDING: The user has accessed the payment link.
PROCESSING: The payment is being processed.
COMPLETED: The payment was successfully completed.
FAILED: Payment encountered an error.
EXPIRED: The payment intent expired before completion.

Payload Examples

Here are some examples of the payloads you'll receive for each status:

{
  "event": "payment_intent",
  "payload": {
    "id": "7fb1011c-e451-48d5-85c4-207d1ea97b1d",
    "external_ref": "client_ref_124",
    "amount": 100.5,
    "asset": "MXN",
    "created_at": "2025-09-15T15:17:13.821281Z",
    "expires_at": "2025-09-15T16:17:13.806476Z",
    "status": "CREATED",
    "type": "PAY_WITH_BITSO",
    "pay_with_bitso": {
      "success_redirect_url": "https://example.com/success",
      "error_redirect_url": "https://example.com/error",
      "duration": "PT1H",
      "universal_link": "https://bitso.com/pay-with-bitso/7fb1011c-e451-48d5-85c4-207d1ea97b1d"
    }
  }
}

{
  "event": "payment_intent",
  "payload": {
    "id": "7fb1011c-e451-48d5-85c4-207d1ea97b1d",
    "external_ref": "client_ref_124",
    "amount": 100.5,
    "asset": "MXN",
    "created_at": "2025-09-15T15:17:13.821281Z",
    "updated_at": "2025-09-15T15:17:21.018277Z",
    "expires_at": "2025-09-15T16:17:13.806476Z",
    "status": "PENDING",
    "type": "PAY_WITH_BITSO",
    "pay_with_bitso": {
      "success_redirect_url": "https://example.com/success",
      "error_redirect_url": "https://example.com/error",
      "duration": "PT1H",
      "universal_link": "https://bitso.com/pay-with-bitso/7fb1011c-e451-48d5-85c4-207d1ea97b1d",
      "universal_link_visited_at": "2025-09-15T15:17:21.011332Z"
    }
  }
}

{
  "event": "payment_intent",
  "payload": {
    "id": "7fb1011c-e451-48d5-85c4-207d1ea97b1d",
    "external_ref": "client_ref_124",
    "amount": 100.5,
    "asset": "MXN",
    "created_at": "2025-09-15T15:17:13.821281Z",
    "updated_at": "2025-09-15T15:17:25.187579Z",
    "expires_at": "2025-09-15T16:17:13.806476Z",
    "status": "PROCESSING",
    "type": "PAY_WITH_BITSO",
    "pay_with_bitso": {
      "success_redirect_url": "https://example.com/success",
      "error_redirect_url": "https://example.com/error",
      "duration": "PT1H",
      "universal_link": "https://bitso.com/pay-with-bitso/7fb1011c-e451-48d5-85c4-207d1ea97b1d",
      "universal_link_visited_at": "2025-09-15T15:17:21.011332Z"
    }
  }
}

{
  "event": "payment_intent",
  "payload": {
    "id": "7fb1011c-e451-48d5-85c4-207d1ea97b1d",
    "external_ref": "client_ref_124",
    "amount": 100.5,
    "asset": "MXN",
    "created_at": "2025-09-15T15:17:13.821281Z",
    "updated_at": "2025-09-15T15:17:28.384443Z",
    "expires_at": "2025-09-15T16:17:13.806476Z",
    "fid": "2bae0a63cc1ad74d3ad465cf50ed050d",
    "status": "COMPLETED",
    "type": "PAY_WITH_BITSO",
    "pay_with_bitso": {
      "success_redirect_url": "https://example.com/success",
      "error_redirect_url": "https://example.com/error",
      "duration": "PT1000000000000H",
      "universal_link": "https://bitso.com/pay-with-bitso/7fb1011c-e451-48d5-85c4-207d1ea97b1d",
      "universal_link_visited_at": "2025-09-15T15:17:21.011332Z"
    }
  }
}