Create a payout

A single POST /v1/payouts creates and submits a payout. Supply the X-Idempotency-Key header so that network retries do not create duplicate transfers.

Request

curl https://api.orqex.com/v1/payouts \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: PO-2026-0001" \
  -d '{
    "amount": 5000,
    "currency": "XOF",
    "method": "momo_mtn",
    "description": "Salary payout",
    "reference": "PO-2026-0001",
    "customer": {
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Doe"
    },
    "instrument": {
      "type": "phone",
      "phone_number": "+22990000000",
      "country": "BJ"
    },
    "metadata": { "department": "engineering" }
  }'

Request body

amount

integer

required

Amount to send, in major units (e.g. 50 for 50.00 of the currency). Minimum 1.

currency

string

required

Three-letter ISO 4217 currency code, uppercase (e.g. XOF).

method

string

required

Payout method code. See Methods & instruments.

description

string

required

Short description of the payout purpose (e.g. "Salary payout").

customer

object

required

The recipient’s identity. Orqex resolves this to a project customer; the customer’s name is used as the beneficiary name on the transfer.

Show customer

string

required

Recipient email address.

first_name

string

required

Recipient first name.

last_name

string

required

Recipient last name.

address

string

Street address (optional).

city

string

City (optional).

state

string

State or region (optional).

country

string

ISO 3166-1 alpha-2 country code (optional).

zip

string

Postal or ZIP code (optional).

instrument

object

required

Typed destination. The required sub-fields depend on instrument.type. See Instrument types below.

reference

string

Your own unique identifier for this payout, scoped to your project. Re-using an existing reference returns 409 Conflict.

metadata

object

Up to 10 arbitrary key/value pairs, stored on the payout and returned as-is.

Instrument types

phone
bank_account
crypto_address

Mobile-money or wallet transfer to a phone number.

{
  "type": "phone",
  "phone_number": "+22990000000",
  "country": "BJ"
}

Field	Required	Description
`phone_number`	Yes	E.164-formatted phone number.
`country`	Yes	ISO 3166-1 alpha-2 country code.

Bank transfer to a named account.

{
  "type": "bank_account",
  "account_name": "Awa Diallo",
  "account_number": "CI93CI0080111301134291200589",
  "bank_code": "CI008",
  "country": "CI",
  "swift_bic": "BICICIAB"
}

Field	Required	Description
`account_name`	Yes	Account holder name.
`account_number`	Yes	Account number or IBAN.
`bank_code`	Yes	Local bank code.
`country`	Yes	ISO 3166-1 alpha-2 country code.
`swift_bic`	No	BIC/SWIFT code.

Crypto transfer to a blockchain address.

{
  "type": "crypto_address",
  "address": "TQ5xxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "network": "TRON",
  "memo_tag": "12345"
}

Field	Required	Description
`address`	Yes	On-chain wallet address.
`network`	Yes	Blockchain network (e.g. `TRON`, `ETH`, `BTC`).
`memo_tag`	No	Memo or destination tag (required by some networks).

Response

{
  "id": "po_...",
  "amount": { "value": 5000, "formatted": "5,000 XOF", "short": "5K", "currency": "XOF" },
  "method": "momo_mtn",
  "status": "processing",
  "reference": "PO-2026-0001",
  "description": "Salary payout",
  "customer": {
    "id": "cus_...",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "avatar_url": null
  },
  "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 },
  "metadata": {},
  "initiated_at": "2026-06-14T10:00:00+00:00",
  "completed_at": null,
  "failed_at": null,
  "created_at": "2026-06-14T10:00:00+00:00"
}

string

Public payout id, prefixed po_.

amount

object

Show amount

value

number

Amount in major units (decimal).

formatted

string

Localised display string (e.g. 5,000 XOF).

short

string

Abbreviated display string (e.g. 5K).

currency

string

ISO 4217 currency code.

method

string

Payout method code used.

status

string

pending, processing, completed, or failed. See Lifecycle.

reference

string

Your reference, if provided.

description

string

Payout description.

customer

object

Resolved project customer (simplified: id, first_name, last_name, email, avatar_url).

instrument

object

Full instrument object returned as provided.

gateway

object

Show gateway

transaction

object

Show transaction

string

Internal gateway transaction id.

reference

string

Reference used with the gateway.

external_id

string|null

Gateway’s own transaction id, once available.

fee_amount

number

Payout fee in major units (decimal).

failure

object

Populated when status is failed. See Lifecycle.

metadata

object

Your metadata as supplied.

initiated_at

string|null

ISO 8601 timestamp when the payout was submitted to the gateway.

completed_at

string|null

ISO 8601 timestamp when the payout completed, or null.

failed_at

string|null

ISO 8601 timestamp when the payout failed, or null.

created_at

string

ISO 8601 timestamp of creation.

Do not treat the initial status in this response as final. Payout status is resolved asynchronously. Listen to webhook events or poll the retrieve endpoint for the authoritative outcome.

​Request

​Request body

​Instrument types

​Response

Request

Request body

Instrument types

Response