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

# Hosted Payment Page (HPP) 集成指南

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

<h2 id="overview">概览</h2>

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

<h2 id="how-to-use">使用方式</h2>

<h3 id="1-create-a-paymentintent">1. 创建 PaymentIntent</h3>

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

**API 参考：** [Create Payment Intent](/zh/global-acquiring/v1.6/api-reference/create-payment-intent)

<h4 id="request-example">请求示例</h4>

```bash theme={null}
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"
}'
```

<h4 id="response-example">响应示例</h4>

```json theme={null}
{
  "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"
}
```

<h3 id="2-extract-parameters">2. 提取参数</h3>

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

* `client_secret`
* `payment_intent_id`
* `currency`

<h3 id="3-initialize-sdk">3. 初始化 SDK</h3>

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

**SDK 包：** [@uqpay/checkout-sdk](https://www.npmjs.com/package/@uqpay/checkout-sdk)

```javascript theme={null}
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
  });
}
```

<img src="https://mintcdn.com/uqpay-0838527a/xOu9nNDPoZYFqizv/images/global-acquiring/hpp.png?fit=max&auto=format&n=xOu9nNDPoZYFqizv&q=85&s=e4ac264b0c65097f39872ae28d1c3ddc" alt="Hosted Payment Page" width="1265" height="1212" data-path="images/global-acquiring/hpp.png" />

<h3 id="4-get-payment-result">4. 获取支付结果</h3>

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

<h4 id="method-a-webhook-recommended">方式 A：Webhook（推荐）</h4>
配置你的服务端监听 UQPay 发出的异步通知。这是更新订单状态最可靠的方式。

**Webhook 参考：**

* [PaymentIntent Result](/zh/global-acquiring/v1.6/webhooks/paymentintent-result)
* [PaymentAttempt Result](/zh/global-acquiring/v1.6/webhooks/paymentattempt-result)

<h4 id="method-b-active-query">方式 B：主动查询</h4>
你的服务端可以主动通过 API 查询 PaymentIntent 的状态。

**API 参考：** [Retrieve Payment Intent](/zh/global-acquiring/v1.6/api-reference/retrieve-payment-intent)