Payouts

Move funds from your NexusPay balance to an external destination. Payouts are processed via DirectPay and support multiple disbursement channels.

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

Method	Channel	Destination
`gcash`	GCash	11-digit mobile number
`paymaya`	Maya (PayMaya)	11-digit mobile number
`grabpay`	GrabPay	11-digit mobile number
`coins`	Coins.ph	11-digit mobile number
`bank_transfer`	Bank (InstaPay/PESONet)	Bank account number

Request parameters

Parameter	Type	Description
`amount`	number	Amount to send (minimum 1.00)
`currency`	string	`PHP`
`method`	string	One of: `gcash`, `paymaya`, `grabpay`, `coins`, `bank_transfer`
`destination`	object	`{"account_no": "..."}` — wallet/account number
`description`	string	Optional note for your records

Bank transfer destination

For bank_transfer method, include additional bank details:

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

Response

{
  "id": "po_abc123",
  "object": "payout",
  "amount": 500.00,
  "currency": "PHP",
  "method": "gcash",
  "status": "pending",
  "destination": { "account_no": "09171234567" },
  "description": "Weekly settlement",
  "created_at": "2026-04-24T10:30:00Z"
}

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

Balance check

The API blocks payouts that would drive your balance negative. Ensure you have sufficient funds before initiating a payout. Test-mode payouts succeed immediately via MockProvider.

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.

Webhook events

Event	Description
`payout.succeeded`	Funds successfully sent to recipient
`payout.failed`	Transfer failed (invalid account, insufficient float, etc.)