Guides

Pay out to a bank or PayPal

An off-ramp moves a wallet balance out to a bank account or PayPal. The wallet is debited when you create it, and credited back automatically if the payout bounces.

The flow

Register a payout account

POST /users/{user_id}/payout_accounts with type (bank or paypal), the rail from GET /routes, and the account owner's name, which is screened against sanctions lists. Details are validated per field, and account numbers come back masked.

Shell

curl -X POST "$NDEIPI/users/usr_01JA8Z3H6J7K8M9N0P1Q2R3S4T/payout_accounts" \
  -H "Api-Key: $NDEIPI_API_KEY" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "type": "paypal", "currency": "usd", "country": "ZW", "rail": "paypal",
        "account_owner_name": "Tendai Ncube",
        "paypal": { "email": "tendai.ncube@example.com" } }'

Create the off-ramp

A transfer from the user's wallet to the payout account. Only cashable points can be paid out: above that, the request returns 422 amount_exceeds_cashable.

Shell

curl -X POST "$NDEIPI/transfers" \
  -H "Api-Key: $NDEIPI_API_KEY" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "source": { "type": "wallet", "wallet_id": "wal_01JA8Z5B7C1DE2F3G4H5J6K7LM" },
        "destination": { "type": "payout_account", "payout_account_id": "pa_01JA8Z6N3P4Q5R6S7T8U9V0WXY" },
        "amount": "20.00" }'

Follow it to the bank
The transfer moves pending → payout_submitted → completed. The receipt shows the rate, fees, amount_paid_out and the rail's own reference, which the user can quote to their bank.

When a payout bounces

If the bank or PayPal rejects or returns the payout, the transfer passes through undeliverable or returned, the full amount is credited back to the wallet, and it ends refunded. You get payout.returned, with the reason in state_reason, so you can ask the user to check their details.

Removing a payout account

Deleting removes the account as a destination for new payouts. Payouts already submitted to it finish as normal. It's refused with 409 payout_account_in_use while a payout to it is still pending.