> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Payout FAQ

> Answers to the most common questions about Waffo payouts: creating and tracking a payout, notifications, per-country payee field requirements, idempotency, and error codes.

This page answers the questions merchants ask most often about Waffo payouts.
Field-level contracts live in the
[Payout API Specification](/docs/api-reference/introduction).

## 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?

| Status | Meaning |
| - | - |
| `IN_PROGRESS` | The payout is being processed. |
| `SUCCESS` | The payout succeeded. |
| `FAILURE` | The payout failed — check `failureCode` and `failureReason`. |

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](/docs/en/support/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](/docs/api-reference/introduction)
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](/docs/en/developer-docs/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).

| Code | Meaning | What to do |
| - | - | - |
| `A0007` | Payout currency is not supported | Use a currency covered by your contracted configuration. |
| `A0012` | Merchant account insufficient balance | Top up your account, then re-submit. |
| `A0008` | Payout limit exceeded | Keep the amount within the allowed range for your account. |
| `A0013` | Too many requests | Back off and retry later. |
| `A0011` | Idempotent param mismatch | Same `payoutRequestId` reused with a different amount, currency or payee account. |
| `E0001` | Unknown status | Retry inquiry until a final `SUCCESS` / `FAILURE`. |

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](/docs/en/support/payout-error-codes-and-retry-faq).

## 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`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.