Advanced webhooks subscriptions

The workflow of the Orchestration API can be synchronous or asynchronous depending on the payment method used and the payment partner. For asynchronous updates, merchants can specify a webhook URL and headers in order to be called back with.

How to set up webhooks

When creating a client session or a payment, the merchant can specify a webhook URL and headers to call back.

{
  "url": "https://www.example.org/payment-hook?order_id=123456789",
  "event_types": [
    "PAYMENT_AUTHORIZATION"
  ],
  "headers": [
    {
      "name": "x-custom-header",
      "values": [
        "x-custom-header-value"
      ]
    }
  ]
}

Event types

Those events allow merchants to be notified on specific changes of the payment, default set to PAYMENT (which contains all the payment information).

The following event types available are:

• PAYMENT: any payment status changes

Default Event Type

See Webhook section

• PAYMENT_AUTHORIZATION: any partner_transactions in authorization status changes
  • specific key: authorization

PAYMENT_AUTHORIZATION Example

{
  "authorization": {
    "updated_at": "2025-01-01T00:00:00.000Z",
    "status": "AUTHORIZED",
    "partner_transactions": [
      {
        "partner": "partner",
        "method": "method",
        "id": "366ee67a-16bc-4aa8-8e73-95bc1df09e35",
        "amount": 10000,
        "remaining_amount": 10000,
        "created_at": "2025-01-01T00:00:00.000Z",
        "updated_at": "2025-01-01T00:00:00.000Z",
        "partner_reference": "014ddeea-c1a6-4bfc-abf7-80443dcb6646",
        "partner_status": "SUCCESS",
        "partner_status_description": "Successful",
        "status": "AUTHORIZED"
      }
    ]
  },
  "payment": {
    "id": "767c7c08-401a-465d-acb3-5bf02fe30ecc",
    "entity_id": "857d47ea-d6e0-4146-b195-9a64d9a4f51d",
    "client_session_id": "66be2b9c-cf77-462e-ba1d-d65cd7bba2f2",
    "amount": 10000,
    "currency": "EUR",
    "amounts": {
      "authorize_pending": 0,
      "total_authorized": 10000,
      "available_to_capture": 10000,
      "total_captured": 0,
      "available_to_void": 10000,
      "total_voided": 0,
      "available_to_refund": 0,
      "total_refunded": 0
    }
  },
  "event_type": "PAYMENT_AUTHORIZATION"
}

• PAYMENT_AUTHORIZATION_PARTNER_TRANSACTION: partner_transactions status changes in authorization
  • specific key: authorization_partner_transaction

PAYMENT_AUTHORIZATION_PARTNER_TRANSACTION Example

{
  "authorization_partner_transaction": {
    "partner": "partner",
    "method": "method",
    "id": "366ee67a-16bc-4aa8-8e73-95bc1df09e35",
    "amount": 10000,
    "remaining_amount": 10000,
    "created_at": "2025-01-01T00:00:00.000Z",
    "updated_at": "2025-01-01T00:00:00.000Z",
    "partner_reference": "014ddeea-c1a6-4bfc-abf7-80443dcb6646",
    "partner_status": "SUCCESS",
    "partner_status_description": "Successful",
    "status": "AUTHORIZED"
  },
  "payment": {
    "id": "767c7c08-401a-465d-acb3-5bf02fe30ecc",
    "entity_id": "857d47ea-d6e0-4146-b195-9a64d9a4f51d",
    "client_session_id": "66be2b9c-cf77-462e-ba1d-d65cd7bba2f2",
    "amount": 10000,
    "currency": "EUR",
    "amounts": {
      "authorize_pending": 0,
      "total_authorized": 10000,
      "available_to_capture": 10000,
      "total_captured": 0,
      "available_to_void": 10000,
      "total_voided": 0,
      "available_to_refund": 0,
      "total_refunded": 0
    }
  },
  "event_type": "PAYMENT_AUTHORIZATION_PARTNER_TRANSACTION"
}

• PAYMENT_CAPTURE: any partner_transactions in captures status changes
  • specific key: capture

PAYMENT_CAPTURE Example

{
  "capture": {
    "id": "b9ca4747-e798-4ae4-9fcc-25e5d48d62ad",
    "created_at": "2025-01-01T00:00:00.000Z",
    "updated_at": "2025-01-01T00:00:00.000Z",
    "amount": 5000,
    "triggered_by": "MERCHANT",
    "status": "SUCCESS",
    "partner_transactions": [
      {
        "partner": "partner",
        "method": "method",
        "id": "fd2b2727-e0e2-4561-a975-3a8c40df2c5c",
        "amount": 5000,
        "remaining_amount": 5000,
        "created_at": "2025-01-01T00:00:00.000Z",
        "updated_at": "2025-01-01T00:00:00.000Z",
        "partner_reference": "536e871b-0595-46ba-bf21-946826d547c3",
        "partner_status": "SUCCESS",
        "partner_status_description": "Successful",
        "status": "SUCCESS"
      }
    ]
  },
  "payment": {
    "id": "767c7c08-401a-465d-acb3-5bf02fe30ecc",
    "entity_id": "857d47ea-d6e0-4146-b195-9a64d9a4f51d",
    "client_session_id": "66be2b9c-cf77-462e-ba1d-d65cd7bba2f2",
    "amount": 10000,
    "currency": "EUR",
    "amounts": {
      "authorize_pending": 0,
      "total_authorized": 10000,
      "available_to_capture": 5000,
      "total_captured": 5000,
      "available_to_void": 5000,
      "total_voided": 0,
      "available_to_refund": 5000,
      "total_refunded": 0
    }
  },
  "event_type": "PAYMENT_CAPTURE"
}

• PAYMENT_CAPTURE_PARTNER_TRANSACTION: partner_transactions status changes in captures
  • specific key: capture_partner_transaction

PAYMENT_CAPTURE_PARTNER_TRANSACTION Example

{
  "payment": {
    "id": "767c7c08-401a-465d-acb3-5bf02fe30ecc",
    "entity_id": "857d47ea-d6e0-4146-b195-9a64d9a4f51d",
    "client_session_id": "66be2b9c-cf77-462e-ba1d-d65cd7bba2f2",
    "amount": 10000,
    "currency": "EUR",
    "amounts": {
      "authorize_pending": 0,
      "total_authorized": 10000,
      "available_to_capture": 5000,
      "total_captured": 5000,
      "available_to_void": 5000,
      "total_voided": 0,
      "available_to_refund": 5000,
      "total_refunded": 0
    }
  },
  "event_type": "PAYMENT_CAPTURE_PARTNER_TRANSACTION",
  "capture_partner_transaction": {
    "partner": "partner",
    "method": "method",
    "id": "fd2b2727-e0e2-4561-a975-3a8c40df2c5c",
    "amount": 5000,
    "remaining_amount": 5000,
    "created_at": "2025-01-01T00:00:00.000Z",
    "updated_at": "2025-01-01T00:00:00.000Z",
    "partner_reference": "536e871b-0595-46ba-bf21-946826d547c3",
    "partner_status": "SUCCESS",
    "partner_status_description": "Successful",
    "status": "SUCCESS"
  }
}

• PAYMENT_VOID: any partner_transactions in voids status changes
  • specific key: void

PAYMENT_VOID Example

{
  "payment": {
    "id": "767c7c08-401a-465d-acb3-5bf02fe30ecc",
    "entity_id": "857d47ea-d6e0-4146-b195-9a64d9a4f51d",
    "client_session_id": "66be2b9c-cf77-462e-ba1d-d65cd7bba2f2",
    "amount": 10000,
    "currency": "EUR",
    "amounts": {
      "authorize_pending": 0,
      "total_authorized": 10000,
      "available_to_capture": 0,
      "total_captured": 5000,
      "available_to_void": 0,
      "total_voided": 5000,
      "available_to_refund": 0,
      "total_refunded": 5000
    }
  },
  "void": {
    "id": "7a852b15-beae-402f-875c-6e1e3de71a12",
    "created_at": "2025-01-01T00:00:00.000Z",
    "updated_at": "2025-01-01T00:00:00.000Z",
    "amount": 5000,
    "triggered_by": "MERCHANT",
    "status": "SUCCESS",
    "partner_transactions": [
      {
        "partner": "partner",
        "method": "method",
        "id": "d0933af7-9ddf-4640-9d35-d44c9909569a",
        "amount": 5000,
        "created_at": "2025-01-01T00:00:00.000Z",
        "updated_at": "2025-01-01T00:00:00.000Z",
        "partner_reference": "06e97d98-9633-4731-ae6c-4a410d1d2c2e",
        "partner_status": "SUCCESS",
        "partner_status_description": "Successful",
        "status": "SUCCESS"
      }
    ]
  },
  "event_type": "PAYMENT_VOID"
}

• PAYMENT_VOID_PARTNER_TRANSACTION: partner_transactions status changes in voids
  • specific key: void_partner_transaction

PAYMENT_VOID_PARTNER_TRANSACTION Example

{
  "void_partner_transaction": {
    "partner": "partner",
    "method": "method",
    "id": "d0933af7-9ddf-4640-9d35-d44c9909569a",
    "amount": 5000,
    "created_at": "2025-01-01T00:00:00.000Z",
    "updated_at": "2025-01-01T00:00:00.000Z",
    "partner_reference": "06e97d98-9633-4731-ae6c-4a410d1d2c2e",
    "partner_status": "SUCCESS",
    "partner_status_description": "Successful",
    "status": "SUCCESS"
  },
  "payment": {
    "id": "767c7c08-401a-465d-acb3-5bf02fe30ecc",
    "entity_id": "857d47ea-d6e0-4146-b195-9a64d9a4f51d",
    "client_session_id": "66be2b9c-cf77-462e-ba1d-d65cd7bba2f2",
    "amount": 10000,
    "currency": "EUR",
    "amounts": {
      "authorize_pending": 0,
      "total_authorized": 10000,
      "available_to_capture": 0,
      "total_captured": 5000,
      "available_to_void": 0,
      "total_voided": 5000,
      "available_to_refund": 0,
      "total_refunded": 5000
    }
  },
  "event_type": "PAYMENT_VOID_PARTNER_TRANSACTION"
}

• PAYMENT_REFUND: any partner_transactions in refunds status changes
  • specific key: refund

PAYMENT_REFUND Example

{
  "payment": {
    "id": "767c7c08-401a-465d-acb3-5bf02fe30ecc",
    "entity_id": "857d47ea-d6e0-4146-b195-9a64d9a4f51d",
    "client_session_id": "66be2b9c-cf77-462e-ba1d-d65cd7bba2f2",
    "amount": 10000,
    "currency": "EUR",
    "amounts": {
      "authorize_pending": 0,
      "total_authorized": 10000,
      "available_to_capture": 0,
      "total_captured": 5000,
      "available_to_void": 0,
      "total_voided": 5000,
      "available_to_refund": 0,
      "total_refunded": 5000
    }
  },
  "event_type": "PAYMENT_REFUND",
  "refund": {
    "id": "971a13dd-fbdf-4d54-863c-76c2c228abbf",
    "created_at": "2025-01-01T00:00:00.000Z",
    "updated_at": "2025-01-01T00:00:00.000Z",
    "amount": 5000,
    "triggered_by": "MERCHANT",
    "status": "SUCCESS",
    "partner_transactions": [
      {
        "partner": "partner",
        "method": "method",
        "id": "9f83628f-1c52-4a53-b2fd-627cd3d661fc",
        "amount": 5000,
        "created_at": "2025-01-01T00:00:00.000Z",
        "updated_at": "2025-01-01T00:00:00.000Z",
        "partner_reference": "73c57074-308a-49a7-9e3c-9a8d42680c15",
        "partner_status": "SUCCESS",
        "partner_status_description": "Successful",
        "status": "SUCCESS"
      }
    ]
  }
}

• PAYMENT_REFUND_PARTNER_TRANSACTION: partner_transactions status changes in refunds
  • specific key: refund_partner_transaction

PAYMENT_REFUND_PARTNER_TRANSACTION Example

{
  "refund_partner_transaction": {
    "partner": "partner",
    "method": "method",
    "id": "9f83628f-1c52-4a53-b2fd-627cd3d661fc",
    "amount": 5000,
    "created_at": "2025-01-01T00:00:00.000Z",
    "updated_at": "2025-01-01T00:00:00.000Z",
    "partner_reference": "73c57074-308a-49a7-9e3c-9a8d42680c15",
    "partner_status": "SUCCESS",
    "partner_status_description": "Successful",
    "status": "SUCCESS"
  },
  "payment": {
    "id": "767c7c08-401a-465d-acb3-5bf02fe30ecc",
    "entity_id": "857d47ea-d6e0-4146-b195-9a64d9a4f51d",
    "client_session_id": "66be2b9c-cf77-462e-ba1d-d65cd7bba2f2",
    "amount": 10000,
    "currency": "EUR",
    "amounts": {
      "authorize_pending": 0,
      "total_authorized": 10000,
      "available_to_capture": 0,
      "total_captured": 5000,
      "available_to_void": 0,
      "total_voided": 5000,
      "available_to_refund": 0,
      "total_refunded": 5000
    }
  },
  "event_type": "PAYMENT_REFUND_PARTNER_TRANSACTION"
}

Any event type other than PAYMENT go with a summary of relevant information of the payment such as id, entity_id, amount, currency and amounts. Those different parts of the payment are under a different named specific key.