Skip to main content

​
構築するもの

PayTo では、顧客が自身のバンキングアプリで一度承認するだけのデジタルな銀行承認型マンデート（「決済契約」）を設定できます。その後は、設定したスケジュールに沿って Hello Clever が自動的に資金を回収します（サブスクリプション、分割払い、住宅ローン、利用量に基づく請求など）。毎回顧客に確認を求める必要はありません。

決済契約

顧客が承認する継続的な授権です。誰が支払うか、どの方法か（PayID または BSB/口座番号）、1回あたりの上限、そして回収を駆動する頻度のパターンを定めます。
これは AUD 専用 (v1) の機能です。以下のエンドポイントは AUD Payment API を使用します。

​
事前準備

  • 加盟店アカウントと app-id / secret-key（Merchant Portal から取得）。
  • サンドボックスのエンドポイント https://api.cleverhub.co、本番環境 https://api-merchant.helloclever.co。
  • ステータスの変更を受け取る Webhook のエンドポイント（TLS 1.2、公開アクセス可能、商用発行の証明書）。

​
契約の種類と頻度

契約を作成する際に payment_agreement_type（例：MORTGAGE）と、次の4つの形のいずれかである agreement_details のブロックを設定します。
limit_amount は個々の回収の上限を定めます。Variable や Usage-based の契約では、想定される最大の請求額を賄える値を選んでください。

​
契約を設定して請求を始める

1

決済契約を作成する

一意の client_transaction_id、limit_amount、description（5〜140 文字）、agreement_details、payer_details、そして payment_agreement_notification（Webhook の認証ヘッダー）を指定して create-payment-agreement を呼び出します。payer details には、bank_account_details（BSB と口座番号）または pay_id_details（pay_id と pay_id_type。例：EMAIL）のいずれかを指定します。
Create agreement request
レスポンスでは Hello Clever の id と payment_agreement_id が返され、初期の status は created になります。
2

顧客の承認を待つ

顧客はバンキングアプリでマンデートを承認します。契約のステータスが変わると、Hello Clever が Webhook を呼び出します。請求は active の契約に対してのみ行ってください。
3

スケジュールに沿って請求させる

別途「引き落とし」や「請求」の呼び出しを行う必要はありません。契約が active のステータスに達すると、agreement_details で設定した frequency（例：MONTHLY、WEEKLY、FORTNIGHTLY）が自動的に回収を駆動します。Hello Clever が周期ごとに limit_amount の範囲内で決済を引き落とし、各回収のステータスが変わるたびに payment_agreement_notification の Webhook へ通知します。Fixed の契約では、limit_amount を毎周期に請求する予定の正確な金額に設定してください。Variable や Usage-based の契約で周期ごとに金額が変わる場合、または固定の周期の外で単発や ADHOC の請求を行う場合は、周期ごとの金額をどう送信するかを Hello Clever の連携担当者にご確認ください。この点は公開されている API リファレンスではまだ扱われていません。回収の消込には、専用の決済や開始の記録ではなく、Get payment agreement detail (/v1/pay_to/payment_agreement/detail) または Get payment agreements (/v1/pay_to/payment_agreement/search) を使ってください。
4

契約をライフサイクル全体で管理する

  • Amend (amend-payment-agreement)：プランが変わったときに limit_amount や agreement_details（頻度など）を変更します。Hello Clever の id、新しい limit_amount、agreement_details のブロック全体、そして payment_agreement_notification が必要です。1つの項目のみを変更する場合でも、これら4つはすべての呼び出しで必須です。
  • Change status (change-status)：status を active、suspended、cancelled に設定します。異議申立ての間に一時停止したり、解約時に取り消したりできます。
  • Get detail / Get list：契約の状態を消込します。期間で絞り込み、ページ分割にも対応しています。

​
サンドボックスのテスト用 PayID

サンドボックスで特定の契約の状態を発生させるには、次の支払人の PayID を使ってください。

​
Webhook の取り扱い

Webhook は冪等に実装してください。Hello Clever は同じペイロードを複数回配信することがあり、毎回 200 OK を期待します。200 以外のレスポンスは 15 分間隔で3回リトライされます。検証を強化するため、契約ごとに異なる authorization_header を使ってください。

関連トピック

Hello Clever 開発者ドキュメントHello Clever を始める継続的な決済向けの PayTo