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 — these are BIC/SWIFT format codes (e.g., BOPIPHMMXXX for BPI, BNORPHMM for BDO).

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 '{
    "source_account_id": "YOUR_ACCOUNT_UUID",
    "external_id": "vendor-payment-INV-1234",
    "amount_cents": 50000,
    "currency": "PHP",
    "settlement_rail": "instapay",
    "status": "published",
    "settlement_account": {
      "bank_account_name": "Maria Santos",
      "bank_account_number": "9876543210",
      "bank_code": "BOPIPHMMXXX"
    },
    "description": "Vendor payment - Invoice #1234"
  }'

Important:

• amount_cents is in centavos: 50000 = PHP 500.00
• status: "published" submits immediately; use "draft" to save without submitting
• settlement_rail must be specified: "instapay" for real-time, "pesonet" for batch
• bank_code is BIC/SWIFT format — get valid codes from GET /v2/receiving_institutions
• Always include X-Idempotency-Key to prevent duplicate payouts

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"

Payout request statuses:

Status	Meaning
draft	Saved but not submitted
published	Submitted, awaiting processing
authorization_pending	Awaiting internal authorization
authorized	Authorized, queued for settlement
queued	Picked up by the settlement rail
processed	Bank confirmed receipt — terminal ✓
rejected	Rejected before processing — terminal ✗
canceled	Canceled — terminal ✗
queue_failed	Failed to queue for settlement — terminal ✗
processing_failed	Settlement attempted but failed — terminal ✗

For failed payouts, funds reserved against the payout are returned to your available balance.

Routing

Specify settlement_rail explicitly: use "instapay" for real-time transfers (typically seconds) or "pesonet" for batch processing (next cutoff, 10 AM or 3 PM Manila time).

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