Hosted Payment Page (HPP) 集成指南

将客户重定向到 UQPAY 托管的收银台页面，安全受理支付，无需处理敏感支付数据。

​

概览

Hosted Payment Page (HPP) 方案让你通过将客户安全地重定向到 UQPay 托管的收银台页面来受理支付。敏感支付数据由 UQPay 安全处理。

​

使用方式

​

1. 创建 PaymentIntent

调用 Create Payment Intent 接口发起交易，并获取 SDK 所需的凭证。

API 参考： Create Payment Intent

​

请求示例

curl --location 'https://api-sandbox.uqpaytech.com/api/v2/payment_intents/create' \
--header 'x-idempotency-key: {uuid}' \
--header 'x-client-id: {your_client_id}' \
--header 'Content-Type: application/json' \
--header 'x-auth-token: Bearer {token}' \
--data '{
  "amount": "11.11",
  "currency": "SGD",
  "merchant_order_id": "2d7645d9-3395-4da3-989a-1462e6235c4a",
  "description": "acquiring sandbox hpp",
  "metadata": {},
  "return_url": "https://127.0.0.1:8080/api/v1/callback"
}'

​

响应示例

{
  "amount": "11.11",
  "available_payment_method_types": [
    "tng",
    "unionpay",
    "wechatpay",
    "alipaycn",
    "alipayhk",
    "card",
    "grabpay",
    "paynow"
  ],
  "cancel_time": "",
  "cancellation_reason": "",
  "captured_amount": "0",
  "client_secret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtYXN0ZXJfaWQiOiIwIiwiYWNjb3VudF9pZCI6ImIxYjg5Njg0LWMyYzQtNGQ1NC1iOGE4LTM1NzI3MjdmZDEyMCIsImludGVudF9pZCI6IlBJMjAwMTEyMDkxNTE2MDU2NzgwOCIsImV4cCI6MTc2NTk0MTE3OSwiaWF0IjoxNzY1OTM5Mzc5fQ.TZha66QBSv5vxpmz34ss8JxWX09P-_SqstHL7k5uyns",
  "complete_time": "",
  "create_time": "2025-12-17T10:42:59+08:00",
  "currency": "SGD",
  "description": "acquiring sandbox hpp",
  "intent_status": "REQUIRES_PAYMENT_METHOD",
  "latest_payment_attempt": null,
  "merchant_order_id": "2d7645d9-3395-4da3-989a-1462e6235c4a",
  "metadata": null,
  "next_action": null,
  "payment_intent_id": "PI2001120915160567808",
  "return_url": "https://127.0.0.1:8080/api/v1/callback",
  "update_time": "2025-12-17T10:42:59+08:00"
}

​

2. 提取参数

从步骤 1 的 API 响应中，提取以下字段传给你的前端：

• client_secret
• payment_intent_id
• currency

​

3. 初始化 SDK

在前端安装 UQPay Checkout SDK，并使用上述参数将用户重定向。

SDK 包： @uqpay/checkout-sdk

import { init } from '@uqpay/checkout-sdk';

async function redirectToPayment() {
  // Initialize SDK
  const uqpay = await init({
    env: 'production', // 'sandbox' | 'production'
    enabledElements: ['payments']
  });

  // Redirect to payment page
  await uqpay.payments.redirectToCheckout({
    mode: 'payment',
    currency: 'USD',
    intent_id: 'pi_1234567890',
    client_secret: 'pi_1234567890_secret_abcdef',
    success_url: 'https://yoursite.com/success', // Optional
    failure_url: 'https://yoursite.com/failure', // Optional
  });
}

​

4. 获取支付结果

可以通过以下任意方式确认支付的最终状态：

Webhook 参考：

• PaymentIntent Result
• PaymentAttempt Result

API 参考： Retrieve Payment Intent