旅游支付 API
面向旅游预订的支付网关 API：从结账到退款
支付网关 API 让您的预订网站无需接触银行卡信息，就能收取旅客的款项。本页按调用顺序讲解一笔银行卡支付、支付会经历的各种状态、旅游支付为何比零售更复杂，以及 PHPTRAVELS 如何把您的预订流程接入所选的支付网关。
- 会话、3-D Secure、扣款
- 全部支付状态
- 银行卡、钱包、银行转账、挂账
- 服务器不存卡数据
调用如何运作
一笔银行卡支付，逐个调用来看
支付网关 API 是支付公司向商户开放的一组 Web 服务。您的服务器请求它按金额和币种创建一笔支付，旅客在网关自己的表单中输入银行卡信息，由网关与卡组织和发卡行通信。您的服务器始终看不到卡号，只会拿到支付 ID 和状态。
整个过程有四方参与。示意图把各方画成列，把每条消息画成带编号的箭头。不同网关的叫法各异（payment intent、session、order、charge），但流程是一样的。
虚线箭头代表 Webhook：网关会主动调用您的服务器，因此即使旅客关闭了浏览器，支付结果依然能更新到订单。每一步如何与 PHPTRAVELS 中的订单关联，请参阅支付网关集成页面。
- 旅客
- 您的网站
- 网关
- 卡组织 / 银行
01结账旅客 您的网站
旅客确认行程并点击支付。订单在供应商处保留，尚未确认。
02创建 Payment Intent 或会话您的网站 网关
您的服务器用密钥 API Key 发送金额、币种、订单号和幂等键，网关返回支付 ID。
03托管字段或跳转网关 旅客
银行卡表单由网关提供，嵌在您的页面内或使用网关独立页面，卡数据直接送到网关。
043-D Secure卡组织 / 银行 旅客
如果发卡行要求，旅客需在银行 App 中或用一次性验证码确认支付。
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 接收状态通知。
网关是您的网站直接对接的部分，负责安全地收集银行卡信息并转发请求。处理商则让交易经卡组织送达发卡行。许多服务商把两者合为一项服务提供。
能批准您的业务、支持客户所在国家、币种和支付方式，并提供预授权与扣款分离及部分退款的那一种。许多旅行社把全球银行卡网关与区域网关搭配使用。
预授权是在旅客卡上预留金额，扣款才是真正收钱。把两者分开，就可以在供应商确认订单后再收款，未确认时撤销冻结。
在包括欧洲经济区和英国在内的许多地区，大多数线上银行卡支付都需要强客户认证，银行卡靠 3-D Secure 来满足。验证环节由网关 API 处理，您的预订流程等待结果即可。
不会自动符合。使用网关的托管字段或支付页面能让卡数据不经过您的服务器、缩小 PCI DSS 范围，但仍需完成收单机构要求的评估。
可以，只要网关支持部分退款，大多数银行卡网关都支持。您针对原支付发起较低金额的退款，例如票价减去取消费。
不会。您需要在所选网关自行开通商户账户，并与其商定费率。PHPTRAVELS 通过您在后台填入的 API 密钥，把预订平台连接到该账户。
可以。任何有公开文档 API 的网关都能作为定制集成添加；由于包含源代码，您的开发人员也可以扩展支付流程。