Payouts

Create a payout

Send PHP to e-wallets or bank accounts. Settlement is asynchronous — you will receive a payout.succeeded or payout.failed webhook once the transfer completes.

curl -X POST https://nexuspayph.com/v1/payouts \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500.00,
    "currency": "PHP",
    "method": "gcash",
    "destination": { "account_no": "09171234567" },
    "description": "Weekly settlement"
  }'

Supported payout methods

Request parameters

Bank transfer destination

For bank_transfer or bank_transfer_nrt, include the destination bank account, the bank code, and the recipient name. Bank codes are numeric-looking strings returned by GET /v1/payout-banks. NexusPay keeps a local 148-bank registry so this list is available even if the provider bank-dictionary API is unavailable.

curl https://nexuspayph.com/v1/payout-banks \
  -H "Authorization: Bearer sk_live_..."

{
  "object": "list",
  "data": [
    { "code": "31248", "name": "BDO Bank", "brstn": null, "status": 1 },
    { "code": "20008", "name": "Bank Of The Philippine Islands", "brstn": "010040018", "status": 1 }
  ],
  "has_more": false
}

{
  "amount": 1000.00,
  "currency": "PHP",
  "method": "bank_transfer",
  "destination": {
    "account_no": "1234567890",
    "bank_code": "31248",
    "first_name": "Juan",
    "last_name": "Dela Cruz"
  },
  "description": "Supplier payment"
}

Response

{
  "id": "po_abc123",
  "object": "payout",
  "amount": 500.00,
  "currency": "PHP",
  "method": "gcash",
  "status": "pending",
  "provider": "directpay",
  "provider_ref": null,
  "destination": { "account_no": "09171234567" },
  "description": "Weekly settlement",
  "failure": null,
  "created": 1776850000
}

The payout starts in pending status. Once DirectPay confirms the transfer, you will receive a webhook and the status updates to succeeded or failed.

Ledger effect

A successful payout writes a debit row to the ledger. If the provider dispatch fails, we write an offsetting credit with kind adjustment to reverse the hold.