Hello Clever Developer Docs

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 へお問い合わせください。

連携のモード

Payment Method

利用できる決済手段を自社の UI に直接表示します。Get Payin Methods を呼び出して顧客に選ばせ、選択された手段のコードを指定して Create Payin を実行します。顧客は Hello Clever のホスト型のページでチェックアウトを完了します。

Payment Link（Hello Clever ブランド）

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

Payment Link（自社ブランド）

決済のチェックアウトページに独自ドメインを使用します。ホワイトラベルのブランド表示の設定については support@helloclever.co へお問い合わせください。

ベース URL

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

認証

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

string

必須

Hello Clever の Merchant Dashboard から取得するアプリケーションの識別子です。

string

必須

クライアントのシークレットです。クライアントサイドのコードで決して露出させないでください。

手順に沿った連携ガイド

認証情報を設定する

Hello Clever アカウント内の各サイトには固有の app-id があります。認証情報を有効にするには、ダッシュボードでサイトの種別を Payment API に設定してください。複数の通貨で運用する場合は、通貨ごとに正しい app-id と secret-key を受け取るため、各サイトを個別に紐づけてください。Webhook Secret Key は加盟店レベルで発行され、同じ加盟店の下のすべてのサイトで共有されます。Hello Clever からのすべての Webhook の署名を検証するために使ってください。

利用できる決済手段を取得する（任意）

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

Example response

{
  "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 分）より小さくすることはできません。

Example request body

{
  "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 が含まれます。

Example response

{
  "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 モードを使う場合は、自社ドメインからのポップアップを許可するようユーザーへ案内してください。

Webhook を処理する

決済のステータスが変わるたびに、指定した endpoint_url へ POST の Webhook がサーバーに届きます。決済ステータスについては常に Webhook を正となる情報源として扱ってください。リダイレクト URL のパラメーターのみに依拠しないでください。Webhook のオブジェクトのスキーマ全体とステータスのリファレンスは Webhook を参照してください。

サンドボックスでテストする

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

作成後の決済の管理

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

リクエストとレスポンスのスキーマの全体は API リファレンスを参照してください。

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

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

Handle popup payment events

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 のデモサイトで確認できます。このデモでは、複数の通貨にわたってすべての連携モード（Payment Link、Payment Method、ポップアップ、リダイレクト）をテストできます。

基本

Payment Gateway (AUD)

Multi-Currency Payment API

Payment Gateway 3

Card API

Cashback API

Payment Gateway 3 API (v3)

対応通貨

連携のモード

Payment Method

Payment Link（Hello Clever ブランド）

Payment Link（自社ブランド）

ベース URL

認証

手順に沿った連携ガイド

リダイレクト URL

作成後の決済の管理

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

デモ

​対応通貨

​連携のモード

Payment Method

Payment Link（Hello Clever ブランド）

Payment Link（自社ブランド）

​ベース URL

​認証

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

​リダイレクト URL

​作成後の決済の管理

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

​デモ

対応通貨

連携のモード

ベース URL

認証

手順に沿った連携ガイド

リダイレクト URL

作成後の決済の管理

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

デモ