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

# 多通貨の Payin と Payout を扱う

> 通貨ごとの Treasury Account を使い、多数の通貨と現地のネットワーク（銀行振込、モバイルマネー、電子ウォレット、QR）で資金を回収・支払します。

## 構築するもの

**Multi-Currency Payment API (v2)** では、多数の通貨と現地の決済ネットワークで資金を回収 (Payin) し、支払 (Payout) できます。対応するのは、APAC、アフリカ、ラテンアメリカにおける銀行振込、バーチャル口座、モバイルマネー、電子ウォレット、QR の各方式です。資金は通貨ごとの Treasury Account へ精算され、自動的に消込されます。

<Info>
  中核となる設計上の原則は、**決済手段とその必須項目が動的である**ことです。対応範囲と要件は国と通貨によって異なるため、ハードコードするのではなく、利用できる手段とその入力スキーマを常に実行時に取得してください。
</Info>

## 事前準備

* 加盟店アカウントと `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`。

<Warning>
  `gst: true` は、**AUD** で取引するオーストラリアの加盟店に**限り**設定してください。それ以外の通貨では `gst: false` に設定します。
</Warning>

## Payin：資金の回収

<Steps>
  <Step title="Payin の手段を取得する">
    アカウントや地域で対応している手段の一覧を取得します。
  </Step>

  <Step title="Payin の必須項目を取得する">
    選択した手段について、その固有の必須入力項目を取得します。
  </Step>

  <Step title="Payin を作成する">
    手段の名称と、前の手順で取得した必須項目を指定して `POST /v2/payins` を実行します。
  </Step>

  <Step title="シミュレーションする（サンドボックスのみ）">
    テストのために **Payin Request Simulation** を呼び出し、取引を完了状態へ進めます。
  </Step>
</Steps>

<Tip>
  手順 1〜2 は手段ごとに一度だけ必要です。その後は同じ手段と項目の構成を再利用できます。
</Tip>

### 手段ごとの挙動

一部の手段は、短い遅延の後に **`pay_code`** を Webhook へ返します。これには、顧客が支払いを完了するために使う情報が含まれます。

<Tabs>
  <Tab title="jp_bank_jpy">
    `bank_name`、`transfer_id`、`branch_code`、`branch_name`、`account_number`、`account_name`、`account_type`、`transfer_name`、`expired_timestamp` を返します。
  </Tab>

  <Tab title="ar_bank_ars">
    `bank_name`、`account_number`、`account_name`、`alias`（アルゼンチンの口座エイリアス）、`expired_timestamp` を返します。
  </Tab>

  <Tab title="kr_bank_va_kyc_krw">
    `virtual_bank_code`、`virtual_account_number`、`virtual_bank_name` を返します。**VA Bank Transfer** のフローに従ってください。
  </Tab>

  <Tab title="mobile_money">
    例として `gh_mobile_money_ghs` があります。**Mobile Money** の OTP 承認のフローに従ってください。
  </Tab>

  <Tab title="kh_pay_khr">
    ステータスの判定に `callback_url` / `failure_callback_url` のパラメーターを**使わない**でください。最終的な取引ステータスは Webhook のみで判断してください。
  </Tab>

  <Tab title="in_upi_inr">
    Unified Payments Interface です。顧客の `upi_id` に加えて、`payin_method_params` に本人と住所の項目一式が必要です。`first_name`、`last_name`、`phone`、`email`、`address`、`city`、`state`、`postal_code`、`country`（ISO 3166-1 alpha-2）、`callback_url` です。返金はできません。
  </Tab>

  <Tab title="mw_bank_mwk / tz_bank_tzs">
    マラウイ (MWK) とタンザニア (TZS) の銀行振込です。顧客が送金するための `account_name`、`account_number`、`bank_name` を返します。どちらも `payin_method_params` に `individual` または `organization` の `user_type` が必要で、これによって他の必須項目が決まります。詳細は下記を参照してください。`user_id` は常に必須です。いずれの手段も返金と取消はできません。
  </Tab>
</Tabs>

#### MWK と TZS の銀行振込における受取人の検証

`mw_bank_mwk` と `tz_bank_tzs` は処理の前に受取人を検証し、指定が必要な項目は `user_type` によって変わります。

| `user_type`    | 必須の `payin_method_params`                                                                                                    |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `individual`   | `first_name`、`last_name`、`address`、`dob`（形式は `MM/DD/YYYY`）、`document_number`、`document_type`、`phone`、`country`、および `user_id` |
| `organization` | `business_name`、`business_reg_no`、および `user_id`                                                                              |

<Note>
  これらの項目は現地ネットワークにおける受取人の検証のために収集されるもので、[コンタクトの KYC のフロー](/api/contact/submit-kyc)とは別のものです。どちらの手段も `require_kyc: false` と `require_contact: false` を返します。パラメーターは手段ごとに変わり得るため、フォームを構築する前に必ず **Get payin required fields** で現在の要件を確認してください。
</Note>

<Note>
  一部の手段では、送信の前に対応事業者の一覧（銀行コード、電子ウォレットなど）から選択する必要があります。たとえば `sa_eft_zar`、`my_bank_fpx_myr`、`th_qrpay_thb`、`bw_bank_bwp`、そして暗号資産での精算に `crypto_ticker` と `crypto_wallet_address` を使う `br_pix_brl` が該当します。Payin を作成する前に、その手段の現在の事業者一覧を取得してください。
</Note>

<Warning>
  **金額の丸め**：**VND**、**JPY**、**XAF**、**KRW**、**XOF** では、処理中にその通貨が対応する精度へ金額が丸められるため、取引に記録される金額が送信した値とわずかに異なる場合があります。消込は、送信した値ではなく API のレスポンスと Webhook のペイロードにある金額に対して行ってください。[金額の丸め](/ja/api/v2/introduction#amount-rounding)を参照してください。
</Warning>

### 作成した後

* 消込には **Get payin requests in a period** と **Get payin details** を使います。
* 決済後の操作には **Refund payin** と **Cancel payin** を使います。
* ステータスが `received` または `return_received` に変わると Webhook が発火します。

## Payout：資金の送金

<Steps>
  <Step title="Payout の手段を取得する">
    対応している送金の手段を取得します。
  </Step>

  <Step title="Payout の必須項目を取得する">
    選択した手段の必須項目を取得します。
  </Step>

  <Step title="Payout を作成する">
    `POST /v2/payouts`：必須項目を指定して開始します。
  </Step>
</Steps>

<Tip>
  手順 1〜2 は手段ごとに一度だけ必要です。
</Tip>

### Payout のステータス

| ステータス        | 意味                                         |
| ------------ | ------------------------------------------ |
| `created`    | Payout が作成された状態                            |
| `processing` | 処理中の状態                                     |
| `scheduled`  | 受取人への資金の送金を待っている状態                         |
| `completed`  | バッチ全体が完了した状態。1件の取引が失敗してもバッチの完了は**妨げられません** |

### 事業者の一覧と補助エンドポイント

多くの 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** のエンドポイント：支払人と受取人の情報を保存し、取引をまたいで再利用します。

<Info>
  Payout の資金は、蓄積された Payin とトップアップからなる通貨ごとの残高から充当されます。Payout を開始する前に、該当する通貨の残高が満たされていることを確認してください。
</Info>

## Webhook の取り扱い

<Warning>
  作成の呼び出しで `webhook_notification.endpoint_url` と `authorization_header` を指定してください。すべての配信に対して `200 OK` を返し、重複を冪等に処理してください。200 以外のレスポンスは 15 分間隔で3回リトライされます。リクエストごとに異なる `authorization_header` を使ってください。
</Warning>


## Related topics

- [Hello Clever 開発者ドキュメント](/ja/index.md)
- [AUD、JPY、USD の Payin と Payout を扱う](/ja/platform-overview/payment-concepts/multi-currency-payins-payouts.md)
- [AU、日本、米国における為替と精算](/ja/platform-overview/payment-concepts/fx-and-settlement.md)