curl --request POST \
--url https://api-sandbox.uqpaytech.com/api/v2/payment_intents/create \
--header 'Content-Type: application/json' \
--header 'x-auth-token: <api-key>' \
--header 'x-client-id: <x-client-id>' \
--header 'x-idempotency-key: <x-idempotency-key>' \
--data '
{
"amount": "1.00",
"currency": "SGD",
"merchant_order_id": "ce37d547-53c7-4648-988b-691a352b5446",
"return_url": "https://example.com/return",
"description": "Sandbox contract test"
}
'import requests
url = "https://api-sandbox.uqpaytech.com/api/v2/payment_intents/create"
payload = {
"amount": "1.00",
"currency": "SGD",
"merchant_order_id": "ce37d547-53c7-4648-988b-691a352b5446",
"return_url": "https://example.com/return",
"description": "Sandbox contract test"
}
headers = {
"x-idempotency-key": "<x-idempotency-key>",
"x-client-id": "<x-client-id>",
"x-auth-token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-idempotency-key': '<x-idempotency-key>',
'x-client-id': '<x-client-id>',
'x-auth-token': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount: '1.00',
currency: 'SGD',
merchant_order_id: 'ce37d547-53c7-4648-988b-691a352b5446',
return_url: 'https://example.com/return',
description: 'Sandbox contract test'
})
};
fetch('https://api-sandbox.uqpaytech.com/api/v2/payment_intents/create', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-sandbox.uqpaytech.com/api/v2/payment_intents/create",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => '1.00',
'currency' => 'SGD',
'merchant_order_id' => 'ce37d547-53c7-4648-988b-691a352b5446',
'return_url' => 'https://example.com/return',
'description' => 'Sandbox contract test'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-auth-token: <api-key>",
"x-client-id: <x-client-id>",
"x-idempotency-key: <x-idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-sandbox.uqpaytech.com/api/v2/payment_intents/create"
payload := strings.NewReader("{\n \"amount\": \"1.00\",\n \"currency\": \"SGD\",\n \"merchant_order_id\": \"ce37d547-53c7-4648-988b-691a352b5446\",\n \"return_url\": \"https://example.com/return\",\n \"description\": \"Sandbox contract test\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
req.Header.Add("x-client-id", "<x-client-id>")
req.Header.Add("x-auth-token", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-sandbox.uqpaytech.com/api/v2/payment_intents/create")
.header("x-idempotency-key", "<x-idempotency-key>")
.header("x-client-id", "<x-client-id>")
.header("x-auth-token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": \"1.00\",\n \"currency\": \"SGD\",\n \"merchant_order_id\": \"ce37d547-53c7-4648-988b-691a352b5446\",\n \"return_url\": \"https://example.com/return\",\n \"description\": \"Sandbox contract test\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.uqpaytech.com/api/v2/payment_intents/create")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-idempotency-key"] = '<x-idempotency-key>'
request["x-client-id"] = '<x-client-id>'
request["x-auth-token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": \"1.00\",\n \"currency\": \"SGD\",\n \"merchant_order_id\": \"ce37d547-53c7-4648-988b-691a352b5446\",\n \"return_url\": \"https://example.com/return\",\n \"description\": \"Sandbox contract test\"\n}"
response = http.request(request)
puts response.read_body{
"amount": "1",
"available_payment_method_types": [
"gcash",
"dana",
"alipayplus",
"googlepay",
"boost",
"hipay",
"alipaycn",
"grabpay",
"tng",
"tosspay",
"card",
"wechatpay",
"kakaopay",
"naverpay",
"kplus",
"kaspi",
"unionpay",
"paynow",
"alipayhk",
"truemoney",
"crypto",
"applepay",
"mpay",
"rabbitlinepay"
],
"cancel_time": "",
"cancellation_reason": "",
"captured_amount": "0",
"client_secret": "<client-secret>",
"complete_time": "",
"create_time": "2026-09-14T17:03:35+08:00",
"currency": "SGD",
"customer_id": "",
"description": "Sandbox contract test",
"intent_status": "REQUIRES_PAYMENT_METHOD",
"latest_payment_attempt": null,
"merchant_order_id": "ce37d547-53c7-4648-988b-691a352b5446",
"metadata": null,
"next_action": null,
"payment_intent_id": "PI2099423807759454208",
"payment_method_flows": {
"crypto": [
"redirect",
"qrcode"
],
"unionpay": [
"qrcode",
"securepay"
]
},
"return_url": "https://example.com/return",
"update_time": "2026-09-14T17:03:35+08:00"
}Create a PaymentIntent
为客户订单创建支付意图,用于发起收款并跟踪支付处理状态。
如果已经取得支付方式,可在请求中提供 payment_method,直接开始支付处理;如果尚未取得,可先创建支付意图,取得支付方式后再调用 Confirm a PaymentIntent。
根据返回的 intent_status 和 next_action 判断支付进度及客户是否需要完成额外操作。完整流程参见直接 API 集成。
curl --request POST \
--url https://api-sandbox.uqpaytech.com/api/v2/payment_intents/create \
--header 'Content-Type: application/json' \
--header 'x-auth-token: <api-key>' \
--header 'x-client-id: <x-client-id>' \
--header 'x-idempotency-key: <x-idempotency-key>' \
--data '
{
"amount": "1.00",
"currency": "SGD",
"merchant_order_id": "ce37d547-53c7-4648-988b-691a352b5446",
"return_url": "https://example.com/return",
"description": "Sandbox contract test"
}
'import requests
url = "https://api-sandbox.uqpaytech.com/api/v2/payment_intents/create"
payload = {
"amount": "1.00",
"currency": "SGD",
"merchant_order_id": "ce37d547-53c7-4648-988b-691a352b5446",
"return_url": "https://example.com/return",
"description": "Sandbox contract test"
}
headers = {
"x-idempotency-key": "<x-idempotency-key>",
"x-client-id": "<x-client-id>",
"x-auth-token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-idempotency-key': '<x-idempotency-key>',
'x-client-id': '<x-client-id>',
'x-auth-token': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
amount: '1.00',
currency: 'SGD',
merchant_order_id: 'ce37d547-53c7-4648-988b-691a352b5446',
return_url: 'https://example.com/return',
description: 'Sandbox contract test'
})
};
fetch('https://api-sandbox.uqpaytech.com/api/v2/payment_intents/create', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-sandbox.uqpaytech.com/api/v2/payment_intents/create",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => '1.00',
'currency' => 'SGD',
'merchant_order_id' => 'ce37d547-53c7-4648-988b-691a352b5446',
'return_url' => 'https://example.com/return',
'description' => 'Sandbox contract test'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-auth-token: <api-key>",
"x-client-id: <x-client-id>",
"x-idempotency-key: <x-idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-sandbox.uqpaytech.com/api/v2/payment_intents/create"
payload := strings.NewReader("{\n \"amount\": \"1.00\",\n \"currency\": \"SGD\",\n \"merchant_order_id\": \"ce37d547-53c7-4648-988b-691a352b5446\",\n \"return_url\": \"https://example.com/return\",\n \"description\": \"Sandbox contract test\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
req.Header.Add("x-client-id", "<x-client-id>")
req.Header.Add("x-auth-token", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-sandbox.uqpaytech.com/api/v2/payment_intents/create")
.header("x-idempotency-key", "<x-idempotency-key>")
.header("x-client-id", "<x-client-id>")
.header("x-auth-token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": \"1.00\",\n \"currency\": \"SGD\",\n \"merchant_order_id\": \"ce37d547-53c7-4648-988b-691a352b5446\",\n \"return_url\": \"https://example.com/return\",\n \"description\": \"Sandbox contract test\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.uqpaytech.com/api/v2/payment_intents/create")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-idempotency-key"] = '<x-idempotency-key>'
request["x-client-id"] = '<x-client-id>'
request["x-auth-token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": \"1.00\",\n \"currency\": \"SGD\",\n \"merchant_order_id\": \"ce37d547-53c7-4648-988b-691a352b5446\",\n \"return_url\": \"https://example.com/return\",\n \"description\": \"Sandbox contract test\"\n}"
response = http.request(request)
puts response.read_body{
"amount": "1",
"available_payment_method_types": [
"gcash",
"dana",
"alipayplus",
"googlepay",
"boost",
"hipay",
"alipaycn",
"grabpay",
"tng",
"tosspay",
"card",
"wechatpay",
"kakaopay",
"naverpay",
"kplus",
"kaspi",
"unionpay",
"paynow",
"alipayhk",
"truemoney",
"crypto",
"applepay",
"mpay",
"rabbitlinepay"
],
"cancel_time": "",
"cancellation_reason": "",
"captured_amount": "0",
"client_secret": "<client-secret>",
"complete_time": "",
"create_time": "2026-09-14T17:03:35+08:00",
"currency": "SGD",
"customer_id": "",
"description": "Sandbox contract test",
"intent_status": "REQUIRES_PAYMENT_METHOD",
"latest_payment_attempt": null,
"merchant_order_id": "ce37d547-53c7-4648-988b-691a352b5446",
"metadata": null,
"next_action": null,
"payment_intent_id": "PI2099423807759454208",
"payment_method_flows": {
"crypto": [
"redirect",
"qrcode"
],
"unionpay": [
"qrcode",
"securepay"
]
},
"return_url": "https://example.com/return",
"update_time": "2026-09-14T17:03:35+08:00"
}授权
UQPAY 提供的登录 API Token。
请求头
指定代表哪个子账户发起该请求。应设置为 account_id,可通过 List Connected Accounts 获取。若省略或为空,则使用主账户执行请求。
更多信息见 Connected Accounts。
用于保持操作幂等性的唯一标识符(UUID),确保同一操作重复执行不会产生意外影响或重复结果。它有助于在网络错误、重试或故障时保持数据一致性。
UQPAY 生成的 API 客户端 ID
请求体
该 PaymentIntent 拟收取的金额。
"10.12"
三位币种代码
"SGD"
商户系统中为该 PaymentIntent 创建的商户参考 ID
36将向客户展示的描述符。最大长度为 32。
32"Sandbox contract test"
支付认证完成后用于跳转客户的网页 URL 或应用 scheme URI。
1024授权模式。预授权要求账户与渠道支持,支付方式为card或card_present,且auto_capture=false。此处与payment_method内同时提供时必须一致;省略时使用支付方式中的值,否则按普通授权处理。
authorization, pre_authorization 用于确认 PaymentIntent 的支付方式详情。设置 payment_method 后,PaymentIntent 将自动确认。
- card
- card_present
- applepay
- googlepay
- alipaycn
- alipayhk
- unionpay
- wechatpay
- grabpay
- crypto
- paynow
- truemoney
- tng
- gcash
- dana
- kakaopay
- toss
- naverpay
Show child attributes
Show child attributes
设备的 IPv4 或 IPv6 地址。
当 payment_method.card.three_ds_action=enforce_3ds 时必填。
否则可选。
45"212.121.222.123"
内联的客户详情。为某位购物者创建第一笔 PaymentIntent 时提供此项,可在托管支付页面启用 Card on File(卡片留存)。UQPAY 会用这些详情创建一条客户记录,并在响应中返回生成的 customer_id。
当同时提供 customer_id 时本项将被忽略——优先级规则见 customer_id。
Show child attributes
Show child attributes
由先前的 Create PaymentIntent 调用返回的、已存在的 UQPAY 客户 ID。为同一购物者的后续支付传入此项,托管支付页面便可提供其已保存的卡片。
当同时提供 customer_id 和 customer 时,以 customer_id 优先。
访客结账时留空(该 PaymentIntent 将不参与 Card on File)。
36"cus_asyknf3wlfxhs1s6plamk80i8v"
与该 PaymentIntent 关联的采购订单
Show child attributes
Show child attributes
为风险与欺诈防控收集的浏览器信息。
当 three_ds_action=enforce_3ds 时必填
Show child attributes
Show child attributes
任意键值对象。最大长度 = 512 字节。必须是合法的 JSON 数据。
Show child attributes
Show child attributes
{ "key1": "value1", "key2": "value2" }
响应
成功创建 PaymentIntent
PaymentIntent 的唯一标识
36"b1c2d3e4-f5a6-b7c8-d9e0-f1a2b3c4d5e6"
支付金额。即你希望向客户收取的订单金额。
"10.12"
三位币种代码
"SGD"
该 PaymentIntent 的状态。
REQUIRES_PAYMENT_METHOD:PaymentIntent 正在等待确认请求。REQUIRES_CUSTOMER_ACTION:PaymentIntent 正在等待客户进一步的认证操作,例如 3DS 验证和扫描二维码。请查看next_action。REQUIRES_CAPTURE:PaymentIntent 正在等待你请款以完成支付。PENDING:PaymentIntent 正在等待支付渠道返回最终结果,无需进一步操作。SUCCEEDED:PaymentIntent 已成功,支付完成。CANCELLED:PaymentIntent 已按你的请求取消,支付已关闭。FAILED:PaymentIntent 已失败。PARTIALLY_CAPTURED: 部分请款的授权仍有待处理余额;不要再次提交请款。EXPIRED: 预授权已过期并释放。
PARTIALLY_CAPTURED, EXPIRED, REQUIRES_PAYMENT_METHOD, REQUIRES_CUSTOMER_ACTION, REQUIRES_CAPTURE, PENDING, SUCCEEDED, CANCELLED, FAILED "SUCCEEDED"
查询PaymentIntent详情或列表时,若存在则返回退款或授权释放详情。
查询PaymentIntent详情和列表时返回的请款记录。
Show child attributes
Show child attributes
本次支付的授权模式。
authorization, pre_authorization 预授权到期时间。未记录时为null。请使用返回的时间,不要假定固定冻结期限。
剩余可请款预授权额度。最终请款会消耗可用授权额度;渠道处理结果请查看capture_records。
剩余预授权额度,与available_to_capture相同。值大于零不代表一定允许撤销。
创建 PaymentIntent 时的描述符。
255该 PaymentIntent 可用的支付方式类型。
PaymentIntent记录的聚合请款金额。请款受理时可能早于渠道完成更新此值;处理结果请查看capture_records。
"10.12"
与该 PaymentIntent 关联的客户快照。在创建时提供了 customer 或 customer_id 时返回。客户的唯一标识在顶层以 customer_id 暴露;该对象内部不包含 id 字段。
Show child attributes
Show child attributes
与该 PaymentIntent 关联的客户 ID。访客结账时为空。
36"cus_asyknf3wlfxhs1s6plamk80i8v"
取消时间未记录时为空字符串。
取消该 PaymentIntent 的原因。
"Order cancelled"
用于浏览器或 App 的 PaymentIntent client secret。由 PaymentIntent 创建接口或查询接口返回。返回的 client_secret 有效期为 60 分钟。
"eyJhbGciOiJI***********ujNdZ1DF9CqWEfF1jphxI"
商户系统中为该 PaymentIntent 创建的商户参考 ID
36"1bf70d90-9ed0-48ce-9370-9bd7ef6ab9ee"
支付关联的元数据。未设置元数据时返回 null。
Show child attributes
Show child attributes
无可用的下一步操作时为 null;否则按返回的操作信息继续处理支付。
Show child attributes
Show child attributes
支付认证完成后用于跳转客户的网页 URL 或应用 scheme URI。
"https://127.0.0.1:8080/api/v1/callback"
该 PaymentIntent 的创建时间。
"2024-03-01T00:00:00+08:00"
完成时间未记录时为空字符串。
该 PaymentIntent 最近一次更新或操作的时间。
"2024-03-01T00:00:00+08:00"
最新 PaymentAttempt;没有可用的支付尝试时为 null。
- Latest payment attempt
- No payment attempt
Show child attributes
Show child attributes

