Payouts

Send money from your Zeny balance to a bank account or e-wallet you have saved.

How a payout works

1. Save a beneficiary in the dashboard. A beneficiary is the bank account or e-wallet you pay. Beneficiaries are created in the dashboard, not through this API. Zeny checks that the account holder's name matches, and a payout to a beneficiary without a passing name check is refused (409 name_check_required or 409 name_check_failed). Copy the beneficiary's id (ben_…).
2. Request the payout with POST /api/merchant/v1/payouts and an Idempotency-Key.

   curl https://api.usezeny.com/api/merchant/v1/payouts \
     -H "Authorization: Bearer $ZENY_SECRET_KEY" \
     -H "Idempotency-Key: payout-2026-11-supplier-17" \
     -H "Content-Type: application/json" \
     -d '{
       "reference": "supplier-17",
       "beneficiary": "ben_…",
       "amount": { "value": "2500000.00", "currency": "IDR" },
       "description": "November invoice"
     }'

   The money is reserved from your available balance at once (debit) and the payout is pending_approval.
3. A second person approves it. Someone else on your team, not the person who requested it, must approve the payout in the dashboard. Zeny's risk review can also hold or refuse it.
4. Zeny sends it. The payout is processing, then paid when the provider reports the money sent. If it fails, the debit returns to your balance.

Learn the outcome from the payout.paid, payout.failed, payout.rejected and payout.canceled webhooks, or read the payout with GET /api/merchant/v1/payouts/{id}.

Reading the amounts

debit is what leaves your balance and net is what the beneficiary receives. They always add up: debit = net + the sum of fees. A fee you bear is added on top of the amount (net equals amount). A fee the beneficiary bears comes off what is sent (debit equals amount).

Cancel a payout

POST /api/merchant/v1/payouts/{id}/cancel withdraws a payout that is still pending_approval and returns its debit to your balance. Once a payout is approved it cannot be canceled (409 invalid_state_transition).

Errors you should expect

A payout that fails has a failure.code: declined means every provider refused it, so check the beneficiary's account; processing_error means it failed after a provider took it.