旅行向け決済API
旅行予約のための決済ゲートウェイAPI：チェックアウトから返金まで
決済ゲートウェイAPIは、予約サイトがカード情報に触れることなく旅行者の支払いを受け取るための仕組みです。このページでは、カード決済1件のAPI呼び出し、決済が移り変わるステータス、旅行の決済が一般の小売より難しい理由、そしてPHPTRAVELSが予約フローをお選びのゲートウェイにつなぐ方法を解説します。
- セッション、3-D Secure、売上確定
- すべての決済ステータス
- カード、ウォレット、銀行、掛け払い
- カード情報をサーバーに残さない
API呼び出しの仕組み
カード決済1件を呼び出しごとに見る
決済ゲートウェイAPIは、決済事業者が加盟店に公開するWebサービス群です。サーバーが金額と通貨を指定して決済の作成を依頼し、旅行者はゲートウェイ自身のフォームにカード情報を入力し、ゲートウェイがカードネットワークと発行銀行とやり取りします。サーバーがカード番号を目にすることはなく、受け取るのは決済IDとステータスだけです。
関係者は4者です。図では各者を列、各メッセージを番号付きの矢印で示しています。呼び名はゲートウェイごとに異なりますが（payment intent、session、order、charge）、流れは同じです。
破線の矢印はWebhookです。ゲートウェイが自らサーバーを呼び出すため、旅行者がブラウザを閉じても決済結果は予約に反映されます。各ステップをPHPTRAVELSの予約にどう結び付けるかは決済ゲートウェイ連携のページで説明しています。
- 旅行者
- 自社サイト
- ゲートウェイ
- カードネットワーク／銀行
01チェックアウト旅行者 自社サイト
旅行者が旅程を確認して「支払う」を押します。予約はサプライヤー側で保留中で、まだ確定していません。
02Payment IntentまたはSessionの作成自社サイト ゲートウェイ
サーバーがシークレットAPIキーを使い、金額、通貨、予約番号、冪等性キーを送信します。ゲートウェイは決済IDを返します。
03ホスト型フィールドまたはリダイレクトゲートウェイ 旅行者
カード入力フォームはゲートウェイが提供し、自社ページ内に埋め込むか専用ページで表示するため、カード情報はゲートウェイへ直接送られます。
043-D Secureカードネットワーク／銀行 旅行者
発行銀行が求めた場合、旅行者は銀行アプリまたはワンタイムコードで支払いを承認します。
05オーソリゲートウェイ カードネットワーク／銀行
ゲートウェイがカードネットワーク経由で、発行銀行に金額の承認を求めます。
06承認済み、与信枠を確保カードネットワーク／銀行 ゲートウェイ
発行銀行がカード上で金額を確保します。まだ資金は動いていません。
07サイトへ結果を返すゲートウェイ 自社サイト
旅行者は決済IDとともにサイトへ戻ります。サーバーがAPIからステータスを読み取り、サプライヤーに予約を確定させます。
08売上確定自社サイト ゲートウェイ
サプライヤーの確定後、サーバーが全額または一部の金額で売上を確定します。多くのゲートウェイでは即時の売上確定にも対応しています。
09Webhookゲートウェイ 自社サイトゲートウェイから自動送信
ゲートウェイが署名付きのイベント（売上確定、返金、チャージバックなど）をエンドポイントへ送信します。サーバーは署名を検証して予約を更新します。
決済ステータス
状態遷移で見る決済のライフサイクル
どのゲートウェイAPIも、決済ごとにステータスを返します。呼び名は異なっても、ごく少数の状態に対応させることができ、予約ロジックはそれぞれに反応する必要があります。
created
作成済み
金額と通貨を指定した決済が作られ、旅行者の操作を待っています。
failed最終
失敗
拒否された、3-D Secureが完了しなかった、または中断されました。請求は発生しません。
authorized
オーソリ済み
発行銀行が金額を承認し、カード上で確保しています。
voided最終
取消済み
売上確定前に与信を取り消すため、旅行者に請求されることはありません。
captured
売上確定済み
代金が確定し、加盟店口座へ精算されます。
partially_refunded最終
一部返金済み
売上確定した金額の一部を返金します。たとえばキャンセル料を差し引く場合です。
refunded最終
返金済み
売上確定した金額の全額がカードに戻されます。
オーソリの有効期間は無期限ではありません。期限内に売上確定しなければ与信は失効し、銀行が金額を解放します。一部返金済みの決済は、売上確定額に達するまでさらに返金できます。
旅行が難しい理由
旅行の決済が特別な理由
店舗は在庫のある商品を売ります。旅行の販売者は、サプライヤーの確定がまだの予約に対して、出発の数か月前に代金を受け取ることもあります。決済APIはその事情に合っている必要があります。
01
先にオーソリ、後で売上確定
リクエスト制のホテル、団体運賃、ツアーは、注文から数時間から数日後に確定します。先にオーソリして確定時に売上を立てれば、成立しなかった予約に請求することはありません。
02
サプライヤーに断られることもある
決済から発券までの間に運賃が売り切れることがあります。オーソリ段階なら取消で与信を解放でき、売上確定後は返金になります。
03
キャンセル料を引いた一部返金
宿泊や航空券のキャンセルでは通常、手数料が残ります。返金の呼び出しで元の決済に対して少ない金額を、規定が求める回数だけ返せます。
04
多通貨対応
旅行者は自国通貨で支払い、サプライヤーは自社通貨で請求します。ゲートウェイは表示通貨に対応し、記録には両方の金額を残す必要があります。
05
高額取引の不正チェック
明日出発の航空券、他人のための購入、初めて使うカードでの支払いは、典型的な不正パターンです。3-D Secure、ゲートウェイのリスクスコア、手動審査キューが高額注文を守ります。
06
数か月後のチャージバック
異議申し立ては旅行後に届くことがよくあります。認証結果、予約書類、ゲートウェイのイベントをまとめて保管しておけば、証拠を添えて反論できます。
決済手段
決済ゲートウェイAPIが対応する支払い方法
カードは選択肢のひとつにすぎません。旅行者とエージェントの支払い方法は異なり、返金の方法もそれぞれ違います。
| 決済手段 | 内容 | 入金のタイミング | 返金 |
|---|---|---|---|
| カード | ゲートウェイ経由のデビットカードとクレジットカード。発行銀行が求める場合は3-D Secureを使います。 | チェックアウト時にオーソリし、即時またはサプライヤーの確定時に売上確定します。 | APIで同じカードへ全額または一部を返金します。 |
| デジタルウォレット | ゲートウェイが対応するPayPalや、トークン化したカードを持つスマホウォレットなどのウォレットです。 | チェックアウト時、旅行者がウォレットで承認した後です。 | ゲートウェイ経由で、ウォレットまたはその元のカードへ戻します。 |
| 銀行振込 | 旅行者またはエージェントが御社の銀行口座へ送金し、その入金を予約に紐付けて記録します。 | 数日後。スタッフが入金を確認するまで予約は待機します。 | ゲートウェイを介さず、振込で返金します。 |
| 後払い | 予約は今行い、支払いは後です。入金があった時点でスタッフが記録します。 | 予約後、旅行者が支払ったときです。 | 実際に支払われた分だけを返します。 |
| B2Bエージェントのウォレットまたは与信 | サブエージェントは、事前にチャージした残高、または御社が付与した与信枠から支払います。 | 予約時に差し引かれ、デポジットと与信は御社の条件で精算します。 | エージェントの残高に戻します。 |
銀行振込、後払い、ウォレット残高はプラットフォーム自体の精算方法であり、ゲートウェイではありません。エージェント残高と与信枠はB2B エージェントウォレットのページで、銀行決済は銀行振込決済のページで解説しています。
PHPTRAVELSで導入済み
接続済みの決済ゲートウェイAPI
以下のゲートウェイはPHPTRAVELSに接続済みです。決済事業者で加盟店アカウントを開設し、管理画面にAPIキーを入力し、サンドボックスでテストして本番へ移行します。一覧は連携ディレクトリの最新情報です。
Stripe連携ガイド
PayPal連携ガイド
xMoney
Fawaterk
Cashfree
Paystack
Flutterwave
Adyen
MyFatoorah
SSLcommerz
Razorpay- すべての決済連携
手数料と加盟店審査は決済事業者との間で決まり、PHPTRAVELSは関与しません。ここにないゲートウェイはカスタムAPI連携として追加でき、各ゲートウェイの設定方法は決済ゲートウェイ連携のページで説明しています。
セキュリティ
カード情報を自社システムに入れない
最も安全なカード番号は、サーバーが一度も受け取らないカード番号です。決済ゲートウェイAPIは、そのように設計されています。
カード番号を保存しない
カード情報はゲートウェイへ送られ、トークンまたは決済IDが返ります。データベースに保存するのはその参照情報だけで、カード番号やセキュリティコードは保存しません。
ホスト型フィールドとリダイレクトでPCI DSSの対象範囲を縮小
PCI DSSはカード情報を扱うすべての事業者に適用されます。カードフォームにゲートウェイ自身のページまたは埋め込みフィールドを使えば、対象となる自社システムの範囲はずっと小さくなります。どの自己問診票が該当するかは、アクワイアラにご確認ください。
署名で検証するWebhook
各Webhookには共有シークレットで作成した署名が付きます。サーバーが署名を再計算し、一致しないイベントを拒否するため、支払い済みの予約を偽装されることはありません。
シークレットキーはサーバーだけに置く
ブラウザに渡すのは公開可能キーだけです。決済や返金を作成するシークレットキーはサーバーの設定内に置き、各リクエストに冪等性キーを付けるため、再試行しても二重に請求されません。
1$payload = file_get_contents("php://input"); 2$signature = $_SERVER["HTTP_X_SIGNATURE"] ?? ""; 3$expected = hash_hmac("sha256", $payload, $webhookSecret); 4 5if (!hash_equals($expected, $signature)) { 6 http_response_code(400); exit; // reject 7} 8$event = json_decode($payload, true); 9if (alreadyHandled($event["id"])) exit; // repeat delivery10updateBooking($event["data"]["metadata"]["booking_ref"], $event["type"]);
一般的な例です。ヘッダー名や署名方式は、選択するゲートウェイによって異なります。
PHPTRAVELSはセルフホスト型ソフトウェアのため、PCI DSSへの準拠は、ソフトウェア単体ではなく、お客様の事業とサーバーを対象に評価されます。
決済事業者が提供するWebサービス群で、ウェブサイトがカード情報を自分で保存せずに、決済の作成、銀行への承認依頼、売上確定、返金、Webhookによるステータス通知を行えるようにするものです。
ゲートウェイはウェブサイトが直接やり取りする部分で、カード情報を安全に受け取って要求を中継します。プロセッサーは取引をカードネットワーク経由で発行銀行へ流します。多くの事業者は両方をひとつのサービスとして提供しています。
自社の事業を審査してくれ、顧客の国、通貨、決済手段に対応し、オーソリと売上確定を分けられ、一部返金もできるものです。グローバルなカードゲートウェイと地域のゲートウェイを併用する旅行会社も多くあります。
オーソリは旅行者のカード上で金額を確保すること、売上確定はそれを実際に引き落とすことです。2つを分ければ、サプライヤーが予約を確定してから請求でき、確定しなければ与信を取り消せます。
欧州経済領域や英国をはじめ多くの地域で、オンラインカード決済の大半に強力な顧客認証が求められ、カードはその要件を3-D Secureで満たします。認証のチャレンジはゲートウェイAPIが処理し、予約フローは結果を待ちます。
それだけではなりません。ゲートウェイのホスト型フィールドや決済ページを使えばカード情報がサーバーに入らず、PCI DSSの対象範囲は小さくなりますが、アクワイアラが求める評価は引き続き受ける必要があります。
ゲートウェイが一部返金に対応していれば可能で、ほとんどのカードゲートウェイは対応しています。元の決済に対して少ない金額、たとえば料金からキャンセル料を引いた額を返金します。
いいえ。お選びのゲートウェイで加盟店アカウントを開設し、手数料はその事業者と取り決めます。PHPTRAVELSは、管理画面に入力したAPIキーで予約プラットフォームをそのアカウントにつなぎます。
はい。APIが公開されているゲートウェイなら、カスタム連携として追加できます。ソースコードが付属するため、開発者が決済フローを拡張することも可能です。