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

# Direct API 集成

> 通过 UQPAY API 直接创建 payment intent、处理 payment attempt，受理卡支付。

本指南将带你使用 Direct API 集成方式，完成一次 card-not-present（线上）支付的完整流程。你将创建 Payment Intent、按需处理身份验证，并接收支付结果。

## 步骤1：创建 Payment Intent

根据拿到支付方式的时机不同，有两种做法：

> [tab] 直接支付
>
> 在创建请求中携带 `payment_method`，支付会立即执行。
>
> ```bash theme={null}
> curl -X POST https://api-sandbox.uqpaytech.com/api/v2/payment_intents/create \
>   -H "Content-Type: application/json" \
>   -H "x-auth-token: Bearer {your_access_token}" \
>   -H "x-client-id: {your_client_id}" \
>   -H "x-idempotency-key: $(uuidgen)" \
>   -d '{
>     "amount": "8.98",
>     "currency": "SGD",
>     "payment_method": {
>       "type": "card",
>       "card": {
>         "card_name": "UQPAY",
>         "card_number": "5346930100108117",
>         "expiry_month": "12",
>         "expiry_year": "2026",
>         "cvc": "811",
>         "network": "mastercard",
>         "billing": {
>           "first_name": "UQPAY",
>           "last_name": "ACQ",
>           "email": "acq@uqpay.com",
>           "phone_number": "0524-91353515",
>           "address": {
>             "country_code": "SG",
>             "state": "Singapore",
>             "city": "Singapore",
>             "street": "444 Orchard Rd, Midpoint Orchard, Singapore",
>             "postcode": "924011"
>           }
>         },
>         "auto_capture": true,
>         "authorization_type": "authorization",
>         "three_ds_action": "skip_3ds"
>       }
>     },
>     "merchant_order_id": "order-001",
>     "description": "Test payment",
>     "metadata": {},
>     "return_url": "https://example.com/callback"
>   }'
> ```
>
> **API 参考：** [Create Payment Intent](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/api-reference/create-payment-intent.md)

> [tab] 延迟确认
>
> 先创建一个不带支付方式的 PI：
>
> ```bash theme={null}
> curl -X POST https://api-sandbox.uqpaytech.com/api/v2/payment_intents/create \
>   -H "Content-Type: application/json" \
>   -H "x-auth-token: Bearer {your_access_token}" \
>   -H "x-client-id: {your_client_id}" \
>   -H "x-idempotency-key: $(uuidgen)" \
>   -d '{
>     "amount": "8.98",
>     "currency": "SGD",
>     "merchant_order_id": "order-002",
>     "description": "Test payment",
>     "metadata": {},
>     "return_url": "https://example.com/callback"
>   }'
> ```
>
> PI 创建后 `intent_status` 为 `REQUIRES_PAYMENT_METHOD`。在 confirm 之前，你可以选择更新 PI（金额、币种等）。
>
> 然后带上支付方式进行 confirm：
>
> ```bash theme={null}
> curl -X POST https://api-sandbox.uqpaytech.com/api/v2/payment_intents/{payment_intent_id}/confirm \
>   -H "Content-Type: application/json" \
>   -H "x-auth-token: Bearer {your_access_token}" \
>   -H "x-client-id: {your_client_id}" \
>   -H "x-idempotency-key: $(uuidgen)" \
>   -d '{
>     "payment_method": {
>       "type": "card",
>       "card": {
>         "card_name": "UQPAY",
>         "card_number": "5346930100108117",
>         "expiry_month": "12",
>         "expiry_year": "2026",
>         "cvc": "811",
>         "network": "mastercard",
>         "billing": {
>           "first_name": "UQPAY",
>           "last_name": "ACQ",
>           "email": "acq@uqpay.com",
>           "phone_number": "0524-91353515",
>           "address": {
>             "country_code": "SG",
>             "state": "Singapore",
>             "city": "Singapore",
>             "street": "444 Orchard Rd, Midpoint Orchard, Singapore",
>             "postcode": "924011"
>           }
>         },
>         "auto_capture": true,
>         "authorization_type": "authorization",
>         "three_ds_action": "skip_3ds"
>       }
>     }
>   }'
> ```
>
> **API 参考：** [Confirm Payment Intent](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/api-reference/confirm-payment-intent.md)

## 步骤2：处理响应

根据响应中的 `intent_status` 字段决定下一步动作：

| `intent_status` | 动作 |
| - | - |
| `SUCCEEDED` | 支付已完成。更新你的订单状态。 |
| `REQUIRES_CUSTOMER_ACTION` | 客户需要完成额外步骤（例如 3DS 验证）。参见[处理客户动作](#step-3-handle-customer-actions)。 |
| `REQUIRES_PAYMENT_METHOD` | payment attempt 已失败。提示客户更换支付方式或换张卡。 |
| `PENDING` | 支付处理中。等待 webhook 通知。 |

### 成功响应示例

```json theme={null}
{
  "amount": 8.98,
  "currency": "SGD",
  "intent_status": "SUCCEEDED",
  "payment_intent_id": "PI1933438751883661312",
  "latest_payment_attempt": {
    "attempt_id": "PA1933438751988518912",
    "attempt_status": "CAPTURE_REQUESTED",
    "amount": 8.98,
    "complete_time": "2025-06-13T16:18:14+08:00"
  },
  "merchant_order_id": "order-001"
}
```

## 步骤3：处理客户动作

当 `intent_status` 为 `REQUIRES_CUSTOMER_ACTION` 时，`next_action` 字段会告诉你客户需要做什么。

### 3DS 重定向

如果卡需要 3D Secure 身份验证，`next_action` 会携带一个重定向 URL：

```json theme={null}
{
  "next_action": {
    "redirect_to_url": {
      "return_url": "",
      "url": "https://checkout-sandbox.uqpaytech.com/secure/..."
    },
    "type": "redirect_to_url"
  }
}
```

将客户重定向到该 URL。客户完成 3DS 后，会被重定向到你配置的 `return_url`。详细的 3DS 集成说明见：

* [3DS Integration Guide - Option 1](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/guide/3ds-integration-guide-option-1.md)
* [3DS Integration Guide - Option 2](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/guide/3ds-integration-guide-option-2.md)

### 展示二维码

对于电子钱包支付（AlipayCN、WeChatPay 等），`next_action` 可能会携带一个二维码：

```json theme={null}
{
  "next_action": {
    "display_qr_code": {
      "qr_code": "https://global.alipay.com/281002040092rZoN1k6ln7O91r9fwjb2tUo2",
      "qr_code_url": "https://global.alipay.com/merchant/order/showQrImage.htm?code=...",
      "expires_at": "2025-06-19T14:38:59.563+08:00"
    }
  }
}
```

将二维码展示给客户，等待客户在钱包 App 中扫码并确认付款。

## 步骤4：获取支付结果

使用下列一种或两种方式来确认最终支付状态：

### Webhooks（推荐）

配置你的服务端接收来自 UQPAY 的异步通知。这是最可靠的方式。

关键 webhook 事件：

* [`acquiring.payment_intent.succeeded`](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/webhooks/paymentintent-result) —— 支付已完成
* [`acquiring.payment_attempt.failed`](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/webhooks/paymentattempt-result) —— payment attempt 失败。注意：`acquiring.payment_intent.failed` 只在 PI 超时自动关闭（30 分钟过期）时触发，单次尝试失败不会触发它。
* [`acquiring.payment_attempt.capture_requested`](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/webhooks/paymentattempt-result) —— 请款已提交。收到这个事件也意味着支付已成功。

### Retrieve 接口（轮询）

直接查询支付状态：

```bash theme={null}
curl https://api-sandbox.uqpaytech.com/api/v2/payment_intents/{payment_intent_id} \
  -H "x-auth-token: Bearer {your_access_token}" \
  -H "x-client-id: {your_client_id}"
```

**API 参考：** [Retrieve Payment Intent](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/api-reference/retrieve-payment-intent.md)

## 电子钱包支付

同一套 API 也支持电子钱包支付方式。把 `payment_method` 对象替换成对应的钱包类型即可：

> [accordion] AlipayCN 二维码示例
>
> ```json theme={null}
> {
>   "amount": "7.77",
>   "currency": "SGD",
>   "payment_method": {
>     "type": "alipaycn",
>     "alipaycn": {
>       "flow": "qrcode",
>       "is_present": false
>     }
>   },
>   "merchant_order_id": "order-alipay-001",
>   "description": "Alipay test",
>   "metadata": {},
>   "return_url": "https://example.com/callback"
> }
> ```
>
> 响应中会包含 `next_action.display_qr_code` 供客户扫码。

> [accordion] AlipayCN 付款码示例（线下）
>
> ```json theme={null}
> {
>   "amount": "1.11",
>   "currency": "SGD",
>   "payment_method": {
>     "type": "alipaycn",
>     "alipaycn": {
>       "flow": "qrcode",
>       "os_type": "ios",
>       "is_present": true,
>       "payment_code": "284057804613761079"
>     }
>   },
>   "merchant_order_id": "order-alipay-002",
>   "description": "Alipay payment code test",
>   "metadata": {},
>   "return_url": "https://example.com/callback"
> }
> ```
>
> 付款码交易在付款码有效时即刻完成。

支持的支付方式全量清单及参数说明，见[支付方式](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/guide/payment-methods.md)。

## 预授权与手动请款

使用预授权前，确认账户和支付渠道支持此能力。请通过直接API使用`card`或`card_present`；Hosted Payment Page和Payment Links不支持预授权。

1. 在[创建](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/api-reference/create-payment-intent.md)或[确认](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/api-reference/confirm-payment-intent.md)PaymentIntent时，将`authorization_type`设为`pre_authorization`，并将`payment_method.card.auto_capture`或`payment_method.card_present.auto_capture`设为`false`。若支付方式内也提供授权类型，两处值必须一致。确认时不能将预授权PaymentIntent改为普通授权。
2. 授权后检查`intent_status`、`authorization_expires_at`和`available_to_capture`。在PaymentIntent为`REQUIRES_CAPTURE`且尚未到期时请款，不要假定固定授权期限。
3. 每笔授权只[请款一次](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/api-reference/capture-payment-intent.md)。省略`final_capture`或设为`true`；`false`会被拒绝。省略`amount_to_capture`时请款全部可用金额，也可提供不超过该额度的正数金额。部分金额的最终请款要求渠道支持。零金额、空字符串和null均会被拒绝。剩余授权额度由系统释放，不要用第二次请款或零金额请款释放余额。
4. 保存返回的`capture_id`和`merchant_capture_order_id`，通过[查询PaymentIntent](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/api-reference/retrieve-payment-intent.md)检查`capture_records`。请款受理以及PaymentIntent的聚合金额不代表渠道已完成处理。每条记录的`channel_capture_status`为：`0`待处理、`1`处理中、`2`完成、`3`失败。

普通授权的手动请款金额必须等于全部授权金额。仅预授权在渠道支持时允许较小金额的最终请款。

### 请款单号与重试

使用账户内唯一、最多64个字符的`merchant_capture_order_id`。省略时使用PaymentIntent的`merchant_order_id`。传输失败后重试相同请求时，复用同一`X-Idempotency-Key`。在缓存响应之外再次提交已记录的请款单号会被拒绝，不会作为另一笔请款执行。进一步操作前，先查询已有PaymentIntent确认结果。请款失败也不能针对同一授权再次请款。

### 撤销与退款

尚未发生请款且授权未过期时，若渠道支持，可[撤销](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/guide/cancellation.md)预授权。请款后通过[退款流程](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/guide/refunds.md)退回已请款资金。`available_to_void`大于零不代表一定允许撤销。

PaymentIntent的`captured_amount`表示聚合请款金额；PaymentAttempt没有请款金额字段。单笔请款使用`capture_records[].capture_amount`及其处理状态。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.