Skip to main content

Overview

The Hosted Payment Page (HPP) solution allows you to accept payments by securely redirecting your customers to a UQPay-hosted checkout page. This ensures sensitive payment data is handled securely by UQPay.

How to use

1. Create a PaymentIntent

Call the Create Payment Intent API to initiate a transaction and get the necessary credentials for the SDK. API Reference: Create Payment Intent

Request Example

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

Response Example

{
  "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. Extract Parameters

From the API response in Step 1, you need to extract the following values to pass to your frontend:
  • client_secret
  • payment_intent_id
  • currency

3. Initialize SDK

On your frontend, install the UQPay Checkout SDK and use the extracted parameters to redirect the user. SDK Package: @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
  });
}
Hosted page ![[Pasted image 20251217194233.png]]

4. Get Payment Result

You can confirm the final status of the payment using one of the following methods: Configure your server to listen for asynchronous notifications from UQPay. This is the most reliable way to update your order status. Webhook Reference:

Method B: Active Query

Your server can proactively query the status of the PaymentIntent using the API. API Reference: Retrieve Payment Intent