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

# Bank Payouts

> Disburse funds to bank accounts and mobile money wallets across supported corridors

PCX supports single-currency and cross-border payouts to bank accounts and mobile money wallets. All flows require a registered beneficiary and follow the same initiation endpoint.

***

## Prerequisites

* A registered beneficiary (`beneficiary_id`) — see [Beneficiaries](/concepts/beneficiaries)
* For NGN payouts: optionally pre-validate the account — see [Beneficiary Validation](/guides/payouts/beneficiary-validation)

***

## Single-currency payout

Disburse in a single currency with no FX conversion. `currency` and `target_currency` must match; `amount` must equal `target_amount`.

### Mobile money payout (KES)

```bash theme={null}
curl -X POST https://prod-api.pcxpay.com/v1/payments-init/initiate/public-payin \
  -H "X-Api-Key: your_api_key" \
  -H "Authorization: NONE" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_xxxx",
    "amount": 5000.00,
    "target_amount": 5000.00,
    "currency": "KES",
    "target_currency": "KES",
    "country": "KE",
    "payment_method": "mobile_money",
    "direction": "payout",
    "org_id": "org_xxxx",
    "client_reference": "PAYOUT-00456",
    "payer_details": {
      "name": "Sender Name",
      "email": "sender@example.com"
    },
    "mobile_money_details": {
      "provider": "<network name from /externals/networks>",
      "phone_number": "+254712345678"
    },
    "beneficiary_id": "ben_xxxx"
  }'
```

<Note>
  The `provider` value in `mobile_money_details` must match the network `name` exactly as returned by `POST /externals/networks`. Also pass `networkId` — the `id` field from that same response — to ensure correct routing.
</Note>

### Bank transfer payout (NGN)

```bash theme={null}
curl -X POST https://prod-api.pcxpay.com/v1/payments-init/initiate/public-payin \
  -H "X-Api-Key: your_api_key" \
  -H "Authorization: NONE" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_xxxx",
    "amount": 50000.00,
    "target_amount": 50000.00,
    "currency": "NGN",
    "target_currency": "NGN",
    "country": "NG",
    "payment_method": "bank_transfer",
    "direction": "payout",
    "org_id": "org_xxxx",
    "client_reference": "PAYOUT-00789",
    "payer_details": {
      "name": "Sender Name",
      "email": "sender@example.com"
    },
    "bank_details": {
      "account_name": "Recipient Name",
      "account_number": "0123456789",
      "bank_name": "Access Bank",
      "country": "NG",
      "bank_code": "044"
    },
    "beneficiary_id": "ben_xxxx"
  }'
```

***

## Cross-border payout (with FX)

To disburse in a different currency from what you collected — for example, collect NGN and pay out KES — first lock in an exchange rate, then initiate the payment with `direction: "payin"`. PCX handles the FX conversion and outbound transfer automatically.

### Step 1 — Fetch the exchange rate

```bash theme={null}
GET /organizations/admin/exchange-rate
  ?orgId=org_xxxx
  &fromCurrency=NGN
  &toCurrency=KES
```

**Response:**

```json theme={null}
{
  "org_rate_id": "258b95aa-a76f-4144-ade1-23814a32900d",
  "from_currency": "NGN",
  "to_currency": "KES",
  "rate": 0.09127444176,
  "expires_at": "2026-06-04T12:00:00.000Z"
}
```

Store `org_rate_id`. Rates expire at `expires_at` — initiate the payment promptly.

### Step 2 — Initiate the cross-border payment

```bash theme={null}
curl -X POST https://prod-api.pcxpay.com/v1/payments-init/initiate/public-payin \
  -H "X-Api-Key: your_api_key" \
  -H "Authorization: NONE" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_xxxx",
    "amount": 100000.00,
    "target_amount": 9127.44,
    "currency": "NGN",
    "target_currency": "KES",
    "org_rate_id": "258b95aa-a76f-4144-ade1-23814a32900d",
    "country": "NG",
    "payment_method": "bank_transfer",
    "direction": "payin",
    "org_id": "org_xxxx",
    "client_reference": "REMIT-00123",
    "payer_details": {
      "name": "Sender Name",
      "email": "sender@example.com"
    },
    "beneficiary_id": "ben_xxxx"
  }'
```

`direction` is `payin` for cross-border flows — it describes the collection leg. PCX automatically initiates the outbound KES payout to the beneficiary once the NGN payin confirms.

***

## Handling the response

```json theme={null}
{
  "statusCode": 200,
  "response": {
    "payment_id": "pay_xxxx",
    "status": "process",
    "next_action": "wait"
  },
  "transaction_id": "txn_xxxx"
}
```

For mobile money payouts, `next_action` may be `instructions` — the recipient will receive a prompt on their phone.

***

## Track payout status

```bash theme={null}
GET /payments/{payment_id}
```

Or look up by transaction:

```bash theme={null}
GET /payments/transaction/{transaction_id}
```

Terminal statuses: `completed`, `failed`, `canceled`. Use [webhooks](/essentials/webhooks) to receive `payment.completed` and `payment.failed` events in real time instead of polling.