構築するもの
Multi-Currency Payment API (v2) では、多数の通貨と現地の決済ネットワークで資金を回収 (Payin) し、支払 (Payout) できます。対応するのは、APAC、アフリカ、ラテンアメリカにおける銀行振込、バーチャル口座、モバイルマネー、電子ウォレット、QR の各方式です。資金は通貨ごとの Treasury Account へ精算され、自動的に消込されます。中核となる設計上の原則は、決済手段とその必須項目が動的であることです。対応範囲と要件は国と通貨によって異なるため、ハードコードするのではなく、利用できる手段とその入力スキーマを常に実行時に取得してください。
事前準備
- 加盟店アカウントと
app-id/secret-key。 - サンドボックス
https://api.cleverhub.co、本番環境https://api-merchant.helloclever.co。 - Webhook のエンドポイント（TLS 1.2、公開、商用証明書）。
- ベースパス：Payin は
POST /v2/payins、Payout はPOST /v2/payouts。
Payin：資金の回収
1
Payin の手段を取得する
アカウントや地域で対応している手段の一覧を取得します。
2
Payin の必須項目を取得する
選択した手段について、その固有の必須入力項目を取得します。
3
Payin を作成する
手段の名称と、前の手順で取得した必須項目を指定して
POST /v2/payins を実行します。4
シミュレーションする（サンドボックスのみ）
テストのために Payin Request Simulation を呼び出し、取引を完了状態へ進めます。
手段ごとの挙動
一部の手段は、短い遅延の後にpay_code を Webhook へ返します。これには、顧客が支払いを完了するために使う情報が含まれます。
- jp_bank_jpy
- ar_bank_ars
- kr_bank_va_kyc_krw
- mobile_money
- kh_pay_khr
- in_upi_inr
- mw_bank_mwk / tz_bank_tzs
bank_name、transfer_id、branch_code、branch_name、account_number、account_name、account_type、transfer_name、expired_timestamp を返します。MWK と TZS の銀行振込における受取人の検証
mw_bank_mwk と tz_bank_tzs は処理の前に受取人を検証し、指定が必要な項目は user_type によって変わります。
これらの項目は現地ネットワークにおける受取人の検証のために収集されるもので、コンタクトの KYC のフローとは別のものです。どちらの手段も
require_kyc: false と require_contact: false を返します。パラメーターは手段ごとに変わり得るため、フォームを構築する前に必ず Get payin required fields で現在の要件を確認してください。一部の手段では、送信の前に対応事業者の一覧（銀行コード、電子ウォレットなど）から選択する必要があります。たとえば
sa_eft_zar、my_bank_fpx_myr、th_qrpay_thb、bw_bank_bwp、そして暗号資産での精算に crypto_ticker と crypto_wallet_address を使う br_pix_brl が該当します。Payin を作成する前に、その手段の現在の事業者一覧を取得してください。作成した後
- 消込には Get payin requests in a period と Get payin details を使います。
- 決済後の操作には Refund payin と Cancel payin を使います。
- ステータスが
receivedまたはreturn_receivedに変わると Webhook が発火します。
Payout：資金の送金
1
Payout の手段を取得する
対応している送金の手段を取得します。
2
Payout の必須項目を取得する
選択した手段の必須項目を取得します。
3
Payout を作成する
POST /v2/payouts：必須項目を指定して開始します。Payout のステータス
事業者の一覧と補助エンドポイント
多くの Payout の手段では、送信の前に対応一覧から銀行や電子ウォレットを選択する必要があります。対象は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、my_ewallet_*_myr の一群（touchngo、finexus、boost、bigpay、shopeepay、gxbank、merchantrade）、br_bank_brl、th_bank_thb、bw_bank_bwp、ph_qrph_php です。
補助エンドポイント：
vn_bank_vnd：支店コードが必要な場合は Get Branch Codes を使ってください。kr_bank_krw：対応銀行の最新の一覧を取得するには Required Field API を使ってください。- VND Bank Lookup：ベトナムの口座向けに、専用の照会（QR の内容を使う方法など）が利用できます。
作成した後
- 消込には Get payout requests in a period と Get payout details を使います。
- フローのテストには Payout Simulation（サンドボックス）を使います。
- 将来の実行が設定された Payout には Cancel a Scheduled Payout を使います。
関連リソース
- Balance（
Get balance detailと履歴）：支払の前に通貨ごとの残高を確認します。 - Customer と Contact のエンドポイント：支払人と受取人の情報を保存し、取引をまたいで再利用します。
Payout の資金は、蓄積された Payin とトップアップからなる通貨ごとの残高から充当されます。Payout を開始する前に、該当する通貨の残高が満たされていることを確認してください。