Send a Single Payout

This guide walks you through sending a payout to an external bank account using NextAPI.

Prerequisites

• NextAPI credentials (Client ID and Client Secret)
• An account with sufficient available balance
• Recipient bank details (bank code and account number)

Step 1: Check Available Balance

Before sending a payout, verify the source account has sufficient funds:

curl -X GET "https://api.partners.nextpay.world/v2/accounts/YOUR_ACCOUNT_ID/balances" \
  -H "Content-Type: application/json" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"

Confirm that available is greater than the payout amount (in centavos).

Step 2: Get Receiving Institutions

Look up valid bank codes to ensure the recipient's bank is supported:

curl -X GET "https://api.partners.nextpay.world/v2/receiving-institutions" \
  -H "Content-Type: application/json" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"

Note the bank_code for the recipient's bank (e.g., BPI, BDO, UBPH).

Step 3: Create the Payout Request

curl -X POST "https://api.partners.nextpay.world/v2/payout-requests" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: payout-$(date +%s)" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d '{
    "account_id": "YOUR_ACCOUNT_ID",
    "amount": 50000,
    "description": "Vendor payment - Invoice #1234",
    "recipient": {
      "name": "Maria Santos",
      "bank_code": "BPI",
      "account_number": "9876543210"
    }
  }'

Important:

• amount is in centavos. 50000 = PHP 500.00
• Always include X-Idempotency-Key to prevent duplicate payouts
• The description appears on the recipient's bank statement

Step 4: Monitor the Payout

Poll the payout request status or set up webhooks for real-time updates:

curl -X GET "https://api.partners.nextpay.world/v2/payout-requests/YOUR_PAYOUT_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"

Routing

NextAPI automatically routes your payout through the optimal payment rail:

• Under PHP 50,000: Routed via InstaPay (real-time, typically 5-30 seconds)
• PHP 50,000 and above: Routed via PESONet (batch processing, 1-4 hours)

You don't need to specify the rail — NextAPI handles routing automatically.

Error Handling

If a payout fails, the response includes an error code and message. Common failures:

Error	Cause	Action
INSUFFICIENT_FUNDS	Account balance too low	Top up the account
INVALID_ACCOUNT	Recipient account doesn't exist	Verify account number
BANK_UNAVAILABLE	Receiving bank is down	Retry after some time

Failed payouts automatically return reserved funds to your available balance.

Related

• The Lifecycle of a Payout — understand all payout states
• Understanding Webhooks — get notified when payouts complete
• API Reference: Create Payout Request — full endpoint docs