Hello Clever Developer Docs

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

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

Get Payout Methods

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

レスポンスの項目

object[]

利用できる Payout の手段の配列。

表示 properties

string

ISO 4217 の通貨コード。

string

手段の識別子（例：vn_bank_vnd）。Payout を作成するときに payout_method_name としてこの値を渡します。

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

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'

{
  "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"
    }
  ]
}

Get Payout Required Fields

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

クエリのパラメーター

string

必須

Get Payout Methods から返された手段の識別子（例：vn_bank_vnd）。

レスポンスの項目

object

リクエストした Payout の手段の詳細。

表示 properties

string

ISO 4217 の通貨コード。symbol と logo もあわせて返されます。

string

手段の識別子。

string

手段について人が読める説明。

object

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

object[]

対応する銀行または電子ウォレット。それぞれ code、name、short_name を持ちます。事業者の選択が不要な手段では空になります。

string

Payout の手段では pay_out です。

boolean

Payout の前にコンタクトの記録が必要かどうか。require_kyc、is_refundable、is_cancellable もあわせて返されます。

number

Payout の最小金額。上限は max_amount です。

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'

{
  "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
  }
}

Create Payout

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

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

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

ボディのパラメーター

string

必須

Get Payout Methods が返した手段の識別子（例：vn_bank_vnd）。

string

必須

ISO 4217 の通貨コード。

object[]

必須

Payout の取引の配列。各取引は独立して処理されます。

表示 properties

string

必須

受取人の名。文字、数字、単一の空白のみ使用できます。

string

必須

受取人の姓。文字、数字、単一の空白のみ使用できます。

string

必須

受取人のメールアドレス。手段が require_contact: true を返す場合、コンタクトの作成に使ったメールアドレスと一致させる必要があります。

number

必須

その通貨の基本単位における送金額。VND、JPY、XAF、KRW、XOF では、この値がその通貨が対応する精度へ丸められます。金額の丸めを参照してください。usdc_bank では任意です。

object

必須

選択した手段における受取人の情報（account_number、account_name、bank_code など）。正確なキーは Get Payout Required Fields で確認してください。手段ごとに異なります。

string

この取引に対する自社の一意の識別子。

string

必須

Payout のバッチの説明。5 文字以上である必要があります。

object

必須

この Payout のバッチの Webhook の設定。

表示 properties

string

必須

Webhook のエンドポイントの URL。TLS 1.2 で、広く知られた商用認証局の証明書が必要です。

string

必須

各 Webhook の通知で送られる authorization ヘッダーの値。

string

Payout を将来の時刻に予約するための日時（YYYY-MM-DDTHH:mm:ss 形式）。UTC として解釈されます。

string

バッチに対する自社の識別子。Get Payouts in a Period の絞り込み条件として使えます。

レスポンスの項目

string

Payout のバッチの一意の識別子。

string

バッチの現在のステータス。created、processing、scheduled、completed のいずれかです。

string

バッチ内のすべての取引の合計金額。

object[]

個々の取引の結果の配列。

表示 properties

string

個々の取引の UUID。

string

受取人の氏名。

string

受取人のメールアドレス。

string

この取引の金額。

object

この取引で送信された受取人の情報。

string

この取引のステータス。

string

この取引の失敗理由、または null。

string

指定した場合、この取引に対する自社の識別子。

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"
  }'

{
  "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"
}

Get Payout Details

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

クエリのパラメーター

string

必須

Payout のバッチの UUID。

string

バッチ内の個々の取引の UUID。その取引のみを返す場合に指定します。

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'

{
  "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": ""
}

Get Payouts in a Period

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

クエリのパラメーター

string

必須

期間の開始日時（ISO 8601 形式）。

string

必須

期間の終了日時（ISO 8601 形式）。

string

自社の識別子に一致する Payout のバッチに絞り込みます。

number

デフォルト:"1"

ページ分割のページ番号。

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'

{
  "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"
    }
  ]
}

Cancel Scheduled Payout

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

ボディのパラメーター

string

必須

取り消す予約済み Payout の UUID。

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" }'

{
  "uuid": "PAY8TK21",
  "status": "cancelled",
  "message": "Scheduled payout cancelled successfully"
}

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

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

ボディのパラメーター

string

必須

模擬する Payout の UUID。

string

必須

模擬する結果。completed または failed です。

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" }'

{
  "uuid": "PAY8TK21",
  "status": "completed",
  "message": "Payout simulation successful"
}

Get Branch Codes

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

クエリのパラメーター

string

必須

支店コードを調べる対象の Payout の手段 (vn_bank_vnd)。

string

必須

送金先の銀行の SWIFT コード。VietQR のコードから SWIFT コードを解決するには、Lookup via QR Content または Lookup via QR Image を使ってください。

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'

{
  "branch_codes": [
    {
      "branch_code": "79600001",
      "branch_name": "NH THE SIAM COMMERCIAL BANK PUBLIC-CN TP HO CHI MINH (NH The Siam Commercial Bank Public)"
    }
  ]
}

Lookup via QR Content

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

ボディのパラメーター

string

必須

VietQR の QR コードにエンコードされた生の文字列。

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..." }'

{
  "account_name": "NGUYEN VAN A",
  "account_number": "1234567890",
  "bank_name": "Vietcombank",
  "swift_code": "BFTVVNVX"
}

Lookup via QR Image

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

ボディのパラメーター

string

必須

VietQR の QR コードの Base64 エンコードされた画像。

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..." }'

{
  "account_name": "NGUYEN VAN A",
  "account_number": "1234567890",
  "bank_name": "Vietcombank",
  "swift_code": "BFTVVNVX"
}

基本

Payment Gateway (AUD)

Multi-Currency Payment API

Payment Gateway 3

Card API

Cashback API

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

Get Payout Methods

レスポンスの項目

Get Payout Required Fields

クエリのパラメーター

レスポンスの項目

Create Payout

ボディのパラメーター

レスポンスの項目

Get Payout Details

クエリのパラメーター

Get Payouts in a Period

クエリのパラメーター

Cancel Scheduled Payout

ボディのパラメーター

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

ボディのパラメーター

Get Branch Codes

クエリのパラメーター

Lookup via QR Content

ボディのパラメーター

Lookup via QR Image

ボディのパラメーター

​Get Payout Methods

​レスポンスの項目

​Get Payout Required Fields

​クエリのパラメーター

​レスポンスの項目

​Create Payout

​ボディのパラメーター

​レスポンスの項目

​Get Payout Details

​クエリのパラメーター

​Get Payouts in a Period

​クエリのパラメーター

​Cancel Scheduled Payout

​ボディのパラメーター

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

​ボディのパラメーター

​Get Branch Codes

​クエリのパラメーター

​Lookup via QR Content

​ボディのパラメーター

​Lookup via QR Image

​ボディのパラメーター

Get Payout Methods

レスポンスの項目

Get Payout Required Fields

クエリのパラメーター

レスポンスの項目

Create Payout

ボディのパラメーター

レスポンスの項目

Get Payout Details

クエリのパラメーター

Get Payouts in a Period

クエリのパラメーター

Cancel Scheduled Payout

ボディのパラメーター

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

ボディのパラメーター

Get Branch Codes

クエリのパラメーター

Lookup via QR Content

ボディのパラメーター

Lookup via QR Image

ボディのパラメーター