获取表单 iframeUrl

📌 Overview

该接口用于创建 Iframe 支付地址，适用于前端嵌入支付场景。

商户通过本接口获取 iframeUrl，在页面中加载该地址即可完成支付流程。

🔐 Authentication

所有请求需包含以下 Header：

Header	类型	必填	说明
tenant-id	string	是	商户租户ID
Request-Time	string	是	请求时间戳（毫秒）
Signature	string	是	签名字段

示例：

http

tenant-id: 220818025875
Request-Time: 1760166006330
Signature: algorithm=MD5,keyVersion=1,signature=3cf78f044908f9c12399f73c62c9fb05

Endpoint

http

POST /payment/payments/iframeUrl

请求示例

shell

curl --location --request POST 'http://localhost:9999/payment/payments/iframeUrl' \
--header 'tenant-id: 220818025875' \
--header 'Request-Time: 1760166006330' \
--header 'Signature: algorithm=MD5,keyVersion=1,signature=3cf78f044908f9c12399f73c62c9fb05' \
--header 'Content-Type: application/json' \
--data-raw '{
    "channel": "iframeTest",
    "source": "shopyy",
    "website": "www.qq.com",
    "country": "US",
    "payMethodId": "1",
    "reference": "P1911",
    "amount": 10000,
    "currency": "USD"
}'

Parameters

Body Parameters

字段	类型	必填	说明
channel	string	是	通道标识（后台配置）
source	string	是	来源平台
website	string	是	网站域名（不带协议）
country	string	是	国家代码（ISO 2位，如 US）
payMethodId	string	是	支付方式ID
reference	string	是	商户订单号（全局唯一）
amount	integer	是	金额（最小单位）
currency	string	是	货币代码（如 USD）

Source 枚举

text

shopyy, shopline, shopify, woocommerce, wix, bigcommerce,
magento, opencart, squarespace, tilda, webflow, etsy,
shopee, lazada, temu, shein, amazon, ebay,
aliexpress, wish, tiktokshop, api

📥 Response

Success Response

json

{
  "requestId": "85b1f915-1c45-4ee0-8716-56d00c09dd28",
  "success": true,
  "data": {
    "channel": "iframeTest",
    "source": "shopyy",
    "url": "https://api.links-pay.com?token=37f88b34-537b-4774-8692-5e307d12f4d8",
    "expiresAt": "2025-10-14 17:32:38",
    "expiresIn": 86400,
    "iframeToken": "6861aa86-16c9-4721-8e9b-9bd69215e43b"
  },
  "timestamp": "2025-10-13T17:32:38.422+08:00"
}

Response Fields

字段	类型	说明
requestId	string	请求唯一ID
success	boolean	是否成功
error	string/null	错误信息
data	object	返回数据
timestamp	string	响应时间

Data Object

字段	类型	说明
channel	string	通道
source	string	来源
url	string	iframe支付地址
expiresAt	string	过期时间
expiresIn	integer	有效期（秒）
iframeToken	string	iframe token

❌ Failure Response

json

{
  "requestId": "xxx",
  "success": false,
  "error": "The merchant is not authorized to use this payment channel",
  "timestamp": "2025-10-13T17:30:29.243+08:00"
}

⚠️ Notes

reference 必须全局唯一
amount 为最小货币单位（如 1000 = $10.00）
website 不包含协议（http/https）
建议使用服务端调用，避免前端暴露敏感信息

🔄 Payment Flow

text

1. 商户调用接口初始化接口 iframeUrl 获取iframeHtml
2. 前端父页面 iframe嵌入html url
3. 持卡人输入卡信息，提交给父页面
4. 父页面通过《payments》接口完成付款
5. 商户通过回调或查询接口确认结果

🚀 Best Practices

使用 HTTPS
订单号（reference）保持唯一
做好接口幂等处理
使用 Webhook 或 Query API 确认最终支付状态

获取表单 iframeUrl ​

📌 Overview ​

🔐 Authentication ​

Endpoint ​

请求示例 ​

Parameters ​

📥 Response ​

❌ Failure Response ​

⚠️ Notes ​

🔄 Payment Flow ​

🚀 Best Practices ​