Skip to main content
Payout events are delivered through the same Pulse (webhook) mechanism as payments. Register a project webhook endpoint in the dashboard and subscribe it to the payout triggers. Unlike payment intents, payouts have no per-payout webhook_url field; delivery is configured at the project level. For the full delivery mechanics — retries, at-least-once semantics, signed vs. unsigned delivery, and how to verify authenticity — see Payment webhooks. Everything described there applies equally to payout events.

​
Events

EventDescription
payout.completedThe payout was successfully settled to the recipient.
payout.failedThe payout failed and the amount was not delivered.

​
Payload

{
  "event": "payout.completed",
  "payout": {
    "id": "po_...",
    "amount": { "value": 5000, "formatted": "5,000 XOF", "short": "5K", "currency": "XOF" },
    "method": "momo_mtn",
    "status": "completed",
    "reference": "PO-2026-0001",
    "description": "Salary payout",
    "customer": { "id": "cus_...", "first_name": "Jane", "last_name": "Doe", "email": "[email protected]" },
    "instrument": { "id": "poi_...", "type": "phone", "phone_number": "+22990000000", "country": "BJ" },
    "gateway": { "transaction": { "id": "gw_tx_123", "reference": "po_ref_generated", "external_id": null } },
    "fee_amount": 0,
    "failure": { "code": null, "message": null },
    "initiated_at": "2026-06-14T10:00:00+00:00",
    "completed_at": "2026-06-14T12:00:00+00:00",
    "failed_at": null,
    "created_at": "2026-06-14T10:00:00+00:00"
  }
}

​
Handler pattern

PHP handler
$event = json_decode(file_get_contents('php://input'), true);

// Re-fetch to get the authoritative status — do not trust the payload alone.
$payout = $orqex->payouts()->retrieve($event['payout']['id']);

if ($payout->status === 'completed') {
    // process the successful payout (idempotently)
}

if ($payout->status === 'failed') {
    // handle failure: inspect $payout->failure
}

http_response_code(200);

​
Handling rules

  • Respond with 2xx quickly; do slow work asynchronously.
  • Events are at-least-once — key your processing on payout.id + event.
  • Always re-fetch the payout from the API and act on that authoritative status.
The payout.completed event signals that Orqex has verified the outcome — not merely that the gateway acknowledged the request. You can act on it confidently after re-fetching.