> ## 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.

# Direct API 集成

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

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

<h2 id="step-1-create-a-payment-intent">步骤1：创建 Payment Intent</h2>

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

<Tabs>
  <Tab title="直接支付">
    在创建请求中携带 `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](/zh/global-acquiring/v1.6/api-reference/create-payment-intent)
  </Tab>

  <Tab title="延迟确认">
    先创建一个不带支付方式的 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](/zh/global-acquiring/v1.6/api-reference/confirm-payment-intent)
  </Tab>
</Tabs>

<h2 id="step-2-handle-the-response">步骤2：处理响应</h2>

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

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

<h3 id="successful-response-example">成功响应示例</h3>

```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,
    "captured_amount": 8.98,
    "complete_time": "2025-06-13T16:18:14+08:00"
  },
  "merchant_order_id": "order-001"
}
```

<h2 id="step-3-handle-customer-actions">步骤3：处理客户动作</h2>

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

<h3 id="3ds-redirect">3DS 重定向</h3>

如果卡需要 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](/zh/global-acquiring/v1.6/guide/3ds-integration-guide-option-1)
* [3DS Integration Guide - Option 2](/zh/global-acquiring/v1.6/guide/3ds-integration-guide-option-2)

<h3 id="qr-code-display">展示二维码</h3>

对于电子钱包支付（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 中扫码并确认付款。

<h2 id="step-4-get-payment-results">步骤4：获取支付结果</h2>

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

<h3 id="webhooks-recommended">Webhooks（推荐）</h3>

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

关键 webhook 事件：

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

<h3 id="retrieve-api-polling">Retrieve 接口（轮询）</h3>

直接查询支付状态：

```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](/zh/global-acquiring/v1.6/api-reference/retrieve-payment-intent)

<h2 id="e-wallet-payments">电子钱包支付</h2>

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

<Accordion title="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>

<Accordion title="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"
  }
  ```

  付款码交易在付款码有效时即刻完成。
</Accordion>

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