Skip to main content

​
Statuses

StatusTypeMeaning
pendingTransitoryPayout created; not yet submitted to the gateway.
processingTransitorySubmitted to the gateway; awaiting verification.
completedFinalVerified successful by Orqex.
failedFinalVerified failed. Read the failure object.
Only pending and processing are non-terminal. Treat completed and failed as final and act on them.

​
How Orqex finalises a payout

Orqex never trusts the gateway’s inline response as the authoritative outcome. After submission, status is resolved through two mechanisms:
  1. Webhook / callback from the gateway — when the gateway posts an outcome event to Orqex, the payout is verified and transitioned immediately.
  2. Reconciliation poller — a background job periodically re-fetches the payout status from the gateway. This covers gateways that do not deliver callbacks reliably.
This “verify, don’t trust” approach means a payout may linger in processing for minutes to hours depending on the gateway and network. Design your integration around payout webhooks for the fastest notification.

​
Failure details

When a payout reaches failed, the failure object is populated: 
{
  "failure": {
    "code": {
      "value": "INSUFFICIENT_BALANCE",
      "category": "GATEWAY_ERROR",
      "message": "The gateway account has insufficient balance to process this payout."
    },
    "message": "The gateway account has insufficient balance to process this payout."
  }
}
​
failure.code
object|null
​
failure.message
string|null
Top-level human-readable message (mirrors failure.code.message).

​
Failure categories

CategoryMeaning
VALIDATION_ERRORRequest rejected before submission: invalid field or rule violation.
RECIPIENT_ERRORRecipient-fixable: invalid account, unregistered number.
INSUFFICIENT_FUNDSThe gateway or source account lacks sufficient funds.
GATEWAY_ERRORProvider-side error or rejection.
TELCO_ERRORMobile-network or telco-side failure.
MERCHANT_CONFIG_ERRORMisconfiguration: missing routing rule, invalid gateway credentials.
PLATFORM_ERRORPlatform fault. Contact support if persistent.

​
Crypto settlement note

For crypto payouts, Orqex performs a settlement conversion: the payout is denominated in your project’s currency, and the equivalent crypto amount is computed and transmitted at execution time. The exchange rate used is captured on the payout. No currency conversion occurs for non-crypto methods.
There is no automatic retry or failover for failed payouts. If a payout fails, create a new one explicitly after resolving the underlying issue.