構築するもの
PayID 決済では、顧客が自身のバンキングアプリから New Payments Platform (NPP) 経由でリアルタイムに支払えます。決済リクエストを作成し、支払先の PayID を顧客に渡すと、資金が届いた瞬間に Hello Clever が通知します。カードもチャージバックもなく、精算はほぼ即時です。 2つのパターンを利用できます。ワンタイム PayID
取引ごとに新しい PayID を発行します。チェックアウトの注文などが該当します。
固定オープン PayID
顧客に紐づく永続的な PayID で、複数回または任意の金額の決済を受け付けます。継続的なトップアップ用のアドレスやウォレットの参照先などが該当します。
これは AUD 専用 (v1) の機能です。
事前準備
- 加盟店アカウントと
app-id/secret-key。 - サンドボックス
https://api.cleverhub.co、本番環境https://api-merchant.helloclever.co。 - 決済ステータスのコールバックを受ける Webhook のエンドポイント（TLS 1.2、公開、商用証明書）。
パターン A：単発の決済リクエスト
1
決済リクエストを作成する
create-payment-request を呼び出します。必須項目は レスポンスには、生成された
name、gst（ブール値。GST を課すオーストラリアの加盟店のみ true）、amount、description、emails（カンマ区切り、小文字のみ）、そして payment_request_notification の Webhook のブロック（endpoint_url と authorization_header）です。取引のステータスが変わるたびに、Hello Clever がこのエンドポイントを呼び出します。有用な任意項目は expired_at（UTC、15 分以上先）、external_id、metadata（任意のカスタムのキーバリューのオブジェクト。取引にそのまま返されます）です。prefix_static_payid は引き続き受け付けられますが、現在は非推奨です。新規の連携では指定しないでください。Create payment request
request_payid（顧客が支払う先の PayID）、total（金額と GST の合計）、expired_at、nonce、そして status: pending が含まれます。2
顧客に PayID を表示する
request_payid と正確な total を表示します。顧客はバンキングアプリを開いてその PayID へ支払い、送金が NPP 上で完了します。3
通知を受け取る、またはステータスを取得する
資金が届くと、Hello Clever が更新されたペイロード（
status: received、paid_at、cashback_amount、sender_details）を Webhook へ POST します。id と payid を指定して Get payment request status を呼び出すこともできます。決済リクエストのステータス
保留中のリクエストを取り消す
{ "payid": "abc.xyz@example.co" } を指定して cancel-a-payid を呼び出します。これにより PayID の登録が解除され、取引が expired として記録されます。
パターン B：固定オープン PayID
顧客に対して、継続的に決済を受け付ける恒久的な PayID を提供する場合に使用します。1
固定オープン PayID を作成する
create-static-open-payid を呼び出します。必須項目は
name、email、prefix_static_payid（3〜35 文字、小文字・数字・ドット）、そして customer_notification の Webhook のブロック（endpoint_url と authorization_header）です。任意項目は address、phone、city、zip_code、state、external_id です。レスポンスでは、永続的な static_payid と status: active が返されます。生成されるアドレスは prefix@example.com の形式です。入金があるたびに、決済のペイロード（金額、paid_at、sender_details、キャッシュバック）とともに Webhook が発火します。2
一覧を取得して照会する
list-static-open-payids を呼び出します。
email、payid、customer_id で絞り込みができ、ページ分割にも対応しています。照会と消込
- 期間内の決済リクエストの取得：
from_date/to_date（UTC、YYYY-MM-DDThh:mm:ssまたはDD/MM/YY）とpage（1 ページ 20 件）を指定します。対象期間は最大1年です。 - 決済リクエストの統計の取得：すべての決済リクエストの集計（総額、完了した取引件数、保留中の件数）を返します。
external_idと返されたnonceを使って、自社の記録と照合してください。
返金
refund-a-payment を呼び出します。payment_request_id、任意の refund_amount（既定では全額）、そして reason（5 文字以上）を指定します。返金用の PayID が生成されます。支払人へ返金できるよう、必要に応じて残高をトップアップしてください。進行状況は return_pending から return_received へと追跡できます。