跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/llms.txt

Use this file to discover all available pages before exploring further.

本指南将带你使用 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": "[email protected]",
          "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

​
步骤2：处理响应

根据响应中的 intent_status 字段决定下一步动作：
intent_status动作
SUCCEEDED支付已完成。更新你的订单状态。
REQUIRES_CUSTOMER_ACTION客户需要完成额外步骤（例如 3DS 验证）。参见处理客户动作。
REQUIRES_PAYMENT_METHODpayment 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,
    "captured_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：获取支付结果

使用下列一种或两种方式来确认最终支付状态： 配置你的服务端接收来自 UQPAY 的异步通知。这是最可靠的方式。 关键 webhook 事件：

​
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 对象替换成对应的钱包类型即可： 
{
  "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 供客户扫码。
{
  "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"
}
付款码交易在付款码有效时即刻完成。
支持的支付方式全量清单及参数说明，见支付方式。