支付接口

📌 Overview

该接口用于商户服务端在获取到持卡人 payToken 与 iframeToken 后，调用本接口完成订单的最终支付。

注意事项

reference 为商户侧订单号，必须保证全局唯一且与iframeUrl接口一致。同一订单号支持多次支付尝试，无需附加随机后缀。
iframeToken 来源于 iframeUrl 接口返回值，payToken 由 iframe 页面在持卡人输入卡信息后生成，调用本接口时必须传递。

Endpoint

http

POST /payment/payments

请求示例

shell

curl --location --request POST 'http://localhost:9999payment/payments' \
--header 'tenant-id: 220818025875' \
--header 'Request-Time: 1760166006330' \
--header 'Signature: algorithm=MD5,keyVersion=1,signature=3cf78f044908f9c12399f73c62c9fb05' \
--header 'Content-Type: application/json' \
--data-raw '{
    "iframeToken": "6861aa86-16c9-4721-8e9b-9bd69215e43b",
    "amount": 10000,
    "website": "www.links-pay.cc",
    "subject": "Women’s 3D Embroidered Bandeau Elegant Mini Dress",
    "channel": "iframeTest",
    "type": "iframe",
    "card": {
        "payToken": "a4a4575c-d144-4e7f-9fec-89c234f78d77"
    },
    "billing": {
        "country": "US",
        "firstName": "Melissa",
        "lastName": "Hughes",
        "address": "1225 Wilshire Blvd Apt 804",
        "city": "Los Angeles",
        "phone": "+14155527689",
        "postalCode": "90017",
        "state": "CA",
        "email": "melissa.hughes@example.com"
    },
    "reference": "R202512045",
    "shipping": {
        "country": "US",
        "firstName": "Melissa",
        "lastName": "Hughes",
        "address": "1225 Wilshire Blvd Apt 804",
        "city": "Los Angeles",
        "phone": "+14155527689",
        "postalCode": "90017",
        "state": "CA",
        "email": "melissa.hughes@example.com"
    },
    "notifyUrl": "https://www.links-pay.cc/notify",
    "currency": "USD",
    "returnUrl": "https://www.links-pay.cc/checkout.html",
    "items": [
        {
            "unitPrice": 10000,
            "name": "Women’s 3D Embroidered Bandeau Elegant Mini Dress",
            "currency": "USD",
            "quantity": "1",
            "category": "Women Clothing",
            "totalPrice": 10000
        }
    ],
    "browserInfo": {
        "screenWidth": 1920,
        "javaEnabled": false,
        "os": "Windows 10",
        "screenHeight": 1080,
        "ipAddress": "168.168.168.168",
        "browserName": "Chrome",
        "timeZone": -480,
        "javascriptEnabled": true,
        "language": "en-US",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36",
        "colorDepth": 24
    },
     "utm": {
        "utm_source": "facebook",
        "utm_medium": "social",
        "utm_term": "",
        "utm_content": ""
    }
}'

顶层字段

字段	类型	必填	说明
channel	string	是	通道标识。由平台配置，通道路线。仅允许平台分配的值，最长 64。
iframeToken	string	是	`iframeUrl` 接口返回。
reference	string	是	商户订单参考号。商户侧唯一（建议 64 以内），用于对账与幂等等。
amount	string	是	订单总金额，表示本次交易请求的支付金额。仅支持整数格式（不带小数点）。金额单位使用最小货币单位（如美分），且必须大于零，不得超过单笔限额。
subject	string	是	商品标题 / 摘要。用于持卡人账单与风控展示，UTF-8，最长 128。
currency	string	是	订单币种（ISO 4217）。大写三位字母，需在商户开通币种列表内。
website	string	是	交易来源站点。须为备案在白名单内的域名（不含协议）；未备案站点应拒绝或降级处理。
notifyUrl	string	是	服务器异步通知地址。推荐 HTTPS；商户需具备幂等处理能力（参考签名 / 重放防护）。
returnUrl	string	是	前端同步跳转地址。3DS / 收银台完成后浏览器跳转地址；推荐 HTTPS。
type	string	是	支付方式类型。取值：`iframe`。
payToken	string	否	持卡人填卡后加密的 `payToken`。
billing	object	是	账单信息对象。用于 AVS / FDS 及物流发货；在支持地区（US/UK/CA 等）启用 AVS 校验（Address / ZIP），作为风控要素之一。
shipping	object	是	物流地址信息。用于订单发货。
browserInfo	object	是	浏览器 / 设备信息。如果启用 3D 校验，`browserInfo` 将用于 AReq / CReq 报文；请确保字段完整，避免被 3DS 服务器降级或拒绝。
items	array[object]	是	订单项目列表。建议提供；用于风控、风险画像与清分。
shiping	object	是	物流信息对象。用于订单物流发货。
utm	object	是	用来做流量追踪和数据分析。

billing（账单信息对象）

字段	类型	必填	说明
email	string	是	邮箱。RFC 5322 约束；用于收据、风控。
phone	string	是	手机。含国家码或与 `country` 匹配；仅数字与 `+`。
firstName	string	是	名。英文字符，最长 64。
lastName	string	是	姓。英文字符，最长 64。
country	string	是	国家。建议用 ISO 3166-1 alpha-2（如 `US`）。
city	string	是	城市。
state	string	是	州 / 省。US / CA 建议使用二位缩写（如 `CA`）。
postalCode	string	是	邮编。US 支持 5 或 9 位（ZIP+4）；按国家规则校验。
address	string	是	账单地址行。地址行 1；用于 AVS。

shipping（物流地址信息）

字段	类型	必填
email	string	是
phone	string	是
firstName	string	是
lastName	string	是
country	string	是
city	string	是
state	string	是
postalCode	string	是
address	string	是

browserInfo（浏览器 / 设备信息）

字段	类型	必填	说明
userAgent	string	是	浏览器 UA。原始 UA；用于指纹与 3DS 风险评估。
ipAddress	string	是	客户端 IP。IPv4 / IPv6；建议与服务器观测 IP 做一致性比对。
colorDepth	integer	否	颜色深度。常见 24 / 30 / 32。
javaEnabled	boolean	否	Java 启用。设备画像字段。
javascriptEnabled	boolean	否	JS 启用。前端能力指示。
language	string	是	语言。约束：IETF BCP 47，如 `en-US`。
screenHeight	integer	否	屏幕高，像素值。
screenWidth	integer	否	屏幕宽，像素值。
timeZone	integer	否	本地时区偏移（分钟）。建议对齐 JS `getTimezoneOffset()` 语义：本地相对 UTC 的分钟偏移；如 UTC+8 为 `-480`。
browserName	string	否	浏览器名。解析自 UA；冗余传输。
os	string	否	操作系统。解析自 UA；冗余传输。

items（订单项目列表）

字段	类型	必填	说明
name	string	是	商品名。UTF-8，最长 256。
category	string	是	商品品类。自定义分类或对标标准类目，用于风控。
unitPrice	string	是	单价。仅支持整数格式（不带小数点）。金额单位使用最小货币单位（如美分），且必须大于零。
quantity	string	是	数量。正整数，≤ 99999。
totalPrice	string	是	小计。`unitPrice * quantity`。仅支持整数格式（不带小数点）。金额单位使用最小货币单位（如美分），且必须大于零。
currency	string	是	币种。必须等于顶层 `currency`。
image	array[string]	是	图片数组。
sku	string	是	SKU，例如 `Dress-White-M`、`Dress-Black-L`。
spec	string	是	规格，例如 `Color: White / Black；Size: M / L`。

shiping（物流信息对象）

字段	类型	必填	说明
email	string	是	邮箱。
phone	string	是	手机。含国家码或与 `country` 匹配；仅数字与 `+`。
firstName	string	是	名。英文字符，最长 64。
lastName	string	是	姓。英文字符，最长 64。
country	string	是	国家。建议用 ISO 3166-1 alpha-2（如 `US`）。
city	string	是	城市。
state	string	是	州 / 省。US / CA 建议使用二位缩写（如 `CA`）。
postalCode	string	是	邮编。
address	string	是	账单地址行。地址行。

utm（流量追踪信息）

字段	类型	必填	说明
utm_source	string	否	用户来源。
utm_medium	string	否	流量渠道。
utm_term	string	否	流量关键词。
utm_content	string	否	内容标识。

返回响应

响应结果处理说明：

当 success = false 时，表示本次接口调用失败，通常由于参数错误、签名错误、通道关闭或通道限额等原因。此时请直接读取并提示 error 字段中的错误信息。
当 success = true 时，表示接口调用成功，此时应根据 data.status 进行判定支付结果，如果失败请展示 failureMessage 失败原因。

顶层结构字段说明

字段	类型	示例值	说明
requestId	string	`75daa341-66fd-4d87-949b-28f7f0ef6d64`	本次通知的唯一追踪 ID，由服务端生成，用于日志追踪、链路排查与问题定位。每次通知通常唯一。
success	boolean	`true`	表示本次接口调用是否成功（接口层面）。`true` 表示通知调用成功并已返回业务结果；`false` 表示接口调用异常，如签名错误、参数缺失、权限拒绝、通道关闭等。
data	object	`{...}`	支付结果详情对象。当 `success = true` 时，商户应重点解析该对象中的业务字段。
timestamp	string (ISO 8601)	`2025-10-10T16:39:23.765+08:00`	通知生成时间，采用 ISO 8601 标准格式，包含毫秒与时区偏移。

data 对象字段说明（支付结果详情）

字段	类型	示例值	说明
id	string	`P1231823`	IntPay 平台交易号。用于标识平台侧唯一交易，可用于对账、查询与问题排查。
reference	string	`SAIDF01239-1230`	商户订单号或交易参考号，由商户系统生成，用于关联商户内部订单。
requiresAction	boolean	`false`	是否仍需用户执行额外操作。通常用于表示是否需要完成额外验证步骤（如 3DS、OTP 等）。
amount	number	`100`	支付金额，单位为最小货币单位。例如 USD 下 `100` 表示 `1.00 USD`。
currency	string	`USD`	支付币种，遵循 ISO 4217 三位字母代码标准。
failureMessage	string	`fail`	失败原因描述。当交易失败时返回；成功状态下通常为空、为 `null` 或被省略。
status	string	`FAILED`	当前订单状态枚举值，商户应以此字段作为订单状态更新依据。

nextAction（当 requiresAction = true 时返回）

字段	类型	示例值	说明
nextAction.type	string	redirect	操作类型
nextAction.url	string	https://3d.com	跳转地址
nextAction.method	string	GET	访问协议

状态枚举

状态值	说明	商户建议
`PENDING`	待处理。支付请求已创建，正在等待用户操作、发卡行响应或通道处理。	订单保持处理中，不要提前判定最终结果。
`REQUIRES_ACTION`	需要下一步操作。通常表示用户需完成额外验证，如 3D Secure、OTP 或其他身份校验。	引导用户继续完成验证流程，并等待后续结果通知。
`SUCCEEDED`	支付成功。发卡行授权通过，交易已成功完成。	将订单更新为成功，进入发货、入账或后续履约流程。
`FAILED`	支付失败。可能由于发卡行拒付、风控拦截、余额不足、卡信息错误或其他原因导致。	将订单更新为失败，并视业务需要记录失败原因。
`CANCELED`	已取消。订单被商户、用户或系统主动取消，通常未完成实际扣款。	将订单更新为已取消，结束本次支付流程。
`REFUND_PENDING`	退款处理中。退款请求已提交，正在等待银行或通道处理。	将订单更新为退款处理中，并等待后续通知。
`REFUNDED`	已退款。原支付金额已成功退回持卡人账户。	将订单更新为已退款，并同步售后或财务状态。
`REFUND_FAILED`	退款失败。退款请求被通道或银行拒绝，未完成退款。	保留原支付成功状态，并记录退款失败原因。
`CHARGEBACK`	拒付。持卡人已发起争议，款项可能被强制退回。	启动拒付处理流程，并同步风控、财务或客服系统。

不同支付产品或通道路由下，部分状态可能不会全部出现。
商户系统应至少完整兼容：PENDING、REQUIRES_ACTION、SUCCEEDED、FAILED、CANCELED、REFUNDED。

响应示例

付款成功

json

{
    "requestId": "b5cb20f9-6968-41ff-8e53-b1a9fc87a2b8",
    "success": true,
    "data": {
        "id": "P251011144163273295845",
        "reference": "R202512038",
        "status": "SUCCESS",
        "amount": 10000,
        "currency": "USD",
        "requiresAction": null,
        "nextAction": null,
        "failureMessage": null
    },
    "timestamp": "2025-10-11T14:41:23.406+08:00"
}

需要 3D

json

{
  "requestId": "d75ebc09-525d-41ef-9743-7135303ea47a",
  "success": true,
  "data": {
    "id": "P251011145346884900074",
    "reference": "R202512038",
    "status": "REQUIRES_ACTION",
    "amount": 10000,
    "currency": "USD",
    "requiresAction": true,
    "nextAction": {
      "type": "redirect",
      "url": "http://www.baidu.ccom",
      "method": "GET"
    },
    "failureMessage": null
  },
  "timestamp": "2025-10-11T14:53:13.672+08:00"
}

签名失败

json

{
  "success": false,
  "message": "invalid signature"
}

卡号不存在

json

{
  "requestId": "18836977-410f-41e4-be7c-02f2c39ffd5f",
  "success": true,
  "data": {
    "id": "P251011143910228479127",
    "reference": "R202512038",
    "status": "FAILED",
    "amount": 10000,
    "currency": "USD",
    "requiresAction": null,
    "nextAction": null,
    "failureMessage": "This card number does not exist"
  },
  "timestamp": "2025-10-11T14:39:27.906+08:00"
}

付款失败

json

{
    "requestId": "75daa341-66fd-4d87-949b-28f7f0ef6d64",
    "success": true,
    "data": {
        "reference": "SAIDF01239-1230",
        "requiresAction": false,
        "amount": 100,
        "currency": "USD",
        "id": "P1231823",
        "failureMessage": "Your card was declined. Please check with your bank or use a different card.",
        "status": "FAILED"
    },
    "timestamp": "2025-10-10T16:39:23.765+08:00"
}

支付接口 ​

📌 Overview ​

Endpoint ​

请求示例 ​

顶层字段 ​

billing（账单信息对象） ​

shipping（物流地址信息） ​

browserInfo（浏览器 / 设备信息） ​

items（订单项目列表） ​

shiping（物流信息对象） ​

utm（流量追踪信息） ​

返回响应 ​

响应示例 ​

付款成功 ​

需要 3D ​

签名失败 ​

卡号不存在 ​

付款失败 ​

支付接口

📌 Overview

Endpoint

请求示例

顶层字段

billing（账单信息对象）

shipping（物流地址信息）

browserInfo（浏览器 / 设备信息）

items（订单项目列表）

shiping（物流信息对象）

utm（流量追踪信息）

返回响应

响应示例

付款成功

需要 3D

签名失败

卡号不存在

付款失败