Payment Request APIは決済画面を出す前に注文の正本と支払い完了の確認を分ける

Payment Request APIは、web site、支払う人、支払い方法を提供する側の間で、browserが決済画面を仲介するためのAPIです。決済画面を表示できたことだけで、注文や支払いが完了したとは判断しません。商品、金額、注文番号、支払いの確認、在庫の扱い、失敗時の案内は、site側とpayment provider側で別に確かめる必要があります。最初に注文の正本をどこへ残すかを決めます。

W3CのPayment Request APIは、merchant、payer、payment method providerの間をuser agentが仲介する仕組みとして定義しています。API自体は新しい支払い方法を作るものでも、payment processorへ直接接続するものでもありません。browserの画面から受け取った情報を、どのproviderへ渡し、どの結果で注文を確定するかは、shop側が設計します。

決済画面の表示と注文確定を分ける

購入buttonを押すと決済画面が出たとしても、order recordを作る時点は別に決めます。注文番号を先に発行するのか、支払いの確認後に発行するのか、仮の注文として保存するのかで、在庫や連絡mailの扱いが変わります。画面に表示する注文内容と、serverへ保存する正本のorder dataを同じものとして扱いません。

説明用の仮例として、一点物を販売するshopを考えます。購入者が商品と送料を確認し、Payment Request APIの画面で支払い方法を選びます。この画面が開いた段階で在庫を永久に減らすと、途中で支払いを取りやめた場合に扱いが難しくなります。反対に、支払いが確認できたあとまで何も記録しなければ、重複した購入要求を調べにくくなります。どの段階を仮注文、確定注文、支払い済みと呼ぶかを先に書きます。

purchase buttonを連続して押された場合や、networkが途中で切れた場合も考えます。同じ注文を二度保存しないための識別子、購入者へ表示する案内、管理者が確認する一覧を分けます。buttonを一度押せないようにする表示は助けになりますが、それだけでserver側の重複を防ぐ仕組みにはなりません。

金額も、browserで表示した値だけを信じません。商品価格、送料、割引、税の扱いをsite側で確認し、providerへ渡す値とorder recordへ残す値をそろえます。JavaScriptで画面の金額を替えられることと、正しい請求額を決められることは別です。価格を決める正本はserver側へ残します。

APIとpayment providerの仕事を分ける

Payment Request APIは、payment method providerを選ぶ画面をbrowserが扱うための枠組みです。card informationの処理、入金の確認、取消、返金、請求書の発行までをAPIが代わりに行うとは限りません。どのproviderを使い、どの管理画面で支払いを確認し、誰が顧客へ連絡するかを決めます。

payment providerから受け取る結果と、購入者のbrowserへ返す画面も分けます。browserで成功のように見えても、provider側の確認が終わっていない場合があります。反対に、browserが途中で閉じても、provider側で支払いが進んでいる場合があります。成功画面を出す条件と、管理者が発送を始める条件を同じにしません。

仮に、支払いの確認を外部serviceからの通知で受けるshopなら、通知を受けるURL、通知の内容を検証する処理、order recordを更新する人を決めます。購入者がreturn pageへ戻ることを、入金確認の唯一の根拠にしません。外部serviceの画面を見て手で確認する場合も、どの注文番号と照合するかを残します。

制作会社がPayment Request APIの画面を実装し、別の会社がpayment providerを設定することもあります。この場合、注文の正本がどこにあるか、providerのaccountを誰が管理するか、障害時の連絡先はcompany側で確認します。codeを納品してもらうことと、代金を受け取る仕組みの所有を渡すことは別です。

失敗と中断の案内を先に書く

Payment Request APIの仕様では、user agentの状態や対応するpayment handlerがない場合などに、requestが失敗することがあります。対応しないbrowserや支払い方法があることも前提にします。決済画面が出ない場合、別の支払い方法へ進めるのか、問い合わせてもらうのか、購入を受け付けないのかを決めます。

失敗したときに、購入者へ「注文を受け付けました」と表示してはいけません。注文が保存されたのか、支払いが始まっていないのか、もう一度試してよいのかを、状態に合わせて案内します。わからない場合は、注文番号や時刻を確認してもらい、company側が照合する方法を示します。

決済画面が出ている間にpageを移動したり、二つのtabで購入を始めたりする場合もあります。画面の操作を完璧に制限するより、order recordが二重にならないこと、購入者へ状態を誤って伝えないことを優先します。購入を受ける仕事と、見た目のbuttonを整える仕事を分けます。

公開前には、少額の検証用注文など、実際の手順を通して確認します。商品選択、金額表示、決済画面、provider側の記録、order record、購入者へのmail、管理者の確認画面を順に見ます。testと本番のaccount、注文data、通知先を混同しないようにします。試験を頼む人が、どこまで注文を取り消せるかも先に決めます。

最初の一手は、注文の状態を「未確定」「支払い確認待ち」「支払い済み」のように書き出すことです。各状態で、購入者へ何を表示し、管理者が何を確認し、在庫をどう扱うかを決めてから、Payment Request APIの画面を加えます。APIは注文管理の代わりではありません。