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", "account_name": "Juan Dela Cruz" },
    "description": "Weekly settlement"
  }'

Supported payout methods

Request parameters

Payee name (required)

Every payout must carry the recipient's real name: destination.account_name for wallet rails, or first_name and last_name (optionally middle_name) on any rail. Requests without a name, or with a placeholder such as N/A, none oranonymous, are rejected with a validation error. Blank or placeholder names cause the receiving bank or wallet to block or hold the transfer, so send the name exactly as registered on the account.

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", "account_name": "Juan Dela Cruz" },
  "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.