Create a payout

POST https://api.orqex.com/v1/payouts

Request parameters

number

required

Amount in major units, the same scale as a payment: 50 means 50.00. Minimum 1.

string

required

ISO 4217 currency code, uppercase, 3 characters (e.g. EUR, USD).

string

required

Payout method code. Valid codes for your project are shown in your dashboard. The method must be compatible with the instrument type — see Instruments.

string

required

Human-readable description of the payout. Maximum 500 characters.

object

required

The typed destination. Must include a type field (phone, bank_account, or crypto_address) plus the required fields for that type. See Instruments for the full field list per type.

object

required

Identifies the recipient in Orchestrate. All sub-fields match the payment customer shape.

Field	Required	Constraints
`email`	Yes	Valid email, max 255 characters.
`first_name`	Yes	Max 100 characters.
`last_name`	Yes	Max 100 characters.
`address`	No	Max 200 characters.
`city`	No	Max 100 characters.
`state`	No	Max 100 characters.
`country`	No	ISO alpha-2 code; must exist.
`zip`	No	Postal code.

string

Your own identifier for this payout. Maximum 191 characters. Must be unique within the project — a duplicate returns 409 Conflict. Use it together with an idempotency key to make retries safe. See API conventions.

string

URL notified when this payout completes or fails, and when it is created. Maximum 2048 characters. Deliveries to it are not signed — see Webhooks.

object

Up to 10 key-value pairs. Returned as-is on all read operations and in webhook payloads.

object

Optional provider-specific parameters, keyed by gateway code. The keys your project can use are shown in your dashboard. Unknown gateway codes or non-object sections are rejected with 422. See API conventions for documented keys.

Example

This sends 50.00 EUR to a bank account.

curl -X POST https://api.orqex.com/v1/payouts \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: payout-inv-4821" \
  -d '{
    "amount": 50,
    "currency": "EUR",
    "method": "bank_transfer",
    "description": "Invoice payout #4821",
    "reference": "payout-inv-4821",
    "instrument": {
      "type": "bank_account",
      "account_name": "Ada Lovelace",
      "account_number": "DE89370400440532013000",
      "bank_code": "37040044",
      "country": "DE"
    },
    "customer": {
      "email": "[email protected]",
      "first_name": "Ada",
      "last_name": "Lovelace"
    }
  }'

use Orqex\Orchestrate\OrchestrateClient;

$orqex = new OrchestrateClient('sk_live_...');

$payout = $orqex->payouts()->create([
    'amount'      => 50,
    'currency'    => 'EUR',
    'method'      => 'bank_transfer',
    'description' => 'Invoice payout #4821',
    'reference'   => 'payout-inv-4821',
    'instrument'  => [
        'type'           => 'bank_account',
        'account_name'   => 'Ada Lovelace',
        'account_number' => 'DE89370400440532013000',
        'bank_code'      => '37040044',
        'country'        => 'DE',
    ],
    'customer'    => [
        'email'      => '[email protected]',
        'first_name' => 'Ada',
        'last_name'  => 'Lovelace',
    ],
]);

For phone and crypto_address instrument shapes, see Instruments.

Response

Returns 201 with envelope { "message": "...", "data": <Payout> }. The status is usually pending immediately after creation — the payout is not yet final. Monitor via webhook or sync.

string

Unique payout identifier.

object

Amount in display form: { "value": float, "formatted": string, "short": string, "currency": string }.

object

The resolved payout method: value, label, description, icon_url, category, requires_phone.

string

Current status: pending, processing, completed, or failed.

string

Your reference, if provided.

string

The description you submitted.

string

The notification URL you submitted, or null.

object

Resolved customer: id, first_name, last_name, email, avatar_url.

object

The resolved destination. Shape varies by type — see Instruments.

object

{ "transaction": { "id", "reference", "external_id" } }. Populated once the provider accepts the payout; fields may be null while status is pending.

integer

Provider fee for this payout, as a plain integer in minor units — unlike amount, this one is not an Amount object. null when the provider reports no fee.

object

{ "code": string, "message": string }. Populated when status is failed; null otherwise.

object

Your key-value pairs, as submitted.

string

ISO 8601 timestamp. Set when the payout is dispatched to the provider.

string

ISO 8601 timestamp. Set when status reaches completed.

string

ISO 8601 timestamp. Set when status reaches failed.

string

ISO 8601 timestamp of creation.

Get started

Payments

Payouts

Events

Utilities

MCP

Request parameters

Example

Response

​Request parameters

​Example

​Response

Request parameters

Example

Response