Webhook Payloads

This document describes the payload structure for payment, refund, and payout webhooks sent by the OrchestraPay system.

Payment Webhook

Sent when a payment's status changes. Payments can have three main statuses: pending, success, or canceled. Only the pending status is mutable - once a payment gets the success or canceled status, it is guaranteed that it will not change again.

Payment Webhook Parameters

idempotency_keystring

Unique key to prevent duplicate webhook processing

uuidstring

Unique identifier for the payment

idnumber

Internal payment ID

gatewaystring

Payment gateway used for the payment

statusstring

Main status of the payment (pending, success, or canceled)

sub_statusstring

Detailed status of the payment

preflight_idnumber

ID of the preflight object used to generate this payment

payloadobject

Additional payment data

amountnumber

Payment amount in cents

currencystring

Three-letter ISO currency code

step_numbernumber

Current step in payment flow

last_reasonstring

Last status reason or message

webhook_typestring

Type of webhook (always "payment" for payment webhooks)

RESPONSE

{
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "id": 123,
  "gateway": "paystack",
  "status": "success",
  "sub_status": "success",
  "preflight_id": 456,
  "payload": {},
  "amount": 1000,
  "currency": "EGP",
  "step_number": 3,
  "last_reason": null,
  "webhook_type": "payment"
}

Refund Webhook

Sent when a refund's status changes. Refunds can have three main statuses: pending, success, or canceled. Only the pending status is mutable - once a refund gets the success or canceled status, it is guaranteed that it will not change again.

Refund Webhook Parameters

idempotency_keystring

Unique key to prevent duplicate webhook processing

idnumber

Internal refund ID

statusstring

Main status of the refund (pending, success, or canceled)

sub_statusstring

Detailed status of the refund

transaction_idnumber

ID of the original payment being refunded

amountnumber

Refund amount in cents

currencystring

Three-letter ISO currency code

webhook_typestring

Type of webhook (always "refund" for refund webhooks)

RESPONSE

{
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "id": 123,
  "status": "success",
  "sub_status": "success",
  "transaction_id": 456,
  "amount": 1000,
  "currency": "EGP",
  "webhook_type": "refund"
}

Payout Webhook

Sent when a payout's status changes. Configure webhook_urls and an optional webhook_secret on POST /payouts. Orchestrapay POSTs the JSON body to each URL and sends Orchestrapay-Webhook-Secret when a secret was provided.

Payouts use the same promise model as refunds: main status is pending, success, or canceled (derived from sub_status), and sub_status carries the detailed value.

When webhooks are sent

Event	Typical sub_status	Notes
Payout row saved, before gateway initiation	pending_created	First notification after create.
Gateway reports in-flight / retry	pending_promise	After initiation when the transfer is still processing.
Transfer completed	success	Funds sent successfully.
Gateway rejected the transfer	canceled_rejected	e.g. invalid account, insufficient balance.
Technical or unexpected failure	canceled_failure	Non-rejection failure path.

A single POST /payouts may produce multiple webhooks (for example pending_created, then pending_promise or success, depending on the gateway response).

Payout Webhook Parameters

webhook_typestring

Always `"payout"` for payout webhooks.

idempotency_keyoptional, string

Idempotency key from the create request, if provided.

uuidstring

Public payout identifier (same as `payout_uuid` in create responses).

idnumber

Internal payout ID.

statusstring

Main status: `pending`, `success`, or `canceled` (first segment of `sub_status`).

sub_statusstring

Detailed payout status.

tenant_idnumber

Owning tenant ID.

gatewaystring

Payout gateway identifier.

recipient_idnumber

Internal ID of the linked payout recipient (not `recipient_uuid`).

amountnumber

Payout amount in cents.

currencystring

Three-letter ISO currency code.

narrationoptional, string

Transfer description from the create request.

gateway_payout_idoptional, string

Gateway reference for the transfer, when known.

gateway_auxiliary_idoptional, string

Secondary gateway reference, when provided by the gateway.

failure_reasonoptional, string

Human-readable rejection or failure message on canceled payouts.

RESPONSE

{
  "webhook_type": "payout",
  "idempotency_key": "settlement-seller-1042-week-15",
  "uuid": "4c56e5c2-7ef0-4db0-8d2e-5e980f3f3bc7",
  "id": 301,
  "status": "pending",
  "sub_status": "pending_promise",
  "tenant_id": 1,
  "gateway": "mygateway",
  "recipient_id": 88,
  "amount": 250000,
  "currency": "NGN",
  "narration": "Weekly seller settlement",
  "gateway_payout_id": "mock-transfer-301",
  "gateway_auxiliary_id": null,
  "failure_reason": null
}