Direct API 集成

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

步骤1：创建 Payment Intent

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

直接支付
延迟确认

在创建请求中携带 payment_method，支付会立即执行。

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

先创建一个不带支付方式的 PI：

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：

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

步骤2：处理响应

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

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

成功响应示例

{
  "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：

{
  "next_action": {
    "redirect_to_url": {
      "return_url": "",
      "url": "https://checkout-sandbox.uqpaytech.com/secure/..."
    },
    "type": "redirect_to_url"
  }
}

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

展示二维码

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

{
  "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 —— 支付已完成
acquiring.payment_attempt.failed —— payment attempt 失败。注意：acquiring.payment_intent.failed 只在 PI 超时自动关闭（30 分钟过期）时触发，单次尝试失败不会触发它。
acquiring.payment_attempt.capture_requested —— 请款已提交。收到这个事件也意味着支付已成功。

Retrieve 接口（轮询）

直接查询支付状态：

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

电子钱包支付

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

AlipayCN 二维码示例

{
  "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 供客户扫码。

AlipayCN 付款码示例（线下）

{
  "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"
}

付款码交易在付款码有效时即刻完成。

支持的支付方式全量清单及参数说明，见支付方式。

预授权与手动请款

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

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

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

请款单号与重试

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

撤销与退款

尚未发生请款且授权未过期时，若渠道支持，可撤销预授权。请款后通过退款流程退回已请款资金。available_to_void大于零不代表一定允许撤销。 PaymentIntent的captured_amount表示聚合请款金额；PaymentAttempt没有请款金额字段。单笔请款使用capture_records[].capture_amount及其处理状态。

入门

收款集成

支付管理

测试

参考

步骤1：创建 Payment Intent

步骤2：处理响应

成功响应示例

步骤3：处理客户动作

3DS 重定向

展示二维码

步骤4：获取支付结果

Webhooks（推荐）

Retrieve 接口（轮询）

电子钱包支付

预授权与手动请款

请款单号与重试

撤销与退款

​步骤1：创建 Payment Intent

​步骤2：处理响应

​成功响应示例

​步骤3：处理客户动作

​3DS 重定向

​展示二维码

​步骤4：获取支付结果

​Webhooks（推荐）

​Retrieve 接口（轮询）

​电子钱包支付

​预授权与手动请款

​请款单号与重试

​撤销与退款

步骤1：创建 Payment Intent

步骤2：处理响应

成功响应示例

步骤3：处理客户动作

3DS 重定向

展示二维码

步骤4：获取支付结果

Webhooks（推荐）

Retrieve 接口（轮询）

电子钱包支付

预授权与手动请款

请款单号与重试

撤销与退款