> ## 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 API リファレンス (v2)

> Hello Clever v2 を使って、APAC 全域の多通貨 Payin を作成、取消、返金、照会します。銀行振込、電子ウォレット、QR、モバイルマネーの各手段に対応します。

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

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

***

## Get Payin Methods

<Badge color="green">GET</Badge> `/v2/payins/payin_methods`

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

### レスポンスの項目

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

  <Expandable title="properties">
    <ResponseField name="currency" type="string">
      ISO 4217 の通貨コード（例：`MYR`、`VND`）。
    </ResponseField>

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

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

<CodeGroup>
  ```bash Request theme={null}
  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'
  ```

  ```json Response theme={null}
  {
    "records": [
      {
        "currency": "MYR",
        "payin_method_name": "my_bank_duitnow_myr"
      }
    ]
  }
  ```
</CodeGroup>

***

## Get Payin Required Fields

<Badge color="green">GET</Badge> `/v2/payins/payin_method/params`

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

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

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

### レスポンスの項目

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

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

    <ResponseField name="symbol" type="string">
      通貨記号。
    </ResponseField>

    <ResponseField name="logo" type="string">
      銀行または電子ウォレットのロゴの URL。
    </ResponseField>

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

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

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

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

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

    <ResponseField name="is_refundable" type="boolean">
      この手段で完了した Payin が返金可能かどうか。
    </ResponseField>

    <ResponseField name="is_cancellable" type="boolean">
      この手段の保留中の Payin が取消可能かどうか。
    </ResponseField>

    <ResponseField name="require_contact" type="boolean">
      Payin を開始する前にコンタクトの記録を作成する必要があるかどうか。
    </ResponseField>

    <ResponseField name="require_kyc" type="boolean">
      この手段で KYC の確認が必要かどうか。
    </ResponseField>

    <ResponseField name="min_amount" type="number">
      その通貨の基本単位における最小取引金額。
    </ResponseField>

    <ResponseField name="max_amount" type="number">
      その通貨の基本単位における最大取引金額。
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  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'
  ```

  ```json Response theme={null}
  {
    "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
    }
  }
  ```
</CodeGroup>

***

## Create Payin

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

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

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

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

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

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

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

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

<ParamField body="currency" type="string" required>
  ISO 4217 の通貨コード（例：`MYR`、`VND`、`AUD`）。
</ParamField>

<ParamField body="name" type="string" required>
  顧客の名前。
</ParamField>

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

<ParamField body="description" type="string" required>
  この決済の説明。
</ParamField>

<ParamField body="gst" type="boolean" required>
  取引に GST を含めます。オーストラリアの加盟店による AUD の取引の場合のみ `true` に設定してください。
</ParamField>

<ParamField body="webhook_notification" type="object" required>
  この Payin の 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="external_id" type="string">
  この取引に対する自社の識別子。Payin に返され、Get Payins in a Period の絞り込み条件として使えます。
</ParamField>

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

<ParamField body="metadata" type="object">
  取引に付加する任意のカスタムのキーバリューのデータ。Payin と Webhook のペイロードにそのまま返されます。
</ParamField>

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

### レスポンスの項目

<ResponseField name="uuid" type="string">
  この Payin の取引の一意の識別子。
</ResponseField>

<ResponseField name="status" type="string">
  現在のステータス。`pending`、`waiting`、`received`、`expired`、`return_pending`、`return_received`、`return_expired`、`return_rejected` のいずれかです。ライフサイクル全体は[決済のステータス](/ja/api/webhooks#payment-statuses)を参照してください。
</ResponseField>

<ResponseField name="stage" type="string">
  決済がオーソリのフローのどこにあるか。`normal_stage`、`authorize_otp`、`authorize_stk` のいずれかです。
</ResponseField>

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

<ResponseField name="payment_method" type="string">
  この取引で使用された `payin_method_name`。
</ResponseField>

<ResponseField name="amount" type="number">
  取引金額。`gst_amount`、`total`、`paid_amount` とあわせて返されます。
</ResponseField>

<ResponseField name="is_refundable" type="boolean">
  この Payin が返金可能かどうか。
</ResponseField>

<ResponseField name="expired_at" type="string">
  Payin が失効する日時。`pay_by` は顧客が支払うべき期限を返します。
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  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"
      }
    }'
  ```

  ```json Response theme={null}
  {
    "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"
  }
  ```
</CodeGroup>

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

***

## Get Payin Details

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

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

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

<ParamField query="uuid" type="string" required>
  Payin の取引の一意の識別子。
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  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'
  ```

  ```json Response theme={null}
  {
    "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
  }
  ```
</CodeGroup>

***

## Get Payins in a Period

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

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

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

<ParamField query="from_date" type="string" required>
  期間の開始日時（ISO 8601 形式。例：`2025-01-01T00:00:00Z`）。
</ParamField>

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

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

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

<ParamField query="per_page" type="number" default="20">
  1 ページあたりの件数。
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  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'
  ```

  ```json Response theme={null}
  {
    "total": 45,
    "page": 1,
    "limit": 20,
    "records": [
      {
        "uuid": "Q3NT0K80",
        "status": "received",
        "amount": 10000,
        "currency": "MYR",
        "created_at": "2025-01-15T10:30:00.000Z"
      }
    ]
  }
  ```
</CodeGroup>

***

## Cancel Payin

<Badge color="blue">POST</Badge> `/v2/payins/cancel`

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

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

<ParamField body="uuid" type="string" required>
  取り消す保留中の Payin の UUID。
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  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" }'
  ```

  ```json Response theme={null}
  {
    "uuid": "Q3NT0K80",
    "status": "expired",
    "message": "Payin cancelled successfully"
  }
  ```
</CodeGroup>

***

## Refund Payin

<Badge color="blue">POST</Badge> `/v2/payins/refund`

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

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

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

<ParamField body="uuid" type="string" required>
  返金する `received` の Payin の UUID。
</ParamField>

<ParamField body="description" type="string" required>
  返金の理由。5 文字以上である必要があります。
</ParamField>

<ParamField body="amount" type="number">
  返金する金額。省略した場合は全額が返金されます。一部返金は Payin の完了から 30〜60 分後にのみ可能です。
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  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"
    }'
  ```

  ```json Response theme={null}
  {
    "uuid": "Q3NT0K80",
    "refund_status": "return_pending",
    "refund_amount": 5000,
    "message": "Refund initiated"
  }
  ```
</CodeGroup>

***

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

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

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

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

<ParamField body="uuid" type="string" required>
  模擬する保留中の Payin の UUID。
</ParamField>

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

<ParamField body="amount" type="number">
  支払済みとして模擬する金額。既定では Payin の全額です。
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  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" }'
  ```

  ```json Response theme={null}
  {
    "uuid": "Q3NT0K80",
    "status": "received",
    "message": "Payin simulation successful"
  }
  ```
</CodeGroup>

***

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

<Badge color="blue">POST</Badge> `/v2/payins/confirm_otp`

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

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

<ParamField body="uuid" type="string" required>
  OTP のオーソリを待っている Payin の UUID。
</ParamField>

<ParamField body="code" type="string" required>
  顧客の電話で受け取った OTP。
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  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" }'
  ```

  ```json Response theme={null}
  {
    "uuid": "Q3NT0K80",
    "status": "pending",
    "message": "OTP verified. STK push sent to customer."
  }
  ```
</CodeGroup>

***

## OTP の再送信

<Badge color="blue">POST</Badge> `/v2/payins/resend_otp`

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

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

<ParamField body="uuid" type="string" required>
  OTP を再送信する Payin の UUID。
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  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" }'
  ```

  ```json Response theme={null}
  {
    "uuid": "Q3NT0K80",
    "message": "OTP resent successfully"
  }
  ```
</CodeGroup>


## Related topics

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