> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orqex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a payout

> POST /payouts — initiate an outbound transfer to a recipient.

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

## Request parameters

<ParamField body="amount" type="number" required>
  Amount in **major units**, the same scale as a payment: `50` means 50.00. Minimum 1.
</ParamField>

<ParamField body="currency" type="string" required>
  ISO 4217 currency code, uppercase, 3 characters (e.g. `EUR`, `USD`).
</ParamField>

<ParamField body="method" type="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](/payouts/instruments).
</ParamField>

<ParamField body="description" type="string" required>
  Human-readable description of the payout. Maximum 500 characters.
</ParamField>

<ParamField body="instrument" type="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](/payouts/instruments) for the full field list per type.
</ParamField>

<ParamField body="customer" 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.                     |
</ParamField>

<ParamField body="reference" type="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](/api-conventions).
</ParamField>

<ParamField body="webhook_url" type="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](/webhooks).
</ParamField>

<ParamField body="metadata" type="object">
  Up to 10 key-value pairs. Returned as-is on all read operations and in webhook payloads.
</ParamField>

<ParamField body="gateway_options" type="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](/api-conventions) for documented keys.
</ParamField>

## Example

This sends 50.00 EUR to a bank account.

<CodeGroup>
  ```bash cURL theme={null}
  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": "ada@example.com",
        "first_name": "Ada",
        "last_name": "Lovelace"
      }
    }'
  ```

  ```php PHP theme={null}
  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'      => 'ada@example.com',
          'first_name' => 'Ada',
          'last_name'  => 'Lovelace',
      ],
  ]);
  ```
</CodeGroup>

For `phone` and `crypto_address` instrument shapes, see [Instruments](/payouts/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](/webhooks) or [sync](/payouts/overview#verifying-a-payout).

<ResponseField name="id" type="string">
  Unique payout identifier.
</ResponseField>

<ResponseField name="amount" type="object">
  Amount in display form: `{ "value": float, "formatted": string, "short": string, "currency": string }`.
</ResponseField>

<ResponseField name="method" type="object">
  The resolved payout method: `value`, `label`, `description`, `icon_url`, `category`,
  `requires_phone`.
</ResponseField>

<ResponseField name="status" type="string">
  Current status: `pending`, `processing`, `completed`, or `failed`.
</ResponseField>

<ResponseField name="reference" type="string">
  Your reference, if provided.
</ResponseField>

<ResponseField name="description" type="string">
  The description you submitted.
</ResponseField>

<ResponseField name="webhook_url" type="string">
  The notification URL you submitted, or `null`.
</ResponseField>

<ResponseField name="customer" type="object">
  Resolved customer: `id`, `first_name`, `last_name`, `email`, `avatar_url`.
</ResponseField>

<ResponseField name="instrument" type="object">
  The resolved destination. Shape varies by type — see [Instruments](/payouts/instruments).
</ResponseField>

<ResponseField name="gateway" type="object">
  `{ "transaction": { "id", "reference", "external_id" } }`. Populated once the provider
  accepts the payout; fields may be `null` while status is `pending`.
</ResponseField>

<ResponseField name="fee_amount" type="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.
</ResponseField>

<ResponseField name="failure" type="object">
  `{ "code": string, "message": string }`. Populated when status is `failed`; `null`
  otherwise.
</ResponseField>

<ResponseField name="metadata" type="object">
  Your key-value pairs, as submitted.
</ResponseField>

<ResponseField name="initiated_at" type="string">
  ISO 8601 timestamp. Set when the payout is dispatched to the provider.
</ResponseField>

<ResponseField name="completed_at" type="string">
  ISO 8601 timestamp. Set when status reaches `completed`.
</ResponseField>

<ResponseField name="failed_at" type="string">
  ISO 8601 timestamp. Set when status reaches `failed`.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of creation.
</ResponseField>