対応通貨と決済手段
Payment Gateway 3 は、Hello Clever の Merchant Dashboard に設定された通貨に対応します。最近追加された NZD、HKD、MWK、TZS、KHQR USD への対応も含みます。追加の通貨を有効にするには support@helloclever.co へお問い合わせください。 通貨ごとに、独自のpayin_method_code の値が用意されています。現在ゲートウェイが発行しているコードは次のとおりです。
この表は全体像をつかむためのもので、設定内容そのものではありません。自社のアカウントで実際に有効になっている手段と、手段ごとの下限額と上限額、対応するカードブランド、利用できるチェックアウトの言語は、
GET /v3/payin_methods を呼び出して確認してください。これらの上下限は通貨によって異なります。たとえば NZD と HKD のカード決済は上限が 10,000、MWK の手段は下限が 2,000 です。モバイルマネー決済
モバイルマネーの手段（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 を選択するまでは、そのままにしておく必要があります。
住所の収集
一部の手段では、決済を進める前に請求先の住所が必要です。ホスト型のチェックアウトでは、顧客の入力に応じて住所の欄が候補を補完し、実在する住所と照合して検証します。そのため、顧客は住所をすべて入力するのではなく、候補から選択します。 Payin を作成するときにsender_info.address、city、postal_code、state、country_code をあらかじめ設定できます。これらの値はフォームに引き継がれ、顧客は足りない部分だけを入力します。顧客が変更した内容には、引き続き検証が適用されます。
住所の自動補完は、住所を検証する手段での失敗を減らしますが、住所の要件そのものをなくすわけではありません。顧客の検証済みの住所をすでに保有している場合は、
sender_info で渡して顧客の入力を減らしてください。連携のモード
Payment Method
利用できる決済手段を自社の UI に直接表示します。Get Payin Methods を呼び出して顧客に選ばせ、選択された手段のコードを指定して Create Payin を実行します。顧客は Hello Clever のホスト型のページでチェックアウトを完了します。
Payment Link（Hello Clever ブランド）
手段を指定せずに決済リンクを作成します。生成された
payment_url へ顧客をリダイレクトすると、Hello Clever ブランドのチェックアウトページで利用できるすべての手段から選べます。Payment Link（自社ブランド）
決済のチェックアウトページに独自ドメインを使用します。ホワイトラベルのブランド表示の設定については support@helloclever.co へお問い合わせください。
ベース URL
認証
すべてのリクエストには、Hello Clever の他の API と同じapp-id と secret-key のヘッダーの組み合わせが必要です。
string
必須
Hello Clever の Merchant Dashboard から取得するアプリケーションの識別子です。
string
必須
クライアントのシークレットです。クライアントサイドのコードで決して露出させないでください。
手順に沿った連携ガイド
1
認証情報を設定する
Hello Clever アカウント内の各サイトには固有の
app-id があります。認証情報を有効にするには、ダッシュボードでサイトの種別を Payment API に設定してください。複数の通貨で運用する場合は、通貨ごとに正しい app-id と secret-key を受け取るため、各サイトを個別に紐づけてください。Webhook Secret Key は加盟店レベルで発行され、同じ加盟店の下のすべてのサイトで共有されます。Hello Clever からのすべての Webhook の署名を検証するために使ってください。2
利用できる決済手段を取得する（任意）
GET /v3/payin_methods を呼び出して、設定した通貨の決済手段の一覧を取得します。Payin を作成する前に顧客に手段を選ばせたい場合は、これを自社のチェックアウト UI に直接表示できます。Example response
3
決済リンクを作成する
取引の情報を指定して レスポンスには、顧客をリダイレクトする先の
POST /v3/payin_links を呼び出します。amount、description、sender_info は必須です。顧客がすでに手段を選択している場合は payin_method_code を含めます。省略すると、Hello Clever のチェックアウトページで利用できるすべての手段が表示されます。expires_in は秒単位です。既定は 1800（30 分）で、900（15 分）より小さくすることはできません。Example request body
payment_url が含まれます。Example response
リダイレクト URL
チェックアウトの終了後に顧客が到達する先を制御するにはredirect_url を使います。どちらの項目も任意で、片方だけを設定することもできます。redirect_url.failure を省略すると、決済が失敗した後も顧客は Hello Clever のチェックアウトページに留まり、自社のチェックアウトの流れに戻る経路がなくなります。これを設定すれば、失敗した顧客を自社のファネル内に留められます。4
顧客をリダイレクトする
顧客を
payment_url へ送ります。製品に合った UX のモードを選んでください。- リダイレクト：同じタブまたは新しいタブで、顧客を決済の URL へ直接送ります。
- ポップアップ：決済の URL をポップアップウィンドウ内に表示し、
window.addEventListener("message", ...)で決済のイベントを受け取ります。
一部のブラウザ（Safari、Chrome）は自動的なポップアップをブロックします。ポップアップの UX モードを使う場合は、自社ドメインからのポップアップを許可するようユーザーへ案内してください。
5
Webhook を処理する
決済のステータスが変わるたびに、指定した
endpoint_url へ POST の Webhook がサーバーに届きます。決済ステータスについては常に Webhook を正となる情報源として扱ってください。リダイレクト URL のパラメーターのみに依拠しないでください。Webhook のオブジェクトのスキーマ全体は Payment Gateway 3 のペイロード、ステータスのリファレンスは Webhook を参照してください。Payment Gateway 3 は決済リンクのオブジェクトを送信します。ステータスは最上位ではなく transaction_info.status にあります。6
サンドボックスでテストする
サンドボックス環境では、決済シミュレーターを使って実際の資金を動かさずにさまざまな決済の結果をテストできます。決済を作成した後、ホスト型チェックアウトのページで 「I have paid」 をクリックしてシミュレーターのポップアップを開き、必要に応じて成功または失敗のシナリオを実行してください。
作成後の決済の管理
リクエストとレスポンスのスキーマの全体は API リファレンスを参照してください。
ポップアップ UX のイベント処理
チェックアウトをポップアップウィンドウに埋め込む場合は、決済のイベントを受け取ってポップアップを閉じ、UI を更新してください。Handle popup payment events
hc_payment_event のオブジェクトには次が含まれます。
event_type："onChange"（ステータスが変わった）または"onDone"（顧客が Done をクリックした、またはカウントダウンがゼロになった）。page_state："success"または"failed"。