3分钟看懂国际支付源码，拒绝官方文档长篇大论

官方文档往往厚达数百页，API 列表密密麻麻，新人一看就头晕，根本抓不住核心逻辑。很多开发者在对接国际支付时，陷入“看文档 -> 写代码 -> 报错 -> 再查文档”的死循环，效率极低。其实，剥离掉营销话术和冗余配置，国际支付的核心链路非常清晰，只需要通过图解原理拆解底层数据流，就能在 10 分钟内建立完整认知。

本文将结合 stripe-node 等 NPM/PyPI 官方包 的实际源码逻辑，带你穿透表象，直击支付网关的心脏。我们不讲空洞的理论，只讲代码里跑通的真相，帮你把复杂系统变成可控的黑盒。

入口定位：请求是如何进入支付大脑的

在深入源码之前，必须先明确一个概念：国际支付系统不是一个单体应用，而是一个分布式的状态机。当你点击“支付”按钮时，前端发起的 POST /createPaymentIntent 请求，实际上只是整个链路的冰山一角。

以业界标准的 stripe-node SDK 为例，其入口函数通常位于 StripeClient 类中。这个类充当了“指挥官”的角色，它负责鉴权、序列化请求、处理重试以及解析响应。

// 源码片段 1：StripeClient 核心请求处理逻辑 (简化版)
// 文件路径: lib/StripeClient.js (伪代码结构，基于真实 SDK 逻辑)class StripeClient {constructor(apiKey) {this._apiKey = apiKey; // 存储私钥，用于 HMAC 签名验证this._baseURL = 'https://api.stripe.com/v1'; // 官方网关地址}async request(method, path, params) {// 1. 构建完整 URLconst url = `${this._baseURL}${path}`;// 2. 准备请求头，Authorization 是核心const headers = {'Content-Type': 'application/x-www-form-urlencoded','Authorization': `Bearer ${this._apiKey}`};// 3. 参数序列化，注意：Stripe 后端要求表单格式而非 JSONconst body = this._serialize(params); try {// 4. 发起 HTTP 请求，这里通常包裹了 fetch 或 axiosconst response = await fetch(url, {method,headers,body,});// 5. 解析响应 JSONconst data = await response.json();// 6. 错误拦截：非 2xx 状态码抛出特定异常if (!response.ok) {throw new StripeError(data.error.message, response.status);}return data;} catch (error) {// 7. 网络层重试逻辑（指数退避策略）if (error instanceof NetworkError && this._retryCount < 3) {return this._retryRequest(method, path, params);}throw error;}}
}

逐行解析：

constructor: 初始化时绑定 API Key，这是身份验证的基石。
request: 这是所有 SDK 调用的统一出口。注意 Content-Type 是 form-urlencoded，这是 Stripe 早期为了兼容各种后端语言做出的妥协，也是很多初学者容易踩的坑（以为要传 JSON）。
_serialize: 将嵌套对象扁平化。例如 { card: { number: '4242...' } } 会变成 card[number]=4242...。
retry: 支付系统必须高可用，网络抖动是常态，SDK 内置的重试机制保证了最终一致性。

理解了这个入口，你就知道，所谓的“调用支付接口”，本质上就是一个带有鉴权头的 HTTP POST 请求，返回的是一个包含状态信息的 JSON 对象。

核心片段：PaymentIntent 的状态流转

国际支付最核心的概念是 PaymentIntent（支付意图）。它不仅仅是一个订单，更是一个状态容器，记录了从“创建”到“成功/失败”的全过程。

在源码层面，PaymentIntent 的创建与更新是分步进行的。让我们看看当用户输入卡号后，后端代码是如何驱动状态变化的。

# 源码片段 2：PaymentIntent 状态机处理 (Python 示例，逻辑同构)
# 依赖包: stripe-python (PyPI 官方包)import stripedef process_payment(customer_id, amount, currency='usd'):"""处理支付流程的核心函数"""# 1. 创建 PaymentIntent# 注意: capture_method='automatic' 表示扣款成功后自动捕获资金intent = stripe.PaymentIntent.create(amount=amount,currency=currency,customer=customer_id,automatic_payment_methods={'enabled': True},metadata={'order_id': 'ORD_12345'})# 2. 获取 Client Secret，用于前端唤起收银台# 这是一个一次性令牌，前端用它来与 Stripe.js 交互client_secret = intent['client_secret']# 3. 模拟前端支付回调 (Webhook)# 实际生产中，这是通过 Webhook 事件触发的异步处理# 假设前端支付成功，Stripe 会发送 payment_intent.succeeded 事件if intent['status'] == 'requires_payment_method':# 状态 1: 需要用户提供支付方式# 此时资金未冻结，仅建立了意向print("等待前端提交卡号信息...")elif intent['status'] == 'requires_confirmation':# 状态 2: 支付方式已提交，等待银行授权# 此时可能触发 3DS 验证print("正在与发卡行通信，验证 3DS...")elif intent['status'] == 'requires_capture':# 状态 3: 授权成功，资金已冻结，等待商户捕获# 适用于预付卡或需要延迟结算的场景print("授权成功，正在捕获资金...")# 手动捕获资金stripe.PaymentIntent.confirm(intent['id'])elif intent['status'] == 'succeeded':# 状态 4: 支付完成，资金已入账print("支付成功！更新本地订单状态...")return {'success': True, 'transaction_id': intent['id']}else:# 状态 5: 失败print("支付失败: ", intent['last_payment_error'])return {'success': False}return {'success': False, 'client_secret': client_secret}

逐行解析：

PaymentIntent.create: 这一步只是“预约”。此时没有任何资金移动，只是告诉 Stripe：“我要收这么多钱，给这个客户”。
client_secret: 这是一个安全设计。前端不需要知道 API Key，只需要拿着这个 secret 去和 Stripe 的 JS SDK 交互，由浏览器端完成卡号收集。
status 字段: 这是整个系统的灵魂。requires_payment_method 到 succeeded 的每一步流转，都对应着银行侧的一次交互。
metadata: 用于关联本地业务数据。当 Webhook 回调时，你通过这个字段找回你的本地订单 ID。

图解原理： 想象一个漏斗：

顶部：用户点击支付，创建 Intent（漏斗口）。
中部：卡号传输，3DS 验证（漏斗颈，最容易卡住的地方）。
底部：银行授权，资金捕获（漏斗底，出水口）。

如果中间任何环节断开（如用户关闭浏览器、银行拒绝），状态就会停留在 requires_confirmation 或变为 canceled，这就是为什么你需要处理 Webhook 来同步最终状态的原因。

设计思想：为什么是异步 Webhook 而不是同步返回？

很多初学者疑惑：既然 confirm 之后有状态，为什么还要监听 Webhook？直接同步返回结果不行吗？

答案在于解耦与最终一致性。

网络不可靠：支付请求涉及多个第三方（你的服务器、Stripe 服务器、发卡行、收单行）。任何一个节点超时，同步响应都可能丢失。
耗时差异：支付授权可能瞬间完成，也可能需要 30 秒进行 3DS 挑战。如果同步等待，用户体验极差。
状态同步：Webhook 是 Stripe 主动推送的“真相”。无论前端页面是否关闭，无论网络是否中断，Stripe 都会确保 Webhook 事件最终送达你的服务器。

源码中的 Webhook 验证逻辑：

// 源码片段 3：Webhook 签名验证 (安全核心)const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), (req, res) => {let event;try {// 1. 验证签名，防止伪造请求// 必须使用原始 body (raw)，不能是 JSON 解析后的对象event = stripe.webhooks.constructEvent(req.body, req.headers['stripe-signature'], process.env.STRIPE_WEBHOOK_SECRET);} catch (err) {// 签名验证失败，直接拒绝console.log(`Webhook signature verification failed.`);res.sendStatus(400);return;}// 2. 事件路由switch (event.type) {case 'payment_intent.succeeded':const paymentIntent = event.data.object;// 执行本地业务逻辑：发货、更新数据库handlePaymentSuccess(paymentIntent);break;case 'payment_intent.payment_failed':const failedIntent = event.data.object;// 执行失败逻辑：记录日志、通知用户handlePaymentFailure(failedIntent);break;}// 3. 快速响应，避免 Stripe 认为你超时并重试res.json({ received: true });
});

设计精髓：

express.raw: 必须使用原始字节流进行签名验证。如果先 JSON.parse，哈希值就会改变，导致验证失败。这是最经典的坑。
幂等性: Webhook 可能会重试。你的 handlePaymentSuccess 必须设计成幂等的（即执行多次效果相同），避免重复发货。
快速 ACK: 验证通过后立即返回 200，耗时操作放入消息队列（如 Redis/RabbitMQ）异步处理。

手写简化版：构建一个迷你支付网关

为了彻底吃透原理，我们手写一个极简版的支付网关，模拟 Stripe 的核心流程。

场景： 用户购买一个 $10.00 的商品。

1. 定义数据模型

# models.py
from enum import Enumclass PaymentStatus(Enum):REQUIRES_PAYMENT_METHOD = "requires_payment_method"REQUIRES_CAPTURE = "requires_capture"SUCCEEDED = "succeeded"FAILED = "failed"class PaymentIntent:def __init__(self, amount, currency, customer_id):self.id = f"pi_{generate_uuid()}"self.amount = amountself.currency = currencyself.customer_id = customer_idself.status = PaymentStatus.REQUIRES_PAYMENT_METHOD.valueself.last_error = None

2. 模拟支付处理引擎

# engine.py
import random
from models import PaymentIntent, PaymentStatusclass PaymentEngine:def create_intent(self, amount, currency, customer_id):return PaymentIntent(amount, currency, customer_id)def confirm_payment(self, intent_id, card_token):intent = self.get_intent(intent_id)# 1. 状态检查：是否已经成功或失败？if intent.status in [PaymentStatus.SUCCEEDED.value, PaymentStatus.FAILED.value]:raise Exception("Payment already processed")# 2. 模拟银行交互 (3DS Verification)# 假设 10% 概率失败if random.random() < 0.1:intent.status = PaymentStatus.FAILED.valueintent.last_error = "Card declined by issuer"return intent# 3. 模拟授权成功intent.status = PaymentStatus.REQUIRES_CAPTURE.value# 4. 模拟自动捕获 (Automatic Capture)intent.status = PaymentStatus.SUCCEEDED.valuereturn intent

3. 服务层 (API)

# api.py
from flask import Flask, request, jsonify
from engine import PaymentEngineapp = Flask(__name__)
engine = PaymentEngine()@app.route('/create', methods=['POST'])
def create_payment():data = request.jsonintent = engine.create_intent(amount=data['amount'],currency=data['currency'],customer_id=data['customer_id'])return jsonify({'id': intent.id,'client_secret': f"{intent.id}_secret_{random_string()}",'status': intent.status})@app.route('/confirm', methods=['POST'])
def confirm_payment():data = request.jsontry:intent = engine.confirm_payment(intent_id=data['id'],card_token=data['card_token'])# 模拟 Webhook 触发 (实际中是异步的)if intent.status == "succeeded":trigger_webhook('payment_intent.succeeded', intent)return jsonify({'status': intent.status})except Exception as e:return jsonify({'error': str(e)}), 400

这个简化版揭示了什么？

状态机是核心：所有逻辑都围绕 status 的流转。
Token 化：前端提交的是 card_token，而不是原始卡号。这是 PCI-DSS 合规的关键。
异步通知：trigger_webhook 解耦了支付处理与业务落地。

应用场景与避坑指南

理解了源码和设计思想，在实际项目中你会遇到以下典型场景：

多币种结算：
- 痛点：汇率波动导致金额不一致。
- 解法：在创建 PaymentIntent 时指定 currency，但金额需经过汇率转换。建议在本地数据库存储原始币种和金额，避免二次转换误差。
退款流程：
- 原理：退款也是一个状态机。Refund 对象关联 PaymentIntent。
- 代码：stripe.Refund.create({'payment_intent': intent_id, 'amount': refund_amount})。
- 注意：部分退款需记录剩余可退金额，防止超退。
Webhook 丢失处理：
- 痛点：网络故障导致 Webhook 未送达。
- 解法：实现对账机制。每天定时任务，拉取 Stripe 后台的交易列表，与本地数据库比对。对于状态不一致的记录，手动触发补偿逻辑。
日志与排查：
- 技巧：记录 Stripe-Request-Id 响应头。当出现问题时，拿着这个 ID 去 Stripe Dashboard 查询，能精确定位到每一次 API 调用的请求体和响应体。