Webhook Payloads

This document describes the payload structure for different types of 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"
}