Gig & Marketplace Payouts

"I have 15,000 riders. After every completed delivery, they want their earnings available. Some have BPI, some BDO, most only have GCash."

If you run a marketplace or gig economy platform, speed of payout is a competitive advantage — riders and sellers choose platforms that pay faster. NextAPI's InstaPay routing sends money to any Philippine bank or e-wallet in real time, with a webhook confirmation per payout.

The problem

Gig payouts have three hard constraints that manual bank transfers and basic payment gateways can't handle:

Volume — 15,000 riders × daily payouts = 15,000 individual bank transfers per day. No bank portal handles this manually.

Multi-bank reach — Your riders have accounts at 20+ different banks and both major e-wallets. A GCash-only payout solution loses the riders on BPI. A BPI-only solution loses the GCash riders.

Speed — Riders on competing platforms get paid daily or per-shift. If your platform pays weekly, you lose your best riders.

How NextAPI handles it

One API call per completed delivery triggers an instant payout to the rider's registered bank or e-wallet. NextAPI routes to InstaPay for real-time settlement (≤ PHP 50,000) and automatically falls back to PESONet for larger amounts.

Delivery marked complete in your platform
               ↓
POST /v2/payout-requests (rider's bank + earnings amount)
               ↓
NextAPI routes via InstaPay → rider's bank/GCash/Maya
               ↓
Webhook: payout_request.completed
               ↓
Your platform notifies rider: "Earnings available"

Integration pattern

Rider onboarding: When a rider registers, collect their bank/wallet details. Store them in your platform — you'll pass them to NextAPI at payout time. No pre-enrollment at the bank required.

Event-triggered payouts: When your platform marks a delivery as completed, trigger a POST /v2/payout-requests. You don't need to batch — each delivery can trigger its own payout.

Confirmation: The payout_request.completed webhook fires when the bank confirms receipt. Your platform can then show the rider "₱250 transferred to BPI ****1234" in their earnings history.

Proof of transfer: Each completed payout has a receipt at GET /v2/payouts/{id}/receipt with the bank's own transaction reference. This answers the support ticket: "I didn't receive my payout."

Key API endpoints

Action	Endpoint
Send a single rider payout	POST /v2/payout-requests
Check payout status	GET /v2/payout-requests/{id}
Get all payouts in a request	GET /v2/payout-requests/{id}/payouts
Get payout receipt	GET /v2/payouts/{id}/receipt
List available banks/wallets	GET /v2/receiving-institutions
Check InstaPay/PESONet health	GET /v2/payout-requests/service-health

Idempotency for high-volume payouts

When you're sending thousands of payouts per day, transient errors are inevitable. Always pass a unique X-Idempotency-Key per payout request — if your network request fails and you retry, NextAPI returns the original response instead of creating a duplicate payout.

curl -u "$CLIENT_ID:$CLIENT_SECRET" \
  -X POST "https://api.partners.nextpay.world/v2/payout-requests" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: delivery-12345-payout-v1" \
  -d '{
    "account_id": "acct_platform_main",
    "amount": 25000,
    "recipient": {
      "type": "bank_account",
      "bank_code": "GCSH",
      "account_number": "09171234567",
      "account_name": "Maria Santos"
    },
    "description": "Delivery earnings - Dec 15 2025",
    "reference": "delivery-12345"
  }'

→ See IDs and Idempotency for key generation strategies.

Handling payout failures

At high volume, some payouts will fail — wrong account number, bank temporarily unavailable, recipient account closed. The payout_request.failed webhook fires for each failure with an error code indicating whether the failure is retryable.

Build a retry queue for transient failures (bank temporarily unavailable) and a manual review queue for permanent failures (invalid account number). Never auto-retry permanent failures with the same recipient details.

→ See Handle Payout Failures for the full failure-handling pattern.

Overnight vs real-time payouts

Not all gig platforms pay per-delivery. Some batch daily:

• Per-delivery (real-time): Call POST /v2/payout-requests for each completed delivery. InstaPay delivers within 30 seconds.
• Daily batch: Accumulate earnings in the rider's NextAPI account throughout the day, then call POST /v2/payout-requests/batch once per day to sweep all balances out.

The batch approach reduces API call volume and is simpler to reconcile, but the per-delivery approach wins on rider satisfaction.

Getting started

1. Get sandbox credentials
2. Follow Your First Payout to make your first payout end-to-end
3. Follow Send a Single Payout to understand the single-payout flow
4. Read Payout Lifecycle to understand all payout states
5. Follow Handle Payout Failures for resilient payout handling
6. Set up Webhooks for real-time payout confirmation