支付网关指南
面向旅游预订网站的Razorpay API 集成
Razorpay 是印度的支付网关，支持以卢比收取银行卡、UPI、网银和电子钱包付款。本指南讲解 Razorpay 支付在机票、酒店或旅游产品预订中如何流转，并如实说明它在 PHPTRAVELS 中的现状：Razorpay 目前不是现成的连接器，但可以在您拥有的源代码上作为自定义集成添加。
- 银行卡、UPI、网银、电子钱包
- 订单、Checkout、扣款
- 签名与 Webhook 校验
- 全额与部分退款
Razorpay 概览
Razorpay 是什么，在 PHPTRAVELS 中处于什么位置
Razorpay 是一家印度支付网关。面向印度客户销售的旅游企业用它在结账时提供当地客户习惯的付款方式：借记卡和信用卡、UPI、网银以及常用电子钱包，款项全部以印度卢比收取，并结算到商户自己的 Razorpay 账户。
PHPTRAVELS 是一个自托管的旅游预订平台，附带完整源代码。它的现成支付网关来自一份实时列表，您用自己的商户凭据即可启用。Razorpay 目前不在该列表中，因此后台暂时没有它的开关。
这并不意味着不能使用。由于代码归您所有，Razorpay 可以作为定制API集成添加；在印度，已有现成可用的网关：Cashfree。支付网关集成页面列出了所有现在就能启用的网关。
Razorpay 概况表
- 简介
- 面向印度企业的支付网关
- 支付方式
- 银行卡、UPI、网银和电子钱包
- 币种
- 以 INR 收款和结算；金额以 paise 为单位传送
- API 密钥
- Key ID 和 Key Secret，测试模式与正式模式各有一套
- PHPTRAVELS 现状
- 不是现成连接器。可在随附源代码上作为自定义集成添加
- 印度现成可用
- Cashfree，使用您自己的 Cashfree 账户在后台启用
支付流程
一笔旅游预订的 Razorpay 支付，逐步拆解
Razorpay 集成把工作分给旅客的浏览器和您的服务器。浏览器负责展示 Checkout；服务器负责创建订单、核对结果，并决定何时确认预订。
- 01
您的服务器
创建订单
旅客点击支付后，您的服务器调用 Orders API，传入以 paise 计的金额、币种，以及设为预订编号的 receipt。Razorpay 返回 order_id。
- 02
浏览器
打开 Razorpay Checkout
预订页面使用您的 Key ID 和该 order_id 打开 Checkout，旅客支付的正是服务器确定的金额。
- 03
浏览器
旅客付款
旅客选择银行卡、UPI、网银或电子钱包，并完成银行要求的验证步骤。此时付款已获授权。
- 04
浏览器
Checkout 返回三个值
支付成功后，Checkout 返回 razorpay_payment_id、razorpay_order_id 和 razorpay_signature，页面再将它们提交到您的服务器。
- 05
您的服务器
校验签名
您的服务器用 Key Secret 对 order_id 和 payment_id 重新计算签名。只有签名一致，才视为真实付款。
- 06
您的服务器
扣款
自动扣款由 Razorpay 代为完成。手动扣款则在航司、酒店或旅游供应商确认后由您的服务器扣款，这样预订失败时不会向任何人收费。
- 07
您的服务器
确认预订
预订状态变为已支付，机票或凭证随之出具，Razorpay 的 payment_id 与预订编号一并保存。
- 08
您的服务器服务器之间
接收 Webhook
Razorpay 还会把 payment.captured 等事件推送到您的 Webhook 地址，覆盖旅客在页面回报结果前就关闭标签页的情况。
签名与 Webhook
保证 Razorpay 集成可靠的两项校验
任何来自浏览器或互联网的数据都可能被伪造。Razorpay 集成只有在核对过由服务器私有密钥生成的签名之后，才会信任一笔付款。
1// 1. After Checkout: verify the payment signature 2$orderId = $booking["razorpay_order_id"]; // from your own record 3$paymentId = $_POST["razorpay_payment_id"]; 4$signature = $_POST["razorpay_signature"]; 5$expected = hash_hmac("sha256", $orderId . "|" . $paymentId, $keySecret); 6if (!hash_equals($expected, $signature)) { rejectPayment(); } 7markPaid($booking["ref"], $paymentId); 8 9// 2. Webhook: verify X-Razorpay-Signature over the raw body10$body = file_get_contents("php://input");11$header = $_SERVER["HTTP_X_RAZORPAY_SIGNATURE"] ?? "";12$expect = hash_hmac("sha256", $body, $webhookSecret);13if (!hash_equals($expect, $header)) { http_response_code(400); exit; }14$event = json_decode($body, true);15if (alreadyHandled($event)) exit; // repeat delivery16switch ($event["event"]) {17 case "payment.captured": confirmBooking($event); break;18 case "refund.processed": markRefunded($event); break;19}
仅为说明逻辑的示意伪代码，不是可直接使用的文件。具体调用请遵循 Razorpay 官方文档和 SDK。
付款签名
以 Key Secret 为密钥，对 order_id、竖线和 payment_id 做 HMAC SHA256，结果必须等于 razorpay_signature。请使用恒定时间函数进行比较。
Webhook 签名
每个 Webhook 都带有 X-Razorpay-Signature 请求头：以您在 Razorpay 控制台设置的 Webhook 密钥为密钥，对原始请求体做 HMAC SHA256。
重复推送
Webhook 可能重复到达，也可能乱序到达。请记录事件 ID 和付款 ID，并忽略已经应用到预订上的事件。
密钥只留在服务器端
只有 Key ID 会发给浏览器。Key Secret 和 Webhook 密钥保存在服务器配置中，绝不出现在页面源码或移动应用里。
退款与取消
旅游退款很少是全额
取消费、未到场规则以及部分取消的行程，使旅游退款往往是部分退款。Razorpay 的 Refunds API 两种情况都能处理，退款金额由集成按您的预订规则决定。
全额退款
免费取消时，已扣的全部金额会退回旅客当初付款所用的方式。
部分退款
扣除取消费后，服务器只退还余额。金额与原订单一样以 paise 为单位传送。
行程的一部分
取消一晚酒店或一位乘客，只退还对应部分；之后还可以继续部分退款，直至达到已扣总额。
refund.processed
退款 Webhook 会在退款完成时通知您的服务器，让预订和旅客看到正确的状态。
与预订一并保存
每个退款 ID 都与预订编号和原始 payment_id 一起保存，供财务团队查账。
示例：产生取消费的取消
- 已扣款
- ₹12,500.00 amount: 1250000
- 取消费
- ₹1,500.00 amount: 150000
- 退款金额
- ₹11,000.00 amount: 1100000
仅为示例数字。Razorpay 以最小货币单位计金额，100 paise 等于 1 卢比。
如何接入 Razorpay
三种收款方式，用 Razorpay 或不用都行
选择适合您团队和上线日期的路径。三种方式的资金都进入您自己的商户账户，PHPTRAVELS 不参与结算。
方案 1
由您的开发者添加
PHPTRAVELS 附带完整源代码，您自己的开发者可以在现有网关旁新增 Razorpay 网关，包括创建订单、支付步骤的 Checkout、签名校验、扣款、Webhook 和退款。
- 使用 Razorpay 测试模式密钥开发和测试
- 把预订编号复用为订单 receipt
- 测试预订通过后切换到正式密钥
方案 2
由 PHPTRAVELS 开发
我们的开发者可以作为定制API集成为您开发 Razorpay 连接器。您提交需求后，我们在动工前给出费用和工期，完成后交付经过测试的源代码。
- 动工前先报价
- 基于 Razorpay 测试模式开发
- 以您拥有的源代码交付
方案 3
立即使用现成网关
如果需要先上线，就启用平台中已有的网关。在印度可选 Cashfree。目前可用的现成网关包括：
- CashfreeCashfree 设置指南
- Stripe
- PayPal
- xMoney
- Fawaterk
- Paystack
现成网关
现在就能启用的支付网关
此列表实时取自 PHPTRAVELS 网关目录。每个网关都用您自己的账户和密钥在后台启用。
Cashfree
Stripe集成指南
PayPal集成指南
xMoney
Fawaterk
Paystack
Flutterwave
Adyen
MyFatoorah
SSLcommerz
Razorpay- 全部集成
想了解其中任何一个背后的调用？请阅读支付网关 API指南，对比Stripe付款和PayPal 支付指南，或了解代理商如何在 B2B 门户中通过B2B 代理钱包付款。
不是以现成连接器的形式。Razorpay 目前不在 PHPTRAVELS 的网关列表中，因此无法在后台直接启用。由于附带完整源代码，可以由您的开发者或我们的开发者将其作为自定义支付网关集成添加。
Cashfree 是 PHPTRAVELS 的现成网关，设置指南见 docs.phptravels.com/payments/cashfree。使用您自己的 Cashfree 账户在后台启用即可。Stripe、PayPal 等其他现成网关列在支付网关页面。
Razorpay 支持以印度卢比结算的银行卡、UPI、网银和电子钱包。结账时显示哪些方式，取决于您自己的 Razorpay 账户启用了什么。
Razorpay 以最小货币单位计金额，所以以卢比计的预订总额要乘以 100 再创建订单。退款金额也用同样方式传送。
Checkout 会返回付款 ID、订单 ID 和签名。您的服务器用 Key Secret 对订单 ID 和付款 ID 计算 HMAC SHA256，只有结果与签名一致才接受这笔付款。
自动扣款更简单。手动扣款则可以等航司、酒店或旅游供应商确认预订后再扣款，预订失败时直接释放即可，无需退款。具体取决于您的产品和供应商。
可以。Razorpay 的 Refunds API 支持全额和部分退款，因此可以保留取消费并退回余额。refund.processed Webhook 会在退款完成时通知您的服务器。
需要。商户账户、Key ID 和 Key Secret 以及结算都归您所有。PHPTRAVELS 从不提供网关凭据，也从不经手您的资金。请先用测试模式密钥开发，上线时再切换为正式密钥。
取决于您需要的范围，例如 Checkout、手动扣款、退款和代理商付款。PHPTRAVELS 在动工前会先为定制工作报价。平台本身为一次性买断授权，起。