Bank Payouts - PCX Developer Docs

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
For NGN payouts: optionally pre-validate the account — see 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)

curl -X POST https://prod-api.pcxpay.com/v1/payments-init/initiate \
  -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"
  }'

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.

Bank transfer payout (NGN)

curl -X POST https://prod-api.pcxpay.com/v1/payments-init/initiate \
  -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

GET /organizations/admin/exchange-rate
  ?orgId=org_xxxx
  &fromCurrency=NGN
  &toCurrency=KES

Response:

{
  "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

curl -X POST https://prod-api.pcxpay.com/v1/payments-init/initiate \
  -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

{
  "statusCode": 200,
  "response": {
    "success": true,
    "payment_id": "pay_xxxx",
    "transaction_id": "txn_xxxx",
    "status": "pending",
    "next_action": "wait"
  }
}

For payouts no customer action is needed — next_action is wait and PCX processes the payout in the background.

Track payout status

GET /payments/{payment_id}

Or look up by transaction:

GET /payments/transaction/{transaction_id}

Terminal statuses: completed, failed, canceled. Use webhooks to receive payment.settled and payment.failed events in real time instead of polling.

​Prerequisites

​Single-currency payout

​Mobile money payout (KES)

​Bank transfer payout (NGN)

​Cross-border payout (with FX)

​Step 1 — Fetch the exchange rate

​Step 2 — Initiate the cross-border payment

​Handling the response

​Track payout status

Prerequisites

Single-currency payout

Mobile money payout (KES)

Bank transfer payout (NGN)

Cross-border payout (with FX)

Step 1 — Fetch the exchange rate

Step 2 — Initiate the cross-border payment

Handling the response

Track payout status