> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 核心概念

> 了解 UQPAY 收单系统的核心构件 —— Payment Intent 和 Payment Attempt。

<h2 id="payment-intent-pi">Payment Intent (PI)</h2>

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

<h3 id="key-characteristics">关键特性</h3>

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

<h3 id="payment-intent-status-reference">Payment Intent 状态参考</h3>

| 状态                         | 说明                                              | 后续动作                           | 阶段   | 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`          |

<h2 id="payment-attempt-pa">Payment Attempt (PA)</h2>

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

<h3 id="key-characteristics">关键特性</h3>

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

<h3 id="payment-attempt-status-reference">Payment Attempt 状态参考</h3>

| 状态                          | 说明                                   | 阶段   | 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`            |

<h2 id="payment-flow">支付流程</h2>

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

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

```mermaid theme={null}
sequenceDiagram
    participant Consumer as 消费者
    participant Merchant as 商户系统
    participant UQPAY as UQPAY 系统

    Note over Consumer,UQPAY: 直接支付模式
    Consumer->>Merchant: 带支付方式信息下单
    Merchant->>UQPAY: 创建 PaymentIntent（携带 payment_method）
    UQPAY-->>Merchant: acquiring.payment_intent.created
    UQPAY-->>Merchant: acquiring.payment_attempt.created
    
    alt 支付成功
        UQPAY->>UQPAY: 处理支付
        Note right of UQPAY: PA: CAPTURE_REQUESTED<br/>PI: SUCCEEDED
        UQPAY-->>Merchant: acquiring.payment_intent.succeeded
        UQPAY-->>Merchant: acquiring.payment_attempt.capture_requested
        Merchant->>Consumer: 支付成功
    else 支付失败
        UQPAY->>UQPAY: 处理支付
        Note right of UQPAY: PA: FAILED<br/>PI: REQUIRES_PAYMENT_METHOD
        UQPAY-->>Merchant: acquiring.payment_attempt.failed
        Merchant->>Consumer: 支付失败
    end

    Note over Consumer,UQPAY: 延迟确认支付模式
    Consumer->>Merchant: 仅下单（无支付方式信息）
    Merchant->>UQPAY: 创建 PaymentIntent（不带 payment_method）
    Note right of UQPAY: PI: REQUIRES_PAYMENT_METHOD
    UQPAY-->>Merchant: acquiring.payment_intent.created
    
    Note over Merchant,UQPAY: 可选：更新订单信息
    Merchant->>UQPAY: 更新 PaymentIntent（金额、币种等）
    UQPAY->>Merchant: PaymentIntent 已更新
    
    Consumer->>Merchant: 选择支付方式并填写信息
    Merchant->>UQPAY: Confirm PaymentIntent
    Note right of UQPAY: PA: INITIATED
    UQPAY-->>Merchant: acquiring.payment_attempt.created
    
    alt 支付成功
        UQPAY->>UQPAY: 处理支付
        Note right of UQPAY: PA: CAPTURE_REQUESTED<br/>PI: SUCCEEDED
        UQPAY-->>Merchant: acquiring.payment_intent.succeeded
        UQPAY-->>Merchant: acquiring.payment_attempt.capture_requested
        Merchant->>Consumer: 支付成功
    else 支付失败
        UQPAY->>UQPAY: 处理支付
        Note right of UQPAY: PA: FAILED<br/>PI: REQUIRES_PAYMENT_METHOD
        UQPAY-->>Merchant: acquiring.payment_attempt.failed
        Merchant->>Consumer: 支付失败
    end

    Note over Consumer,UQPAY: 取消场景
    alt 系统自动关闭（30 分钟超时）
        UQPAY->>UQPAY: 自动关闭已过期的 PI
        Note right of UQPAY: PI: FAILED
        UQPAY-->>Merchant: acquiring.payment_intent.failed
    else 商户发起取消
        Merchant->>UQPAY: Cancel PaymentIntent
        UQPAY->>UQPAY: 取消支付
        Note right of UQPAY: PA: CANCELLED<br/>PI: CANCELLED
        UQPAY-->>Merchant: acquiring.cancel.succeeded
        UQPAY-->>Merchant: acquiring.payment_attempt.cancelled
    end
```