iFrame 卡支付 API

Ask AI

创建一个会话，返回一个指向 GLODIPAY 托管的卡输入表单的签名 URL。将该 URL 嵌入到您页面的 <iframe> 中 —— 买家在托管表单中输入卡详情，而无需离开您的网站。

接口地址 (Endpoint): POST /v2/card/iframe Content-Type: application/json

---

请求参数 (Request Parameters)

字段	类型	是否必填	描述
merchantId	String(1–50)	M	商户 ID。例如：1100000123
orderRef	String(1–250)	M	每个商户唯一的交易引用。例如：ORDER-2026-001
amount	Float	M	发票金额。最小值：1。最多 2 位小数。例如：100.00
currency	String(3)	M	ISO 4217 货币代码。例如：USD
paymentMethod	String	M	必须为 card
callbackUrl	String(1–300)	M	付款成功后的重定向 URL。必须是 https。例如：https://yoursite.com/return
notificationUrl	String(1–300)	M	用于 IPN Webhook 的服务器端点。必须是 https。例如：https://yoursite.com/webhook
cancelUrl	String(1–300)	M	取消时的重定向 URL。必须是 https。例如：https://yoursite.com/cancel
errorUrl	String(1–300)	M	出错时的重定向 URL。必须是 https。例如：https://yoursite.com/error
billingEmail	String(max:255)	O	买家电子邮件地址。例如：john.doe@example.com
billingCountry	String	O	ISO 3166-1 alpha-2 国家代码。例如：US。请参阅 国家代码
billingFirstName	String(max:255)	O	账单名字。例如：John
billingLastName	String(max:255)	O	账单姓氏。例如：Doe
billingStreet1	String(max:255)	O	账单街道地址第 1 行。例如：123 Main St
billingStreet2	String(max:255)	O	账单街道地址第 2 行。例如：Suite 4B
billingCity	String(max:255)	O	账单城市。例如：New York
billingState	String(2–255)	O	账单州/省。例如：NY
billingPostalCode	String(max:25)	O	邮政编码。例如：10001
billingPhoneCountryCode	String(max:10)	O	电话国家代码。例如：1（美国）
billingPhoneNumber	String(max:20)	O	电话号码。例如：5551234567
orderDescription	String(max:3000)	M	订单的简短描述。例如：Order #2026-001
metadata	JSON	O	IPN 和查询响应中返回的键值对。例如：{"orderId":"12345"}
transactionDocuments	JSON	O	交易的辅助文档。例如：[{"type":"invoice","url":"https://yoursite.com/inv.pdf"}]
feeBySeller	Number(0–100)	O	商户支付的处理费百分比。0 = 买家支付 100%。例如：50
brandName	String(1–255)	O	覆盖卡表单上的品牌名称。例如：My Store
colorMode	String(1–255)	O	最多 3 种颜色，用 --- 分隔。接受颜色名称、HEX 或 RGBA。例如：#2e7d32---#e8f5e9---#81c784
logoSource	String(1–255)	O	覆盖卡表单上的 Logo。例如：https://yoursite.com/logo.png
customerIp	String	O	客户的 IP 地址。例如：203.0.113.42
websiteUrl	String(max:300)	O	商户网站 URL。例如：https://yoursite.com
expiresAt	String	O	ISO 8601 格式的会话过期时间。默认值：24 小时。例如：2026-04-22T10:00:00+00:00
signature	String(max:750)	M	RSA-MD5 签名。请参阅 签名

M = 必填 (Mandatory)，O = 可选 (Optional)

---

响应 (Response)

字段	类型	描述
status	String	成功时为 created，失败时为 error
transactionId	String (ULID)	GLODIPAY 交易 ID
url	String	托管卡输入表单的签名 URL —— 嵌入到 <iframe> 中
message	String	人类可读的消息

成功示例:

{
  "status": "created",
  "transactionId": "01jza90dy6w82dfrrqvadn5vs4",
  "url": "https://payment.gpayprocessing.com/v2/card-iframe/01jza90dy6w82dfrrqvadn5vs4?...",
  "message": "Iframe card created successfully"
}

错误示例:

{
  "status": "error",
  "transactionId": null,
  "url": null,
  "message": "No active payment service providers found. Please contact support."
}

---

嵌入 iFrame

收到 url 后，将其嵌入到您的页面中：

<iframe
  src="{url}"
  width="100%"
  height="600"
  frameborder="0"
  scrolling="no"
  allowtransparency="true">
</iframe>

URL 已签名并将在 expiresAt 到期。买家必须在会话有效期内完成付款。请勿在当前结账会话之外存储或共享该 URL。

---

IPN 通知

当交易达到终端状态时，GLODIPAY 会将付款结果发送到您的 notificationUrl。请参阅 IPN 通知 了解完整的 payload 和确认格式。

---

交易查询 (Transaction Query)

随时使用 POST /v2/checkout/query 检查交易状态。请参阅 交易查询。

---

来源

此页面派生自 GLODIPAY_iFrame_API_Specification_v2。