> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helloclever.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Gateway 3 API

> Payment Gateway 3 では、1回の API 呼び出しでホスト型チェックアウトのリンクが返され、顧客がそこで支払いを完了することで、対応するあらゆる通貨を受け付けられます。

Payment Gateway 3 API は Unified Checkout とも呼ばれ、異なる通貨の顧客から決済を回収する方法を簡素化します。決済手段の UI、フォームの項目、チェックアウトページを自ら扱うのではなく、決済リンクを1つ作成すれば、Hello Clever のホスト型チェックアウトが残りを処理します。顧客にはその通貨に適した決済手段が表示され、支払いを完了すると、ステータスが変わったタイミングでサーバーが Webhook を受け取ります。

Payment Gateway 3 は、多通貨決済を最短で本番稼働させる方法です。導入は最小限で、フロントエンドの決済 UI を構築する必要がなく、対応するすべての通貨で一貫した挙動になります。

## 対応通貨と決済手段

Payment Gateway 3 は、Hello Clever の Merchant Dashboard に設定された通貨に対応します。最近追加された **NZD**、**HKD**、**MWK**、**TZS**、**UGX**、**KHQR USD** への対応も含みます。追加の通貨を有効にするには [support@helloclever.co](mailto:support@helloclever.co) へお問い合わせください。

通貨ごとに、独自の `payin_method_code` の値が用意されています。現在ゲートウェイが発行しているコードは次のとおりです。

| 通貨 | 決済手段（`payin_method_code`） |
| - | - |
| AUD | `au_card_aud`、`au_payid_npp_aud` |
| NZD | `nz_card_nzd` |
| HKD | `hk_card_hkd` |
| JPY | `jp_bank_jpy`、`jp_card_jpy` |
| USD | `us_card_usd`、`kh_pay_usd`（KHQR USD） |
| KRW | `kr_bank_krw` |
| INR | `in_upi_inr` |
| MYR | `my_bank_duitnow_myr`、`my_bank_fpx_myr`、`my_ewallet_touchngo_myr`、`my_ewallet_grabpay_myr`、`my_ewallet_boost_myr`、`my_ewallet_shopeepay_myr` |
| PHP | `ph_bank_php`、`ph_bank_maya_php`、`ph_ewallet_gcash_php`、`ph_qrph_php` |
| IDR | `id_bank_qris_idr`、`id_ewallet_dana_idr` |
| VND | `vn_vietqr_vnd`、`vn_other_vietqr_vnd`、`vn_ewallet_momo_vnd` |
| THB | `th_qrpay_thb` |
| CAD | `ca_interac_cad` |
| BRL | `br_pix_brl` |
| ZAR | `sa_eft_zar` |
| NGN | `ng_bank_ngn` |
| KES | `ke_mobile_money_kes` |
| GHS | `gh_mobile_money_ghs` |
| MWK | `mw_mobile_money_mwk`、`mw_bank_mwk` |
| BWP | `bw_bank_bwp`、`bw_mobile_money_bwp` |
| UGX | `ug_bank_ugx` |
| XAF | `cm_mobile_money_xaf` |
| XOF | `ci_mobile_money_xof` |

<Note>
  この表は全体像をつかむためのもので、設定内容そのものではありません。自社のアカウントで実際に有効になっている手段と、手段ごとの下限額と上限額、対応するカードブランド、利用できるチェックアウトの言語は、`GET /v3/payin_methods` を呼び出して確認してください。これらの上下限は通貨によって異なります。たとえば NZD と HKD のカード決済は上限が 10,000、MWK の手段は下限が 2,000 です。
</Note>

### モバイルマネー決済

モバイルマネーの手段（`ke_mobile_money_kes`、`mw_mobile_money_mwk`、`bw_mobile_money_bwp`、`gh_mobile_money_ghs`、`cm_mobile_money_xaf`、`ci_mobile_money_xof`）は、チェックアウトのページではなく顧客の端末に届くプロンプトで決済します。顧客が携帯番号を入力し、PIN または STK プッシュのプロンプトを受け取って承認し、ページ上で **I have paid** を選択して確定します。

ホスト型のチェックアウトには、市場ごとのネットワークの要件が表示されます。自社の案内に反映しておきたい点は次のとおりです。

* **通貨ごとに対応するネットワークが限られます。** MWK では Airtel と TNM の携帯番号のみが使えます。他のネットワークの番号では失敗します。
* **プロンプトには期限があります。** 顧客は速やかに応答する必要があります。プロンプトを放置したり閉じたりするとタイムアウトになり、保留ではなく失敗した決済として扱われます。
* **ウォレットに十分な残高が必要です。** 決済を開始する前に確認してください。
* **顧客はページを閉じたり再読み込みしたりしないでください。** プロンプトを承認し **I have paid** を選択するまでは、そのままにしておく必要があります。

<Warning>
  モバイルマネーの決済は、API から返金することも取り消すこともできません。Payin を作成する前に、金額を顧客と確認してください。
</Warning>

<Tip>
  各手段の分類ごとに顧客が実際に目にする画面については、[マルチ通貨のホスト型チェックアウトのガイド](/ja/platform-overview/customer-guides/multi-currency-checkout)を参照してください。自社のサポート資料を作成するときに役立ちます。
</Tip>

### 住所の収集

一部の手段では、決済を進める前に請求先の住所が必要です。ホスト型のチェックアウトでは、顧客の入力に応じて住所の欄が候補を補完し、実在する住所と照合して検証します。そのため、顧客は住所をすべて入力するのではなく、候補から選択します。

Payin を作成するときに `sender_info.address`、`city`、`postal_code`、`state`、`country_code` をあらかじめ設定できます。これらの値はフォームに引き継がれ、顧客は足りない部分だけを入力します。顧客が変更した内容には、引き続き検証が適用されます。

<Note>
  住所の自動補完は、住所を検証する手段での失敗を減らしますが、住所の要件そのものをなくすわけではありません。顧客の検証済みの住所をすでに保有している場合は、`sender_info` で渡して顧客の入力を減らしてください。
</Note>

## 連携のモード

<Columns cols={3}>
  <Card title="Payment Method" icon="credit-card">
    利用できる決済手段を自社の UI に直接表示します。Get Payin Methods を呼び出して顧客に選ばせ、選択された手段のコードを指定して Create Payin を実行します。顧客は Hello Clever のホスト型のページでチェックアウトを完了します。
  </Card>

  <Card title="Payment Link（Hello Clever ブランド）" icon="link">
    手段を指定せずに決済リンクを作成します。生成された `payment_url` へ顧客をリダイレクトすると、Hello Clever ブランドのチェックアウトページで利用できるすべての手段から選べます。
  </Card>

  <Card title="Payment Link（自社ブランド）" icon="building">
    決済のチェックアウトページに独自ドメインを使用します。ホワイトラベルのブランド表示の設定については [support@helloclever.co](mailto:support@helloclever.co) へお問い合わせください。
  </Card>
</Columns>

## ベース URL

| 環境 | ベース URL |
| - | - |
| サンドボックス | `https://api.cleverhub.co/api` |
| 本番環境 | `https://api-merchant.helloclever.co/api` |

## 認証

すべてのリクエストには、Hello Clever の他の API と同じ `app-id` と `secret-key` のヘッダーの組み合わせが必要です。

<ParamField header="app-id" type="string" required>
  Hello Clever の Merchant Dashboard から取得するアプリケーションの識別子です。
</ParamField>

<ParamField header="secret-key" type="string" required>
  クライアントのシークレットです。クライアントサイドのコードで決して露出させないでください。
</ParamField>

## 手順に沿った連携ガイド

<Steps>
  <Step title="認証情報を設定する">
    Hello Clever アカウント内の各サイトには固有の `app-id` があります。認証情報を有効にするには、ダッシュボードでサイトの種別を **Payment API** に設定してください。複数の通貨で運用する場合は、通貨ごとに正しい `app-id` と `secret-key` を受け取るため、各サイトを個別に紐づけてください。

    **Webhook Secret Key** は加盟店レベルで発行され、同じ加盟店の下のすべてのサイトで共有されます。Hello Clever からのすべての Webhook の署名を検証するために使ってください。
  </Step>

  <Step title="利用できる決済手段を取得する（任意）">
    `GET /v3/payin_methods` を呼び出して、設定した通貨の決済手段の一覧を取得します。Payin を作成する前に顧客に手段を選ばせたい場合は、これを自社のチェックアウト UI に直接表示できます。

    ```json Example response theme={null}
    {
      "records": [
        {
          "currency": "MYR",
          "payin_method_code": "my_bank_duitnow_myr",
          "payin_method_name": "DuitNow",
          "min_amount": 1,
          "max_amount": 9999999
        }
      ]
    }
    ```
  </Step>

  <Step title="決済リンクを作成する">
    取引の情報を指定して `POST /v3/payin_links` を呼び出します。`amount`、`description`、`sender_info` は必須です。顧客がすでに手段を選択している場合は `payin_method_code` を含めます。省略すると、Hello Clever のチェックアウトページで利用できるすべての手段が表示されます。`expires_in` は秒単位です。既定は 1800（30 分）で、900（15 分）より小さくすることはできません。

    ```json Example request body theme={null}
    {
      "amount": 10000,
      "payin_method_code": null,
      "description": "Order #5678",
      "expires_in": 1800,
      "redirect_url": {
        "success": "https://yoursite.com/success",
        "failure": "https://yoursite.com/failure"
      },
      "webhook_notification": {
        "authorization_header": "Bearer N234jkd85h2h3j4hj234difu892134jh",
        "endpoint_url": "https://yoursite.com/webhooks/payment"
      },
      "sender_info": {
        "email": "customer@example.com",
        "first_name": "Jane",
        "last_name": "Smith"
      }
    }
    ```

    レスポンスには、顧客をリダイレクトする先の `payment_url` が含まれます。

    ```json Example response theme={null}
    {
      "uuid": "Q3NT0K80",
      "payment_url": "https://paylink.cleverhub.co/UTNOVDBLODA",
      "expired_at": "2025-09-11T16:30:02.712Z"
    }
    ```

    #### リダイレクト URL

    チェックアウトの終了後に顧客が到達する先を制御するには `redirect_url` を使います。どちらの項目も任意で、片方だけを設定することもできます。

    | 項目 | 使われる場面 |
    | - | - |
    | `redirect_url.success` | 決済が成功した場合。自社の注文確認ページへ顧客を送ります。 |
    | `redirect_url.failure` | 決済が失敗、拒否、または失効した場合。顧客が再試行したり別の手段を選べる、自社が管理するページへ送ります。 |

    `redirect_url.failure` を省略すると、決済が失敗した後も顧客は Hello Clever のチェックアウトページに留まり、自社のチェックアウトの流れに戻る経路がなくなります。これを設定すれば、失敗した顧客を自社のファネル内に留められます。

    <Warning>
      成功 URL へのリダイレクトを決済の証拠として扱わないでください。決済が精算されていなくても顧客はその URL に到達し得ます。すべての決済は、正となる情報源である Webhook に照らして確認してください。
    </Warning>
  </Step>

  <Step title="顧客をリダイレクトする">
    顧客を `payment_url` へ送ります。製品に合った UX のモードを選んでください。

    * **リダイレクト**：同じタブまたは新しいタブで、顧客を決済の URL へ直接送ります。
    * **ポップアップ**：決済の URL をポップアップウィンドウ内に表示し、`window.addEventListener("message", ...)` で決済のイベントを受け取ります。

    <Note>
      一部のブラウザ（Safari、Chrome）は自動的なポップアップをブロックします。ポップアップの UX モードを使う場合は、自社ドメインからのポップアップを許可するようユーザーへ案内してください。
    </Note>
  </Step>

  <Step title="Webhook を処理する">
    決済のステータスが変わるたびに、指定した `endpoint_url` へ POST の Webhook がサーバーに届きます。決済ステータスについては常に Webhook を正となる情報源として扱ってください。リダイレクト URL のパラメーターのみに依拠しないでください。

    Webhook のオブジェクトのスキーマ全体は [Payment Gateway 3 のペイロード](/ja/api/webhooks#payment-gateway-3-payload)、ステータスのリファレンスは [Webhook](/ja/api/webhooks) を参照してください。Payment Gateway 3 は決済リンクのオブジェクトを送信します。ステータスは最上位ではなく `transaction_info.status` にあります。
  </Step>

  <Step title="サンドボックスでテストする">
    サンドボックス環境では、決済シミュレーターを使って実際の資金を動かさずにさまざまな決済の結果をテストできます。決済を作成した後、ホスト型チェックアウトのページで **「I have paid」** をクリックしてシミュレーターのポップアップを開き、必要に応じて成功または失敗のシナリオを実行してください。
  </Step>
</Steps>

## 作成後の決済の管理

| エンドポイント | 目的 |
| - | - |
| `GET /v3/payin_links` | Payin の一覧を取得します。消込のための絞り込みができます。 |
| `GET /v3/payin_links/{uuid}` | 個々の Payin の現在のステータスと詳細を取得します。 |
| `POST /v3/payin_links/refund` | 完了した Payin を返金します。 |

リクエストとレスポンスのスキーマの全体は [API リファレンス](/ja/api/overview)を参照してください。

## ポップアップ UX のイベント処理

チェックアウトをポップアップウィンドウに埋め込む場合は、決済のイベントを受け取ってポップアップを閉じ、UI を更新してください。

```javascript Handle popup payment events theme={null}
window.addEventListener("message", function (event) {
  if (
    !event.data?.hc_payment_event ||
    typeof event.data?.hc_payment_event !== "object"
  ) return;

  if (event.data.hc_payment_event.event_type === "onChange") {
    if (event.data.hc_payment_event.page_state === "success") {
      // Payment succeeded: close the popup and update your UI
      // window.location.href = event.data.hc_payment_event.redirect_url.success;
    }
    if (event.data.hc_payment_event.page_state === "failed") {
      // Payment failed: show an error message
      // window.location.href = event.data.hc_payment_event.redirect_url.failure;
    }
  }
});
```

`hc_payment_event` のオブジェクトには次が含まれます。

* `event_type`：`"onChange"`（ステータスが変わった）または `"onDone"`（顧客が Done をクリックした、またはカウントダウンがゼロになった）。
* `page_state`：`"success"` または `"failed"`。

<Warning>
  ポップアップのイベントリスナーは、即時のフィードバックで UX を改善する目的にのみ使ってください。決済ステータスについては常に Webhook を正式な根拠としてください。
</Warning>

## デモ

Payment Gateway 3 の動作は [Hello Clever のデモサイト](https://testing-minimoo.cleverpay.store/)で確認できます。このデモでは、複数の通貨にわたってすべての連携モード（Payment Link、Payment Method、ポップアップ、リダイレクト）をテストできます。


## Related topics

- [適切な Hello Clever の連携方法を選ぶ](/ja/integrations/choosing-integration.md)
- [業種別ユースケース](/ja/getting-started/industry-use-cases.md)
- [Create Payment Gateway Link](/api/payment-gateway/create-payment-gateway-link.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.