Hello Clever Developer Docs

v2 Payin API では、統一された1つのスキーマで、複数の通貨で顧客から決済を回収できます。銀行振込、電子ウォレット、QR 決済、モバイルマネーなどを、すべて同じエンドポイント群で受け付けられます。このページでは、テスト用のサンドボックスのシミュレーションを含む、すべての Payin のエンドポイントを解説します。

Payin を作成する前に、Get Payin Methods と Get Required Fields を呼び出して、設定した通貨で利用できる決済手段と顧客の項目を確認してください。

Get Payin Methods

GET /v2/payins/payin_methods app-id で利用できるすべての決済手段を返します。返される手段は、Hello Clever の Merchant Dashboard に設定された国と通貨によって決まります。

レスポンスの項目

object[]

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

表示 properties

string

ISO 4217 の通貨コード（例：MYR、VND）。

string

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

v2 は決済手段を payin_method_name で識別します。payin_method_code の項目は v3 ゲートウェイのものであり、ここでは返されず、受け付けられません。手段の上下限、ロゴ、必須パラメーターについては Get Payin Required Fields を呼び出してください。

curl --request GET \
  --url https://api.cleverhub.co/api/v2/payins/payin_methods \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY'

{
  "records": [
    {
      "currency": "MYR",
      "payin_method_name": "my_bank_duitnow_myr"
    }
  ]
}

Get Payin Required Fields

GET /v2/payins/payin_method/params 特定の決済手段で Payin を作成するために必要（または任意）な項目を返します。収集すべき顧客のデータを把握するため、手段ごとに一度呼び出してください。

クエリのパラメーター

string

必須

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

レスポンスの項目

object

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

表示 properties

string

ISO 4217 の通貨コード。

string

通貨記号。

string

銀行または電子ウォレットのロゴの URL。

string

手段の識別子。

string

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

object

Payin の作成時に payin_method_params で送るパラメーター。各項目は type:Mandatory|Optional <description> の形式で表されます。

object[]

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

string

Payin の手段では pay_in です。

boolean

この手段で完了した Payin が返金可能かどうか。

boolean

この手段の保留中の Payin が取消可能かどうか。

boolean

Payin を開始する前にコンタクトの記録を作成する必要があるかどうか。

boolean

この手段で KYC の確認が必要かどうか。

number

その通貨の基本単位における最小取引金額。

number

その通貨の基本単位における最大取引金額。

curl --request GET \
  --url 'https://api.cleverhub.co/api/v2/payins/payin_method/params?payin_method_name=au_payid_npp_aud' \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY'

{
  "record": {
    "currency": "AUD",
    "symbol": "$",
    "logo": "",
    "payin_method_name": "au_payid_npp_aud",
    "description": "New Payments Platform (NPP)",
    "payin_method_params": {
      "callback_url": "string:Mandatory callback URL"
    },
    "payment_type": "pay_in",
    "is_refundable": false,
    "is_cancellable": false,
    "require_contact": true,
    "require_kyc": false,
    "min_amount": 20,
    "max_amount": 10000
  }
}

Create Payin

POST /v2/payins 新しい Payin のリクエストを作成します。正しい手段のコードと必須項目を揃えるため、先に Get Payin Methods と Get Required Fields を呼び出す必要があります。

Payin の手段が jp_bank_jpy、ar_bank_ars、kr_bank_va_kyc_krw の場合、バーチャル口座番号などの決済情報は API のレスポンスではなく、Payin の作成後に Webhook を通じて非同期に届きます。

ボディのパラメーター

string

必須

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

object

必須

手段ごとのパラメーター。この手段が想定する正確なキーは Get Payin Required Fields で確認してください。手段ごとに異なり、一部は必須です。パラメーターが不要な手段には {} を送ります。

表示 properties

boolean

デフォルト:"false"

送信の前に、顧客の名前を銀行が求める文字体系に変換します。対応しているのは jp_bank_jpy のみで、first_name / last_name を全角カタカナに変換します。入力はラテン文字のみのローマ字である必要があり、無効な入力はバリデーションエラーを返します。他の手段では無視されます。

number

必須

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

string

必須

ISO 4217 の通貨コード（例：MYR、VND、AUD）。

string

必須

顧客の名前。

string

必須

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

string

必須

この決済の説明。

boolean

必須

取引に GST を含めます。オーストラリアの加盟店による AUD の取引の場合のみ true に設定してください。

object

必須

この Payin の Webhook の設定。

表示 properties

string

必須

Webhook のエンドポイントの URL。TLS 1.2 で、広く知られた商用認証局の証明書が必要です。自己署名証明書と内部で署名された証明書は拒否されます。

string

必須

各 Webhook 呼び出しで送られる authorization ヘッダーの値。セキュリティのため、決済ごとに一意の値を使ってください。

string

この取引に対する自社の識別子。Payin に返され、Get Payins in a Period の絞り込み条件として使えます。

string

YYYY-MM-DDTHH:mm:ss 形式の失効日時。適用されるのは vn_vietqr_vnd のみで、他のすべての手段は上書きできない固定の既定値を使います。少なくとも 15 分先である必要があります。

object

取引に付加する任意のカスタムのキーバリューのデータ。Payin と Webhook のペイロードにそのまま返されます。

v2 には sender_info、expire_in、redirect_url はありません。これらは v3 ゲートウェイのものです。顧客はトップレベルの name と email として送り、失効には expired_at を使ってください。

レスポンスの項目

string

この Payin の取引の一意の識別子。

string

現在のステータス。pending、waiting、received、expired、return_pending、return_received、return_expired、return_rejected のいずれかです。ライフサイクル全体は決済のステータスを参照してください。

string

決済がオーソリのフローのどこにあるか。normal_stage、authorize_otp、authorize_stk のいずれかです。

object

顧客が支払いを完了するために使う情報。内容は手段によって異なり、ホスト型のフローでは payment_url、銀行振込では account_name、account_number、bank_name などの銀行の項目になります。jp_bank_jpy、ar_bank_ars、kr_bank_va_kyc_krw では、レスポンスではなく Webhook で届きます。

string

この取引で使用された payin_method_name。

number

取引金額。gst_amount、total、paid_amount とあわせて返されます。

boolean

この Payin が返金可能かどうか。

string

Payin が失効する日時。pay_by は顧客が支払うべき期限を返します。

curl --request POST \
  --url https://api.cleverhub.co/api/v2/payins \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "currency": "MYR",
    "amount": 10000,
    "name": "Jane Smith",
    "email": "customer@example.com",
    "gst": false,
    "external_id": "123456",
    "description": "Invoice #1234",
    "payin_method_name": "my_bank_duitnow_myr",
    "payin_method_params": {},
    "webhook_notification": {
      "endpoint_url": "https://yoursite.com/webhooks/payin",
      "authorization_header": "Bearer abc123xyz"
    },
    "metadata": {
      "custom_note": "Priority customer"
    }
  }'

{
  "uuid": "Q3NT0K80",
  "name": "Jane Smith",
  "description": "Invoice #1234",
  "email": "customer@example.com",
  "external_id": "123456",
  "status": "pending",
  "stage": "normal_stage",
  "pay_code": {
    "payment_url": "https://paylink.cleverhub.co/UTNOVDBLODA"
  },
  "currency": "MYR",
  "gst": false,
  "amount": "10000.0",
  "gst_amount": "0",
  "total": "10000.0",
  "paid_amount": "0",
  "payment_method": "my_bank_duitnow_myr",
  "is_refundable": "true",
  "expired_at": "2025-09-11T16:30:02.712Z",
  "pay_by": "2025-09-11T16:30:02.712Z"
}

Webhook はベストエフォートで呼び出されます。エンドポイントが HTTP 200 を返さない場合、Hello Clever は 15 分の間隔を置いて3回リトライします。Webhook のハンドラーは冪等になるよう設計してください。

Get Payin Details

GET /v2/payins/detail UUID を指定して、特定の Payin のリクエストの完全な詳細を返します。

クエリのパラメーター

string

必須

Payin の取引の一意の識別子。

curl --request GET \
  --url 'https://api.cleverhub.co/api/v2/payins/detail?uuid=Q3NT0K80' \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY'

{
  "uuid": "Q3NT0K80",
  "status": "received",
  "amount": 10000,
  "currency": "MYR",
  "payin_method_name": "my_bank_duitnow_myr",
  "created_at": "2025-09-11T10:30:02.000Z",
  "expired_at": "2025-09-11T16:30:02.712Z",
  "is_refundable": true,
  "is_cancellable": false
}

Get Payins in a Period

GET /v2/payins/all app-id に紐づく Payin の取引のページ分割された一覧を返します。期間と、任意でステータスによる絞り込みができます。既定では1ページ 20 件を返します。

クエリのパラメーター

string

必須

期間の開始日時（ISO 8601 形式。例：2025-01-01T00:00:00Z）。

string

必須

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

string

自社の識別子に一致する Payin に絞り込みます。

number

デフォルト:"1"

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

number

デフォルト:"20"

1 ページあたりの件数。

curl --request GET \
  --url 'https://api.cleverhub.co/api/v2/payins/all?from_date=2025-01-01T00:00:00Z&to_date=2025-01-31T23:59:59Z&page=1&per_page=20' \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY'

{
  "total": 45,
  "page": 1,
  "limit": 20,
  "records": [
    {
      "uuid": "Q3NT0K80",
      "status": "received",
      "amount": 10000,
      "currency": "MYR",
      "created_at": "2025-01-15T10:30:00.000Z"
    }
  ]
}

Cancel Payin

POST /v2/payins/cancel pending の Payin の取引を取り消します。ステータスは expired へ移ります。このエンドポイントを呼び出す前に、その Payin の手段で is_cancellable == true であることを確認してください。

ボディのパラメーター

string

必須

取り消す保留中の Payin の UUID。

curl --request POST \
  --url https://api.cleverhub.co/api/v2/payins/cancel \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "uuid": "Q3NT0K80" }'

{
  "uuid": "Q3NT0K80",
  "status": "expired",
  "message": "Payin cancelled successfully"
}

Refund Payin

POST /v2/payins/refund 完了した (received) Payin に対して返金を開始します。このエンドポイントを呼び出す前に、その取引で is_refundable == true であることを確認してください。

Payin が成功した直後に返金を開始する場合、返金は全額でなければなりません。一部返金は、Payin の完了から 30 分から1時間経過した後にのみ対応しています。

ボディのパラメーター

string

必須

返金する received の Payin の UUID。

string

必須

返金の理由。5 文字以上である必要があります。

number

返金する金額。省略した場合は全額が返金されます。一部返金は Payin の完了から 30〜60 分後にのみ可能です。

curl --request POST \
  --url https://api.cleverhub.co/api/v2/payins/refund \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "uuid": "Q3NT0K80",
    "amount": 5000,
    "description": "Partial refund requested by customer"
  }'

{
  "uuid": "Q3NT0K80",
  "refund_status": "return_pending",
  "refund_amount": 5000,
  "message": "Refund initiated"
}

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

POST /v2/payins/simulate サンドボックス環境で、保留中の Payin の結果を模擬します。Payin は pending のステータスである必要があります。このエンドポイントは本番環境では利用できません。

ボディのパラメーター

string

必須

模擬する保留中の Payin の UUID。

string

必須

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

number

支払済みとして模擬する金額。既定では Payin の全額です。

curl --request POST \
  --url https://api.cleverhub.co/api/v2/payins/simulate \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "uuid": "Q3NT0K80", "status": "completed" }'

{
  "uuid": "Q3NT0K80",
  "status": "received",
  "message": "Payin simulation successful"
}

OTP による取引のオーソリ

POST /v2/payins/confirm_otp モバイルマネーの手段（例：gh_mobile_money_ghs）で Payin を作成した後、レスポンスの stage が authorize_otp であれば、顧客の電話に OTP が送信されています。顧客から OTP を受け取り、このエンドポイントへ送信してください。成功すると、顧客が PIN で決済を確定するための STK プッシュが電話へ送信されます。

ボディのパラメーター

string

必須

OTP のオーソリを待っている Payin の UUID。

string

必須

顧客の電話で受け取った OTP。

curl --request POST \
  --url https://api.cleverhub.co/api/v2/payins/confirm_otp \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "uuid": "Q3NT0K80", "code": "123456" }'

{
  "uuid": "Q3NT0K80",
  "status": "pending",
  "message": "OTP verified. STK push sent to customer."
}

OTP の再送信

POST /v2/payins/resend_otp 元の OTP が失効した、または顧客が受け取れなかった場合に、モバイルマネーの Payin の OTP を再送信します。

ボディのパラメーター

string

必須

OTP を再送信する Payin の UUID。

curl --request POST \
  --url https://api.cleverhub.co/api/v2/payins/resend_otp \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "uuid": "Q3NT0K80" }'

{
  "uuid": "Q3NT0K80",
  "message": "OTP resent successfully"
}

基本

Payment Gateway (AUD)

Multi-Currency Payment API

Payment Gateway 3

Card API

Cashback API

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

Get Payin Methods

レスポンスの項目

Get Payin Required Fields

クエリのパラメーター

レスポンスの項目

Create Payin

ボディのパラメーター

レスポンスの項目

Get Payin Details

クエリのパラメーター

Get Payins in a Period

クエリのパラメーター

Cancel Payin

ボディのパラメーター

Refund Payin

ボディのパラメーター

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

ボディのパラメーター

OTP による取引のオーソリ

ボディのパラメーター

OTP の再送信

ボディのパラメーター

​Get Payin Methods

​レスポンスの項目

​Get Payin Required Fields

​クエリのパラメーター

​レスポンスの項目

​Create Payin

​ボディのパラメーター

​レスポンスの項目

​Get Payin Details

​クエリのパラメーター

​Get Payins in a Period

​クエリのパラメーター

​Cancel Payin

​ボディのパラメーター

​Refund Payin

​ボディのパラメーター

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

​ボディのパラメーター

​OTP による取引のオーソリ

​ボディのパラメーター

​OTP の再送信

​ボディのパラメーター

Get Payin Methods

レスポンスの項目

Get Payin Required Fields

クエリのパラメーター

レスポンスの項目

Create Payin

ボディのパラメーター

レスポンスの項目

Get Payin Details

クエリのパラメーター

Get Payins in a Period

クエリのパラメーター

Cancel Payin

ボディのパラメーター

Refund Payin

ボディのパラメーター

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

ボディのパラメーター

OTP による取引のオーソリ

ボディのパラメーター

OTP の再送信

ボディのパラメーター