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

# Handle Multi-Currency Payins and Payouts

> Collect and disburse funds across many currencies and local rails (bank transfers, mobile money, e-wallets, and QR) with per-currency Treasury Accounts.

## What you’ll build

The **Multi-Currency Payment APIs (v2)** let you collect (payin) and disburse (payout) funds across many currencies and local payment rails: bank transfers, virtual accounts, mobile money, e-wallets, and QR schemes across APAC, Africa, and Latin America. Funds settle into per-currency Treasury Accounts with automatic reconciliation.

<Info>
  The core design principle: **methods and their required fields are dynamic**. Always discover the available methods and their input schema at runtime rather than hard-coding them, because coverage and requirements vary by country and currency.
</Info>

## Prerequisites

* Merchant account and `app-id` / `secret-key`.
* Sandbox `https://api.cleverhub.co`; production `https://api-merchant.helloclever.co`.
* A webhook endpoint (TLS 1.2, public, commercial cert).
* Base paths: payins `POST /v2/payins`, payouts `POST /v2/payouts`.

<Warning>
  Set `gst: true` **only** for AU merchants transacting in **AUD**. For every other currency, set `gst: false`.
</Warning>

## Payins: collecting money

<Steps>
  <Step title="Get payin methods">
    Retrieve the list of supported methods for your account / region.
  </Step>

  <Step title="Get payin required fields">
    For the chosen method, fetch its specific required input fields.
  </Step>

  <Step title="Create the payin">
    `POST /v2/payins` with the method name plus the required fields from the previous step.
  </Step>

  <Step title="Simulate (sandbox only)">
    Call **Payin Request Simulation** to drive the transaction to completion for testing.
  </Step>
</Steps>

<Tip>
  You only need steps 1–2 once per method; reuse the method and field shape afterward.
</Tip>

### Method-specific behaviour

Some methods return a **`pay_code`** to your webhook after a short delay, containing the details your customer uses to complete payment.

<Tabs>
  <Tab title="jp_bank_jpy">
    Returns `bank_name`, `transfer_id`, `branch_code`, `branch_name`, `account_number`, `account_name`, `account_type`, `transfer_name`, `expired_timestamp`.
  </Tab>

  <Tab title="ar_bank_ars">
    Returns `bank_name`, `account_number`, `account_name`, `alias` (the Argentine account alias), `expired_timestamp`.
  </Tab>

  <Tab title="kr_bank_va_kyc_krw">
    Returns `virtual_bank_code`, `virtual_account_number`, `virtual_bank_name`. Follow the **VA Bank Transfer** flow.
  </Tab>

  <Tab title="mobile_money">
    E.g. `gh_mobile_money_ghs`: follow the **Mobile Money** OTP-authorisation flow.
  </Tab>

  <Tab title="kh_pay_khr">
    Do **not** rely on `callback_url` / `failure_callback_url` parameters to set status; use webhooks exclusively for the final transaction status.
  </Tab>

  <Tab title="in_upi_inr">
    Unified Payments Interface. Requires the customer's `upi_id` plus a full set of identity and address fields in `payin_method_params`: `first_name`, `last_name`, `phone`, `email`, `address`, `city`, `state`, `postal_code`, `country` (ISO 3166-1 alpha-2), and `callback_url`. Not refundable.
  </Tab>

  <Tab title="mw_bank_mwk / tz_bank_tzs">
    Bank transfer for Malawi (MWK) and Tanzania (TZS). Returns `account_name`, `account_number`, and `bank_name` for the customer to transfer to. Both require a `user_type` of `individual` or `organization` in `payin_method_params`, which determines the other required fields. See below. `user_id` is always mandatory. Neither method is refundable or cancellable.
  </Tab>
</Tabs>

#### Recipient validation for MWK and TZS bank transfers

`mw_bank_mwk` and `tz_bank_tzs` validate the recipient before processing, and the fields you must supply depend on `user_type`:

| `user_type`    | Required `payin_method_params`                                                                                                            |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `individual`   | `first_name`, `last_name`, `address`, `dob` (format `MM/DD/YYYY`), `document_number`, `document_type`, `phone`, `country`, plus `user_id` |
| `organization` | `business_name`, `business_reg_no`, plus `user_id`                                                                                        |

<Note>
  These fields are collected for recipient validation on the local rail and are separate from the [contact KYC flow](/api/contact/submit-kyc). Both methods report `require_kyc: false` and `require_contact: false`. Always confirm the current requirements with **Get payin required fields** before building your form, since parameters can change per method.
</Note>

<Note>
  Several methods require you to pick from a supported-provider list (bank codes, e-wallets, etc.) before submitting, e.g. `sa_eft_zar`, `my_bank_fpx_myr`, `th_qrpay_thb`, `bw_bank_bwp`, and `br_pix_brl` (which uses `crypto_ticker` + `crypto_wallet_address` for crypto settlement). Fetch the current provider list for the method before creating the payin.
</Note>

<Warning>
  **Amount rounding**: for **VND**, **JPY**, **XAF**, **KRW**, and **XOF**, amounts are rounded to the precision the currency supports during processing, so the amount recorded against a transaction may differ slightly from the value you submitted. Always reconcile against the amount in the API response and webhook payload rather than the value you sent. See [amount rounding](/api/v2/introduction#amount-rounding).
</Warning>

### After creation

* **Get payin requests in a period** and **Get payin details** for reconciliation.
* **Refund payin** and **Cancel payin** for post-payment actions.
* Your webhook fires when status changes to `received` or `return_received`.

## Payouts: sending money

<Steps>
  <Step title="Get payout methods">
    Retrieve supported outbound methods.
  </Step>

  <Step title="Get payout required fields">
    Fetch the required fields for the chosen method.
  </Step>

  <Step title="Create the payout">
    `POST /v2/payouts`: initialise with the required fields.
  </Step>
</Steps>

<Tip>
  Steps 1–2 are one-time per method.
</Tip>

### Payout statuses

| Status       | Meaning                                                                                  |
| ------------ | ---------------------------------------------------------------------------------------- |
| `created`    | Payout created                                                                           |
| `processing` | Being processed                                                                          |
| `scheduled`  | Waiting for funds to be transferred to the payee                                         |
| `completed`  | The whole batch is done; a single failed transaction does **not** block batch completion |

### Provider lists and helpers

Many payout methods require selecting a bank/e-wallet from a supported list before submitting, including `vn_bank_vnd`, `ph_bank_php`, `ng_bank_ngn`, `sa_bank_zar`, `ke_bank_kes`, `ke_mobile_money_kes`, `gh_mobile_money_ghs`, `cm_mobile_money_xaf`, `ci_mobile_money_xof`, `my_bank_myr`, the `my_ewallet_*_myr` family (touchngo, finexus, boost, bigpay, shopeepay, gxbank, merchantrade), `br_bank_brl`, `th_bank_thb`, `bw_bank_bwp`, and `ph_qrph_php`.

Helpers:

* **`vn_bank_vnd`**: use **Get Branch Codes** when a branch code is required.
* **`kr_bank_krw`**: use the **Required Field API** to get the current list of supported banks.
* **VND Bank Lookup**: a dedicated lookup (e.g. via QR content) is available for Vietnamese accounts.

### After creation

* **Get payout requests in a period** and **Get payout details** for reconciliation.
* **Payout Simulation** (sandbox) to test the flow.
* **Cancel a Scheduled Payout** for payouts set to run in the future.

## Supporting resources

* **Balance** (`Get balance detail` / history): check per-currency balances before disbursing.
* **Customer** and **Contact** endpoints: store payer/payee identities and reuse them across transactions.

<Info>
  Payout funds are sourced from your per-currency balance, made up of accumulated payins and top-ups. Ensure the relevant currency balance is funded before initiating a payout.
</Info>

## Webhook hygiene

<Warning>
  Provide `webhook_notification.endpoint_url` and `authorization_header` on create calls. Return `200 OK` to every delivery and handle duplicates idempotently; non-200 responses are retried 3× at 15-minute intervals. Use a distinct `authorization_header` per request.
</Warning>


## Related topics

- [Get Started with Hello Clever](/getting-started/overview.md)
- [Hello Clever Developer Documentation](/index.md)
- [Multi-Currency Payout API Reference (v2)](/api/v2/payout.md)