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.

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.

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.

Set gst: true only for AU merchants transacting in AUD. For every other currency, set gst: false.

Payins: collecting money

1. Get payin methods

   Retrieve the list of supported methods for your account / region.

2. Get payin required fields

   For the chosen method, fetch its specific required input fields.

3. Create the payin

   POST /v2/payins with the method name plus the required fields from the previous step.

4. Simulate (sandbox only)

   Call Payin Request Simulation to drive the transaction to completion for testing.

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

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.

jp_bank_jpy

Returns bank_name, transfer_id, branch_code, branch_name, account_number, account_name, account_type, transfer_name, expired_timestamp.

ar_bank_ars

Returns bank_name, account_number, account_name, alias (the Argentine account alias), expired_timestamp.

kr_bank_va_kyc_krw

Returns virtual_bank_code, virtual_account_number, virtual_bank_name. Follow the VA Bank Transfer flow.

mobile_money

E.g. gh_mobile_money_ghs: follow the Mobile Money OTP-authorisation flow.

kh_pay_khr

Do not rely on callback_url / failure_callback_url parameters to set status; use webhooks exclusively for the final transaction status.

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.

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.

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

These fields are collected for recipient validation on the local rail and are separate from the contact KYC flow. 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.

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.

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.

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

1. Get payout methods

   Retrieve supported outbound methods.

2. Get payout required fields

   Fetch the required fields for the chosen method.

3. Create the payout

   POST /v2/payouts: initialise with the required fields.

Steps 1–2 are one-time per method.

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.

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.

Webhook hygiene

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.