> ## 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.

# Payout instruments

> The three destination types: phone, bank account, and crypto address.

The `instrument` object on a payout describes the typed destination. Three types are
supported. The type must match the payout method — the API validates this at creation time
and returns `422` if there is a mismatch.

On the way **in**, you send a plain ISO alpha-2 country code. On the way **out**, `country`
is returned as an object: `{ "code": string, "name": string, "flag": string }`.

***

## phone

Pay to a phone number registered with a mobile money or wallet provider.

### Request fields

<ParamField body="instrument.type" type="string" required>
  Must be `"phone"`.
</ParamField>

<ParamField body="instrument.phone_number" type="string" required>
  The recipient's phone number. Must be a valid, dialable number.
</ParamField>

<ParamField body="instrument.country" type="string" required>
  ISO alpha-2 country code for the phone number.
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.orqex.com/v1/payouts \
    -H "Authorization: Bearer sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 2000,
      "currency": "USD",
      "method": "mobile_money",
      "description": "Contractor payment",
      "instrument": {
        "type": "phone",
        "phone_number": "+12025550156",
        "country": "US"
      },
      "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'      => 2000,
      'currency'    => 'USD',
      'method'      => 'mobile_money',
      'description' => 'Contractor payment',
      'instrument'  => [
          'type'         => 'phone',
          'phone_number' => '+12025550156',
          'country'      => 'US',
      ],
      'customer'    => [
          'email'      => 'ada@example.com',
          'first_name' => 'Ada',
          'last_name'  => 'Lovelace',
      ],
  ]);
  ```
</CodeGroup>

### Response shape

```json theme={null}
{
  "id": "pi_...",
  "type": "phone",
  "phone_number": "+12025550156",
  "country": {
    "code": "US",
    "name": "United States",
    "flag": "🇺🇸"
  }
}
```

***

## bank\_account

Pay to a bank account by account number or IBAN.

### Request fields

<ParamField body="instrument.type" type="string" required>
  Must be `"bank_account"`.
</ParamField>

<ParamField body="instrument.account_name" type="string" required>
  Name of the account holder.
</ParamField>

<ParamField body="instrument.account_number" type="string" required>
  Account number or IBAN.
</ParamField>

<ParamField body="instrument.bank_code" type="string" required>
  Routing or sort code for the bank. Maximum 32 characters.
</ParamField>

<ParamField body="instrument.swift_bic" type="string">
  SWIFT/BIC code. Optional; include when required by the provider.
</ParamField>

<ParamField body="instrument.country" type="string" required>
  ISO alpha-2 country code for the bank account.
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.orqex.com/v1/payouts \
    -H "Authorization: Bearer sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 5000,
      "currency": "EUR",
      "method": "bank_transfer",
      "description": "Invoice payout #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'      => 5000,
      'currency'    => 'EUR',
      'method'      => 'bank_transfer',
      'description' => 'Invoice payout #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>

### Response shape

```json theme={null}
{
  "id": "pi_...",
  "type": "bank_account",
  "account_name": "Ada Lovelace",
  "account_number": "DE89370400440532013000",
  "bank_code": "37040044",
  "swift_bic": null,
  "country": {
    "code": "DE",
    "name": "Germany",
    "flag": "🇩🇪"
  }
}
```

***

## crypto\_address

Pay to a blockchain address.

### Request fields

<ParamField body="instrument.type" type="string" required>
  Must be `"crypto_address"`.
</ParamField>

<ParamField body="instrument.address" type="string" required>
  The on-chain destination address.
</ParamField>

<ParamField body="instrument.network" type="string" required>
  The blockchain network identifier. Maximum 32 characters.
</ParamField>

<ParamField body="instrument.memo_tag" type="string">
  Destination tag or memo, required by some networks (e.g. XRP, Stellar). Maximum 64
  characters.
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.orqex.com/v1/payouts \
    -H "Authorization: Bearer sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 10000,
      "currency": "USD",
      "method": "crypto",
      "description": "Freelancer settlement",
      "instrument": {
        "type": "crypto_address",
        "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
        "network": "ethereum"
      },
      "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'      => 10000,
      'currency'    => 'USD',
      'method'      => 'crypto',
      'description' => 'Freelancer settlement',
      'instrument'  => [
          'type'    => 'crypto_address',
          'address' => '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
          'network' => 'ethereum',
      ],
      'customer'    => [
          'email'      => 'ada@example.com',
          'first_name' => 'Ada',
          'last_name'  => 'Lovelace',
      ],
  ]);
  ```
</CodeGroup>

### Response shape

```json theme={null}
{
  "id": "pi_...",
  "type": "crypto_address",
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "network": "ethereum",
  "memo_tag": null
}
```

<Note>
  The `crypto_address` instrument has no `country` field — blockchain addresses are
  network-scoped, not country-scoped.
</Note>