核心概念 - UQPAY Developer Docs

Payment Intent (PI)

Payment Intent 代表客户的一次付款意图。它是支付相关信息的主容器，在整个交易生命周期中维护支付的总体状态。它代表一次完整的收款意图，无论最终收款成功与否。

关键特性

唯一标识：每个 PI 拥有一个以 PI 开头的唯一 ID（例如 PI1234567890123456789）
订单信息：包含金额、币种、商户侧订单号等关键订单信息
过期机制：未完成时 30 分钟后自动过期
持久性：一经创建即持续存在，可用于多次 payment attempt
幂等性：确保每笔交易只扣款一次
状态跟踪：在整个支付过程中完整记录状态变更

Payment Intent 状态参考

状态	说明	后续动作	阶段	Webhook 事件
`REQUIRES_PAYMENT_METHOD`	创建后或支付尝试失败后的初始状态。等待携带支付方式的 confirm 请求。	使用支付方式调用 confirm	初始	`acquiring.payment_intent.created`
`REQUIRES_CUSTOMER_ACTION`	等待客户完成身份验证（3DS 验证、扫码等）。查看 `next_action` 了解具体指引。	等待客户完成 `next_action` 字段中指定的操作。	客户交互	`acquiring.payment_intent.requires_action`
`REQUIRES_CAPTURE`	授权成功，等待请款以完成支付。资金已授权但尚未结算。	调用 capture 接口（暂未开放）完成全额或部分请款	授权完成	-
`PENDING`	正在由支付渠道处理。无需进一步操作。	等待结果	处理中	-
`SUCCEEDED`	支付已成功完成。交易结束。	无需进一步操作	终态	`acquiring.payment_intent.succeeded`
`CANCELLED`	支付被商户取消，支付已关闭。	无需进一步操作	终态	`acquiring.cancel.succeeded`
`FAILED`	因错误或系统超时（30 分钟）导致支付失败。	无需进一步操作	终态	`acquiring.payment_intent.failed`

Payment Attempt (PA)

Payment Attempt 代表 Payment Intent 下的一次具体支付尝试。每个 PA 都包含该次尝试所使用的支付方式明细和处理结果。

关键特性

唯一标识：每个 PA 拥有一个以 PA 开头的唯一 ID（例如 PA1234567890123456789）
临时性：代表单次具体支付尝试
可重试：失败的尝试可以通过在同一 Payment Intent 下创建新的 payment attempt 来重试
详细信息：包含具体的支付明细，如所用支付方式、错误信息等

Payment Attempt 状态参考

状态	说明	阶段	Webhook 事件
`INITIATED`	根据初始请求已创建 payment attempt。	初始	`acquiring.payment_attempt.created`
`AUTHENTICATION_REDIRECTED`	等待客户完成身份验证（3DS 验证、扫码等）。	客户交互	-
`PENDING_AUTHORIZATION`	授权请求已受理，等待支付渠道的最终结果。	处理中	-
`AUTHORIZED`	授权成功。支付将自动或手动完成请款。	授权完成	-
`CAPTURE_REQUESTED`	请款请求已成功提交。支付视为已完成。	请款	`acquiring.payment_attempt.capture_requested`
`SETTLED`	UQPAY 已从支付渠道收到结算款。	结算	-
`SUCCEEDED`	UQPAY 已将资金结算到你的钱包。	终态	-
`CANCELLED`	payment attempt 已被取消。如有已授权资金，将退回给客户。	终态	`acquiring.payment_attempt.cancelled`
`EXPIRED`	payment attempt 未在允许的时间窗口内完成，已过期。	终态	`acquiring.payment_attempt.cancelled`
`FAILED`	payment attempt 失败。	终态	`acquiring.payment_attempt.failed`

支付流程

支付流程支持两种模式，适配不同的商户集成场景：

直接支付 —— 适用于下单时已经拿到支付方式信息的场景
延迟确认 —— 适用于下单之后才选择支付方式的场景，允许在支付确认前修改订单

快速开始 Direct API 集成