> ## 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.
# Payment Gateway 3 API (v3)
> Hello Clever の v3 ゲートウェイでは、1回の API 呼び出しでホスト型チェックアウトのリンクが返され、顧客がそこで支払いを完了することで、対応するあらゆる通貨を受け付けられます。
Payment Gateway 3 API (v3) は Unified Checkout とも呼ばれ、異なる通貨の顧客から決済を回収する方法を簡素化します。決済手段の UI、フォームの項目、チェックアウトページを自ら扱うのではなく、決済リンクを1つ作成すれば、Hello Clever のホスト型チェックアウトが残りを処理します。顧客にはその通貨に適した決済手段が表示され、支払いを完了すると、ステータスが変わったタイミングでサーバーが Webhook を受け取ります。
v3 は、多通貨決済を最短で本番稼働させる方法です。導入は最小限で、フロントエンドの決済 UI を構築する必要がなく、対応するすべての通貨で一貫した挙動になります。
## 対応通貨
v3 ゲートウェイは、Hello Clever の Merchant Dashboard に設定された通貨に対応します。最近追加された **NZD**、**HKD**、**MWK**、**TZS** への対応も含みます。追加の通貨を有効にするには [support@helloclever.co](mailto:support@helloclever.co) へお問い合わせください。
## 連携のモード
利用できる決済手段を自社の UI に直接表示します。Get Payin Methods を呼び出して顧客に選ばせ、選択された手段のコードを指定して Create Payin を実行します。顧客は Hello Clever のホスト型のページでチェックアウトを完了します。
手段を指定せずに決済リンクを作成します。生成された `payment_url` へ顧客をリダイレクトすると、Hello Clever ブランドのチェックアウトページで利用できるすべての手段から選べます。
決済のチェックアウトページに独自ドメインを使用します。ホワイトラベルのブランド表示の設定については [support@helloclever.co](mailto:support@helloclever.co) へお問い合わせください。
## ベース URL
| 環境 | ベース URL |
| ------- | ----------------------------------------- |
| サンドボックス | `https://api.cleverhub.co/api` |
| 本番環境 | `https://api-merchant.helloclever.co/api` |
## 認証
v3 のすべてのリクエストには、v2 と同じ `app-id` と `secret-key` のヘッダーの組み合わせが必要です。
Hello Clever の Merchant Dashboard から取得するアプリケーションの識別子です。
クライアントのシークレットです。クライアントサイドのコードで決して露出させないでください。
## 手順に沿った連携ガイド
Hello Clever アカウント内の各サイトには固有の `app-id` があります。認証情報を有効にするには、ダッシュボードでサイトの種別を **Payment API** に設定してください。複数の通貨で運用する場合は、通貨ごとに正しい `app-id` と `secret-key` を受け取るため、各サイトを個別に紐づけてください。
**Webhook Secret Key** は加盟店レベルで発行され、同じ加盟店の下のすべてのサイトで共有されます。Hello Clever からのすべての Webhook の署名を検証するために使ってください。
`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
}
]
}
```
取引の情報を指定して `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 のチェックアウトページに留まり、自社のチェックアウトの流れに戻る経路がなくなります。これを設定すれば、失敗した顧客を自社のファネル内に留められます。
成功 URL へのリダイレクトを決済の証拠として扱わないでください。決済が精算されていなくても顧客はその URL に到達し得ます。すべての決済は、正となる情報源である Webhook に照らして確認してください。
顧客を `payment_url` へ送ります。製品に合った UX のモードを選んでください。
* **リダイレクト**：同じタブまたは新しいタブで、顧客を決済の URL へ直接送ります。
* **ポップアップ**：決済の URL をポップアップウィンドウ内に表示し、`window.addEventListener("message", ...)` で決済のイベントを受け取ります。
一部のブラウザ（Safari、Chrome）は自動的なポップアップをブロックします。ポップアップの UX モードを使う場合は、自社ドメインからのポップアップを許可するようユーザーへ案内してください。
決済のステータスが変わるたびに、指定した `endpoint_url` へ POST の Webhook がサーバーに届きます。決済ステータスについては常に Webhook を正となる情報源として扱ってください。リダイレクト URL のパラメーターのみに依拠しないでください。
Webhook のオブジェクトのスキーマ全体とステータスのリファレンスは [Webhook](/ja/api/webhooks) を参照してください。
サンドボックス環境では、決済シミュレーターを使って実際の資金を動かさずにさまざまな決済の結果をテストできます。決済を作成した後、ホスト型チェックアウトのページで **「I have paid」** をクリックしてシミュレーターのポップアップを開き、必要に応じて成功または失敗のシナリオを実行してください。
## 作成後の決済の管理
| エンドポイント | 目的 |
| ----------------------------- | -------------------------------- |
| `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"`。
ポップアップのイベントリスナーは、即時のフィードバックで UX を改善する目的にのみ使ってください。決済ステータスについては常に Webhook を正式な根拠としてください。
## デモ
v3 ゲートウェイの動作は [Hello Clever のデモサイト](https://testing-minimoo.cleverpay.store/)で確認できます。このデモでは、複数の通貨にわたってすべての連携モード（Payment Link、Payment Method、ポップアップ、リダイレクト）をテストできます。
## Related topics
- [List PayIns](/api/payin/list-payins.md)
- [Get PayIn methods](/api/payin/get-payin-methods.md)
- [Create Payment Gateway Link](/api/payment-gateway/create-payment-gateway-link.md)