跳转到内容

支付

网关状态特性
Airwallex生产(主网关)银行卡、微信支付、支付宝、3DS
Stripe生产(遗留)银行卡、Apple Pay、Google Pay、3DS
Mock测试模拟成功/失败
[payment]
default_gateway = "airwallex" # 或 "stripe" / "mock"
[payment.airwallex]
enabled = true
client_id = "..." # Airwallex 控制台 → API keys
api_key = "..." # Airwallex 控制台 → API keys
webhook_secret = "..." # 校验 webhook 签名
demo = true # true = 沙箱,false = 生产
[payment.stripe]
enabled = true
secret_key = "sk_..."
publishable_key = "pk_..."
  1. POST /checkout/complete —— 创建订单 + payment intent,返回 client_secret / payment_intent_id 和 airwallex_env 提示
  2. 客户端:用 client_secret 挂载 Airwallex Drop-in(或 Stripe Elements)
  3. 顾客输入支付信息并确认
  4. POST /checkout/confirm —— 服务端校验支付并完成订单

Airwallex 是生产环境的主网关。它用 client ID + API key 对认证, demo/prod API base 由 demo 配置项选择(或由 AIRWALLEX_USE_DEMO=1 环境变量选择)。

结账 summary 中的 airwallex_env 始终告知客户端 intent 创建于哪个 环境——店面的构建时 PUBLIC_AIRWALLEX_ENV 只在服务端未上报时作为 兜底。两者应保持一致(后端退出 demo 模式后把 PUBLIC_AIRWALLEX_ENV 设为 prod)。

从 CDN 加载 Drop-in SDK:

<script src="https://static.airwallex.com/components/sdk/v1/index.js"></script>
await AirwallexComponentsSDK.init({
env: summary.airwallex_env, // 'demo' 或 'prod'
enabledElements: ['payments'],
});
const dropIn = await AirwallexComponentsSDK.createElement('dropIn', {
client_secret: result.client_secret,
currency: 'USD',
intent_id: result.payment_intent_id,
});
dropIn.mount('airwallex-drop-in');
dropIn.on('success', () => { /* POST /checkout/confirm */ });

结算:Airwallex 按批次结算。费用、结算批次 ID 和汇率通过 POST /api/v1/accounting/sync-settlements 回填到支付记录上——见 会计导出参考。

Stripe Elements 集成仍可用。客户端把结账返回的 client_secret 传给 Stripe.js。

const stripe = await loadStripe(publishableKey);
const { error } = await stripe.confirmCardPayment(clientSecret, {
payment_method: { card: cardElement }
});
Terminal window
POST /api/v1/payments/:id/refund
{ "amount": 50.00, "reason": "Customer request" }

支持部分退款。退款通过原网关处理。

支付状态变化会触发 webhook:

  • payment.succeeded —— 支付确认
  • payment.failed —— 支付被拒绝
  • refund.succeeded —— 退款完成

在管理后台或 API 中配置 webhook 端点。使用 Airwallex 时,在 [payment.airwallex] 中设置 webhook secret 以便校验签名。