Skip to main content
This page answers the questions merchants ask most often about Waffo payouts. Field-level contracts live in the Payout API Specification.

​
How do I create a payout and track it to completion?

Three integration points, all required:
  1. Create — call /api/v1/payout/create with a unique payoutRequestId, the payout amount and currency, the receiving country, and the payee details. Some corridors additionally require a remittance purpose — payouts to mainland China must carry one from a fixed list. The response returns Waffo’s payoutOrderId and an initial status.
  2. Inquire — call /api/v1/payout/inquiry with either payoutRequestId or payoutOrderId to fetch the full payout object at any time.
  3. Listen — receive the payout notification webhook on the notifyUrl you supplied, pushed when the payout completes or fails.

​
What statuses can a payout have?

A subStatus field appears only when a reversal occurs after success (status stays SUCCESS): FULL_REVERSED means the whole amount was reversed; PARTIAL_REVERSED means only part of it was. Most orders never carry a subStatus.

​
How does idempotency work? What if I retry a create request?

payoutRequestId is your idempotency key. Retrying /api/v1/payout/create with the same payoutRequestId:
  • and the same amount, currency and payee account returns the ordinary success code carrying the original order’s data — including its current status, and its original failure code if it had already failed. No second payout is created. Detect this by comparing the returned payoutOrderId with the one you already hold; there is no distinct idempotency code.
  • but a different amount, currency or payee account returns A0011 (idempotent param mismatch) and the request is rejected. Note that the comparison covers only those three fields — see the Payout Request Field Guide for what that means if you edit a payee and resend.
If you receive an Exxxxx unknown error, the final outcome is not yet determined — keep retrying the inquiry until you receive a final SUCCESS or FAILURE status. Do not treat an unknown result as failed.

​
Which payee name fields are required?

payeeFirstName, payeeMiddleName, and payeeLastName are conditional: whether they are required varies by the receiving country and payout method. The same applies to payeeIDType: today CHN is the country with enforced requirements (an ID or passport must be supplied, and bank payouts carry additional local rules). Other countries are validated by the channel rather than by a country-specific rule, so follow the field requirements table for the corridor you use. For Indonesia (IDN), the name fields are not required for either IDN_BANK bank payouts or DANA eWallet payouts, but bank payouts require bankCode inside payoutMethodProperty. Check the Payout Creation Field Requirements table in the Payout API Specification for the country and method you use; the methods available to you depend on your contracted configuration.

​
How do payout notifications work?

When a payout completes or fails, Waffo sends an HTTPS POST to your notifyUrl with eventType set to PAYOUT_NOTIFICATION. The result object has the same structure as the /api/v1/payout/inquiry response. Respond with message set to success after processing. If Waffo receives failed or unknown, Waffo retries the notification on a fixed back-off schedule; see Webhook retry for the attempts and intervals. Verify the X-SIGNATURE header with Waffo’s public key before trusting the payload (signature algorithm: SHA256WithRSA).

​
What do the common error codes mean?

Error codes are grouped by prefix: A merchant-related, B user-related, C system-related, D risk rejection, E unknown (retry until final). The payout code set is not the same as the payment one — several codes carry a different meaning and payouts have no A0014. The complete table, with which four codes are safe to retry, is in Payout error codes & retries.

​
What amount is deducted from my balance?

The inquiry response separates the amounts: payoutAmount (what you asked to pay out), prefundAmount (what is deducted from your account, fee included), and payeeAmount (what the payee receives — for cross-currency payouts the exact received amount may not be known). If a payout fails, the remaining amount is returned to you; the handling fee may still be charged depending on the situation, as reflected by feeStatus (DEDUCTED, RETURNED, or NONE).