Skip to main content
Platform Payouts draws from the available balance in the payout currency. Funding has two steps: deposit USD, then request conversion into the currency you need. A credited USD deposit does not automatically become VND, THB, or PHP. Funding must be enabled for your account and environment. For sandbox tests, ask Zennopay to arrange test deposits and settlement; do not send real money to sandbox instructions.

​
Use the Console

  1. Open Balances in the Console and choose Add funds.
  2. Enter the USD amount. Use the returned beneficiary name, account details, and unique deposit reference when arranging the bank transfer.
  3. Wait for the deposit to be credited to your USD balance.
  4. Choose Convert & reserve, enter a USD amount, and select the payout currency. Submitting the request reserves USD immediately.
  5. Wait for Zennopay operations to confirm settlement of the quoted local amount. Check the available local balance before creating a payout.
Use the beneficiary name exactly as returned in the funding instructions. Each deposit has its own ZPF-... reference; include it with the transfer so Zennopay can match the receipt to your deposit.

​
Check balances with the API

All endpoints below use HMAC authentication and the base URL for your environment.
The response contains account and balances. account is null when an active funding account is unavailable. When present, it includes the bank name, account name, USD currency, routing number, masked account number, and status. Full transfer instructions are returned when you create a funding request. Each entry in balances contains: All amounts are base-10 int64 strings in minor units. USD uses cents, VND uses whole dong, and THB/PHP use hundredths. Read the entry for the payout currency; do not combine currencies or use the USD balance to authorize a local payout.

​
Declare a USD deposit

"10000" means USD 100.00. The amount must be a positive int64 string without decimals or leading zeroes. Idempotency-Key must contain 1–255 printable ASCII characters. A new request returns 201 Created with funding_request and funding_instructions. Save funding_request.id and use these instruction fields to arrange the transfer: Creating the request records an expected deposit; it does not initiate a bank transfer. Keep full account details in authorized treasury workflows. Track the deposit with GET /v1/funding_requests/{id}. The response wraps the record in funding_request. GET /v1/funding_requests?limit=50 returns a bounded { "data": [...] } list; limit accepts 1–100 and defaults to 50. Wait for credited and confirm the available USD balance before requesting conversion. Existing deposits from the earlier automatic conversion flow may have a VND destination; read the stored currency instead of assuming it.

​
Request conversion

The API accepts VND, THB, or PHP as a destination currency. A usable quote, settlement arrangement, and payout destination must also be enabled for your account. An accepted currency code does not establish live payout coverage. A new request returns 202 Accepted with conversion and replay: false. The conversion records the source and destination amounts, currencies, FX rate, ID, and status. Its initial status is reserved: USD is reserved, and the local amount is awaiting operations settlement. Use GET /v1/funding_conversions?limit=50 to track the record by its ID. The response is { "data": [...] }; limit accepts 1–100 and defaults to 50. There is currently no single-conversion GET endpoint. Wait for settled, then read GET /v1/funding_overview again to verify the available local balance. A pending request or quote is not spendable money. If settlement remains unresolved or reports amount_mismatch, contact support with the conversion ID and keep tracking the original request.

​
Retry and recover

For either create endpoint, identical input with the original idempotency key returns 200 OK and Idempotent-Replayed: true. Reusing a key with different input returns 409 idempotency_conflict. Generate a fresh HMAC timestamp, nonce, and signature for every retry while preserving the business key. Once local funds are available, continue with the Platform Payouts quickstart.