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

# 多通貨 Payout API リファレンス (v2)

> Hello Clever の v2 Payout エンドポイントで、複数の通貨の受取人へ資金を送ります。銀行振込、モバイルマネー、QR などに対応します。

v2 Payout API では、APAC、アフリカ、ラテンアメリカ、その他の地域の受取人へ、複数の通貨で資金を支払えます。銀行口座、モバイルマネーのウォレット、PayID、QR ベースのネットワークへの Payout が可能です。このページでは、スケジュール Payout の管理、支店コードの照会、QR による銀行口座の解決を含む、すべての Payout のエンドポイントを扱います。

<Note>
  Get Payout Methods と Get Required Fields を呼び出す必要があるのは、手段ごとに一度だけです。最初に確認した後は、その通貨の今後のすべての Payout で同じ手段のコードと項目の構成を再利用できます。
</Note>

***

## Get Payout Methods

<Badge color="green">GET</Badge> `/v2/payouts/payout_methods`

Hello Clever の Merchant Dashboard に設定された国と通貨に基づいて、`app-id` で利用できるすべての Payout の手段を返します。

### レスポンスの項目

<ResponseField name="records" type="object[]">
  利用できる Payout の手段の配列。

  <Expandable title="properties">
    <ResponseField name="currency" type="string">
      ISO 4217 の通貨コード。
    </ResponseField>

    <ResponseField name="payout_method_name" type="string">
      手段の識別子（例：`vn_bank_vnd`）。Payout を作成するときに `payout_method_name` としてこの値を渡します。
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  v2 は Payout の手段を `payout_method_code` ではなく `payout_method_name` で識別します。手段の上下限、対応銀行、必須パラメーターについては Get Payout Required Fields を呼び出してください。
</Note>

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url https://api.cleverhub.co/api/v2/payouts/payout_methods \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY'
  ```

  ```json Response theme={null}
  {
    "records": [
      {
        "currency": "PHP",
        "payout_method_name": "ph_bank_maya_php"
      },
      {
        "currency": "PHP",
        "payout_method_name": "ph_ewallet_gcash_php"
      },
      {
        "currency": "PHP",
        "payout_method_name": "ph_bank_php"
      }
    ]
  }
  ```
</CodeGroup>

***

## Get Payout Required Fields

<Badge color="green">GET</Badge> `/v2/payouts/payout_method/params`

特定の Payout の手段について、必要（または任意）な項目を返します。特定の国への銀行振込など一部の Payout の手段では、受取人の銀行コード、口座番号、その他の情報が必要です。

### クエリのパラメーター

<ParamField query="payout_method_name" type="string" required>
  Get Payout Methods から返された手段の識別子（例：`vn_bank_vnd`）。
</ParamField>

### レスポンスの項目

<ResponseField name="record" type="object">
  リクエストした Payout の手段の詳細。

  <Expandable title="properties">
    <ResponseField name="currency" type="string">
      ISO 4217 の通貨コード。`symbol` と `logo` もあわせて返されます。
    </ResponseField>

    <ResponseField name="payout_method_name" type="string">
      手段の識別子。
    </ResponseField>

    <ResponseField name="description" type="string">
      手段について人が読める説明。
    </ResponseField>

    <ResponseField name="payout_method_params" type="object">
      各取引の `payout_method_params` で送るキー。各項目は `type:Mandatory|Optional <description>` の形式で表されます。
    </ResponseField>

    <ResponseField name="banks" type="object[]">
      対応する銀行または電子ウォレット。それぞれ `code`、`name`、`short_name` を持ちます。事業者の選択が不要な手段では空になります。
    </ResponseField>

    <ResponseField name="payment_type" type="string">
      Payout の手段では `pay_out` です。
    </ResponseField>

    <ResponseField name="require_contact" type="boolean">
      Payout の前にコンタクトの記録が必要かどうか。`require_kyc`、`is_refundable`、`is_cancellable` もあわせて返されます。
    </ResponseField>

    <ResponseField name="min_amount" type="number">
      Payout の最小金額。上限は `max_amount` です。
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url 'https://api.cleverhub.co/api/v2/payouts/payout_method/params?payout_method_name=ph_bank_maya_php' \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY'
  ```

  ```json Response theme={null}
  {
    "record": {
      "currency": "PHP",
      "symbol": "₱",
      "logo": "",
      "payout_method_name": "ph_bank_maya_php",
      "description": "MAYA",
      "payout_method_params": {
        "account_number": "string:Mandatory Bank Account Number",
        "account_name": "string:Mandatory Account Holder Name",
        "bank_code": "string:Mandatory Bank Code"
      },
      "banks": [
        {
          "code": "600",
          "name": "GCASH",
          "short_name": null
        }
      ],
      "payment_type": "pay_out",
      "is_refundable": false,
      "is_cancellable": false,
      "require_contact": false,
      "require_kyc": false,
      "min_amount": 200,
      "max_amount": 50000
    }
  }
  ```
</CodeGroup>

***

## Create Payout

<Badge color="blue">POST</Badge> `/v2/payouts`

1件以上の Payout の取引を開始します。各 Payout は独立して処理されます。バッチ内の1件の取引が失敗しても、他の取引は完了します。

Payout のステータス：

* `created`：Payout が開始された状態。
* `processing`：Payout が処理中の状態。
* `scheduled`：受取人への資金の送金を待っている状態。
* `completed`：バッチ全体が完了した状態。
* `expired`：処理の期間内に Payout が処理されなかった状態。

<Note>
  `vn_bank_vnd` の Payout で金額が 300,000,000 VND を超える場合、または銀行が求める場合は、`branch_code` を含める必要があります。有効な支店コードを調べるには Get Branch Codes のエンドポイントを使ってください。
</Note>

### ボディのパラメーター

<ParamField body="payout_method_name" type="string" required>
  Get Payout Methods が返した手段の識別子（例：`vn_bank_vnd`）。
</ParamField>

<ParamField body="currency" type="string" required>
  ISO 4217 の通貨コード。
</ParamField>

<ParamField body="payout_transaction_details" type="object[]" required>
  Payout の取引の配列。各取引は独立して処理されます。

  <Expandable title="properties">
    <ParamField body="first_name" type="string" required>
      受取人の名。文字、数字、単一の空白のみ使用できます。
    </ParamField>

    <ParamField body="last_name" type="string" required>
      受取人の姓。文字、数字、単一の空白のみ使用できます。
    </ParamField>

    <ParamField body="email" type="string" required>
      受取人のメールアドレス。手段が `require_contact: true` を返す場合、コンタクトの作成に使ったメールアドレスと一致させる必要があります。
    </ParamField>

    <ParamField body="amount" type="number" required>
      その通貨の基本単位における送金額。`VND`、`JPY`、`XAF`、`KRW`、`XOF` では、この値がその通貨が対応する精度へ丸められます。[金額の丸め](/ja/api/v2/introduction#amount-rounding)を参照してください。`usdc_bank` では任意です。
    </ParamField>

    <ParamField body="payout_method_params" type="object" required>
      選択した手段における受取人の情報（`account_number`、`account_name`、`bank_code` など）。正確なキーは Get Payout Required Fields で確認してください。手段ごとに異なります。
    </ParamField>

    <ParamField body="external_id" type="string">
      この取引に対する自社の一意の識別子。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="description" type="string" required>
  Payout のバッチの説明。5 文字以上である必要があります。
</ParamField>

<ParamField body="webhook_notification" type="object" required>
  この Payout のバッチの Webhook の設定。

  <Expandable title="properties">
    <ParamField body="endpoint_url" type="string" required>
      Webhook のエンドポイントの URL。TLS 1.2 で、広く知られた商用認証局の証明書が必要です。
    </ParamField>

    <ParamField body="authorization_header" type="string" required>
      各 Webhook の通知で送られる authorization ヘッダーの値。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="scheduled_at" type="string">
  Payout を将来の時刻に予約するための日時（`YYYY-MM-DDTHH:mm:ss` 形式）。UTC として解釈されます。
</ParamField>

<ParamField body="external_id" type="string">
  バッチに対する自社の識別子。Get Payouts in a Period の絞り込み条件として使えます。
</ParamField>

### レスポンスの項目

<ResponseField name="uuid" type="string">
  Payout のバッチの一意の識別子。
</ResponseField>

<ResponseField name="status" type="string">
  バッチの現在のステータス。`created`、`processing`、`scheduled`、`completed` のいずれかです。
</ResponseField>

<ResponseField name="total_amount" type="string">
  バッチ内のすべての取引の合計金額。
</ResponseField>

<ResponseField name="payout_transactions" type="object[]">
  個々の取引の結果の配列。

  <Expandable title="properties">
    <ResponseField name="uuid" type="string">
      個々の取引の UUID。
    </ResponseField>

    <ResponseField name="payee" type="string">
      受取人の氏名。
    </ResponseField>

    <ResponseField name="email" type="string">
      受取人のメールアドレス。
    </ResponseField>

    <ResponseField name="amount" type="string">
      この取引の金額。
    </ResponseField>

    <ResponseField name="payout_method_params" type="object">
      この取引で送信された受取人の情報。
    </ResponseField>

    <ResponseField name="status" type="string">
      この取引のステータス。
    </ResponseField>

    <ResponseField name="error_message" type="string">
      この取引の失敗理由、または `null`。
    </ResponseField>

    <ResponseField name="external_id" type="string">
      指定した場合、この取引に対する自社の識別子。
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl --request POST \
    --url https://api.cleverhub.co/api/v2/payouts \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "payout_transaction_details": [
        {
          "first_name": "Nguyen",
          "last_name": "Van A",
          "email": "payee@example.com",
          "amount": 100000,
          "payout_method_params": {
            "account_number": "1234567890",
            "account_name": "Nguyen Van A",
            "bank_code": "VCB"
          },
          "external_id": "salary_jan_001"
        }
      ],
      "currency": "VND",
      "payout_method_name": "vn_bank_vnd",
      "description": "Salary payment",
      "webhook_notification": {
        "endpoint_url": "https://yoursite.com/webhooks/payout",
        "authorization_header": "Bearer abc123xyz"
      },
      "external_id": "batch_jan_001"
    }'
  ```

  ```json Response theme={null}
  {
    "uuid": "PAY8TK21",
    "currency": "VND",
    "payout_method_name": "vn_bank_vnd",
    "description": "Salary payment",
    "total_amount": "100000",
    "status": "created",
    "scheduled_at": null,
    "payout_transactions": [
      {
        "uuid": "TXN9QM45",
        "balance_id": null,
        "payee": "Nguyen Van A",
        "email": "payee@example.com",
        "amount": "100000",
        "payout_method_params": {
          "account_number": "1234567890",
          "account_name": "Nguyen Van A",
          "bank_code": "VCB"
        },
        "status": "created",
        "error_message": null,
        "external_id": "salary_jan_001",
        "created_at": "2025-01-15T10:00:00.000+0000"
      }
    ],
    "external_id": "batch_jan_001"
  }
  ```
</CodeGroup>

***

## Get Payout Details

<Badge color="green">GET</Badge> `/v2/payouts/detail`

UUID を指定して、Payout のバッチの現在のステータスと詳細を返します。

### クエリのパラメーター

<ParamField query="uuid" type="string" required>
  Payout のバッチの UUID。
</ParamField>

<ParamField query="child_uuid" type="string">
  バッチ内の個々の取引の UUID。その取引のみを返す場合に指定します。
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url 'https://api.cleverhub.co/api/v2/payouts/detail?uuid=PAY8TK21' \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY'
  ```

  ```json Response theme={null}
  {
    "uuid": "PAY8TK21",
    "currency": "VND",
    "payout_method_name": "vn_bank_vnd",
    "description": "Salary payment",
    "total_amount": "100000",
    "status": "completed",
    "scheduled_at": null,
    "payout_transactions": [
      {
        "uuid": "TXN9QM45",
        "payee": "Nguyen Van A",
        "email": "payee@example.com",
        "amount": "100000",
        "status": "completed",
        "error_message": null,
        "reference": null,
        "external_id": "salary_jan_001",
        "created_at": "2025-01-15T10:00:00.000+0000"
      }
    ],
    "external_id": "batch_jan_001",
    "error_code": null,
    "error_message": ""
  }
  ```
</CodeGroup>

***

## Get Payouts in a Period

<Badge color="green">GET</Badge> `/v2/payouts/all`

期間内の Payout のバッチのページ分割された一覧を返します。最大1年の期間に対応します。より長い期間が必要な場合は Hello Clever へお問い合わせください。

### クエリのパラメーター

<ParamField query="from_date" type="string" required>
  期間の開始日時（ISO 8601 形式）。
</ParamField>

<ParamField query="to_date" type="string" required>
  期間の終了日時（ISO 8601 形式）。
</ParamField>

<ParamField query="external_id" type="string">
  自社の識別子に一致する Payout のバッチに絞り込みます。
</ParamField>

<ParamField query="page" type="number" default="1">
  ページ分割のページ番号。
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url 'https://api.cleverhub.co/api/v2/payouts/all?from_date=2025-01-01T00:00:00Z&to_date=2025-01-31T23:59:59Z&page=1' \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY'
  ```

  ```json Response theme={null}
  {
    "from_date": "2025-01-01T00:00:00.000+0000",
    "to_date": "2025-01-31T23:59:59.000+0000",
    "page": 1,
    "size": 10,
    "next_page": null,
    "total_page": 1,
    "total_count": 1,
    "records": [
      {
        "uuid": "PAY8TK21",
        "currency": "VND",
        "status": "completed"
      }
    ]
  }
  ```
</CodeGroup>

***

## Cancel Scheduled Payout

<Badge color="blue">POST</Badge> `/v2/payouts/cancel_scheduled`

将来の実行が予約された Payout を取り消します。取り消せるのは `scheduled` のステータスの Payout のみです。

### ボディのパラメーター

<ParamField body="uuid" type="string" required>
  取り消す予約済み Payout の UUID。
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  curl --request POST \
    --url https://api.cleverhub.co/api/v2/payouts/cancel_scheduled \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY' \
    --header 'Content-Type: application/json' \
    --data '{ "uuid": "PAY8TK21" }'
  ```

  ```json Response theme={null}
  {
    "uuid": "PAY8TK21",
    "status": "cancelled",
    "message": "Scheduled payout cancelled successfully"
  }
  ```
</CodeGroup>

***

## Payout のシミュレーション（サンドボックスのみ）

<Badge color="blue">POST</Badge> `/v2/payouts/simulate`

サンドボックス環境で、保留中の Payout の結果を模擬します。本番環境では利用できません。

### ボディのパラメーター

<ParamField body="uuid" type="string" required>
  模擬する Payout の UUID。
</ParamField>

<ParamField body="status" type="string" required>
  模擬する結果。`completed` または `failed` です。
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  curl --request POST \
    --url https://api.cleverhub.co/api/v2/payouts/simulate \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY' \
    --header 'Content-Type: application/json' \
    --data '{ "uuid": "PAY8TK21", "status": "completed" }'
  ```

  ```json Response theme={null}
  {
    "uuid": "PAY8TK21",
    "status": "completed",
    "message": "Payout simulation successful"
  }
  ```
</CodeGroup>

***

## Get Branch Codes

<Badge color="green">GET</Badge> `/v2/payouts/branch_codes`

`vn_bank_vnd` の Payout の手段について支店コードを返します。Payout の金額が 300,000,000 VND を超える場合、または送金先の銀行が求める場合に支店コードが必要です。

### クエリのパラメーター

<ParamField query="payout_method_name" type="string" required>
  支店コードを調べる対象の Payout の手段 (`vn_bank_vnd`)。
</ParamField>

<ParamField query="swift_code" type="string" required>
  送金先の銀行の SWIFT コード。VietQR のコードから SWIFT コードを解決するには、Lookup via QR Content または Lookup via QR Image を使ってください。
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url 'https://api.cleverhub.co/api/v2/payouts/branch_codes?payout_method_name=vn_bank_vnd&swift_code=BFTVVNVX' \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY'
  ```

  ```json Response theme={null}
  {
    "branch_codes": [
      {
        "branch_code": "79600001",
        "branch_name": "NH THE SIAM COMMERCIAL BANK PUBLIC-CN TP HO CHI MINH (NH The Siam Commercial Bank Public)"
      }
    ]
  }
  ```
</CodeGroup>

***

## Lookup via QR Content

<Badge color="blue">POST</Badge> `/v2/banks/lookup/qr_content`

VietQR (EMV Co) の QR コードの内容の文字列から、銀行口座の情報を解決します。QR の内容が有効な場合、口座名義、口座番号、銀行名、SWIFT コードを返します。

### ボディのパラメーター

<ParamField body="qr_content" type="string" required>
  VietQR の QR コードにエンコードされた生の文字列。
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  curl --request POST \
    --url https://api.cleverhub.co/api/v2/banks/lookup/qr_content \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY' \
    --header 'Content-Type: application/json' \
    --data '{ "qr_content": "00020101021238570010A000000727..." }'
  ```

  ```json Response theme={null}
  {
    "account_name": "NGUYEN VAN A",
    "account_number": "1234567890",
    "bank_name": "Vietcombank",
    "swift_code": "BFTVVNVX"
  }
  ```
</CodeGroup>

***

## Lookup via QR Image

<Badge color="blue">POST</Badge> `/v2/banks/lookup/qr_image`

VietQR (EMV Co) の QR コードの画像から、銀行口座の情報を解決します。画像に有効な QR のデータが含まれる場合、口座名義、口座番号、銀行名、SWIFT コードを返します。

### ボディのパラメーター

<ParamField body="qr_image" type="string" required>
  VietQR の QR コードの Base64 エンコードされた画像。
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  curl --request POST \
    --url https://api.cleverhub.co/api/v2/banks/lookup/qr_image \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY' \
    --header 'Content-Type: application/json' \
    --data '{ "qr_image": "iVBORw0KGgoAAAANSUhEUgAA..." }'
  ```

  ```json Response theme={null}
  {
    "account_name": "NGUYEN VAN A",
    "account_number": "1234567890",
    "bank_name": "Vietcombank",
    "swift_code": "BFTVVNVX"
  }
  ```
</CodeGroup>


## Related topics

- [多通貨 Payin API リファレンス (v2)](/ja/api/v2/payin.md)
- [残高 API リファレンス (v2)](/ja/api/v2/balance.md)
- [AUD 残高 API リファレンス](/ja/api/v1/balance.md)