结账 API

Ask AI

创建一个结账会话，将您的买家重定向到 GLODIPAY 托管的付款页面，或返回一个可共享的付款链接。

接口地址 (Endpoint): POST /v2/checkout 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	要显示的付款方式。例如：checkout。请参阅 付款方式
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
connectionMode	String	O	API (默认) 或 DIRECT_POST。请参阅 连接模式
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"}]
paymentFilter	JSON	O	要从会话中排除的付款方式类型数组。例如：["card"]
paymentSorter	JSON	O	控制显示顺序的有序数组。例如：["checkout","card"]
feeBySeller	Number(0–100)	O	商户支付的处理费百分比。0 = 买家支付 100%。例如：50
billingFirstName	String(max:255)	O	账单名字。例如：John
billingLastName	String(max:255)	O	账单姓氏。例如：Doe
billingEmail	String(max:255)	O	买家电子邮件地址。例如：john.doe@example.com
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
billingCountry	String	O	ISO 3166-1 alpha-2 国家代码。例如：US。请参阅 国家代码
billingPostalCode	String(max:25)	O	邮政编码。例如：10001
billingPhoneCountryCode	String(max:10)	O	电话国家代码。例如：1（美国）
billingPhoneNumber	String(max:20)	O	电话号码。例如：5551234567
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)

connectionMode: API

字段	类型	描述
status	String	成功时为 created，失败时为 error
transactionId	String (ULID)	GLODIPAY 交易 ID
paymentLink	String	已签名的 URL —— 将买家重定向到此 URL 以完成付款
message	String	人类可读的消息

成功示例:

{
  "status": "created",
  "transactionId": "01jza90dy6w82dfrrqvadn5vs4",
  "paymentLink": "https://payment.gpayprocessing.com/v2/checkout/01jza90dy6w82dfrrqvadn5vs4?...",
  "message": "Payment Link created successfully"
}

错误示例:

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

connectionMode: DIRECT_POST

买家的浏览器被直接重定向到 GLODIPAY 托管的结账页面。您的服务器不会收到 JSON 响应。

---

回调 URL (Callback URL)

付款后，GLODIPAY 会使用 payload 查询参数对您的 callbackUrl 执行 GET 重定向：

GET {callbackUrl}?payload={base64-encoded-json}

解码后的 payload 字段：

字段	类型	描述
status	String	最终交易状态。请参阅 状态值
transactionId	String	GLODIPAY 交易 ID
ref	String	商户的 orderRef
amount	Float	发票金额
currency	String	货币代码
signature	String	RSA-MD5 签名 —— 使用 GLODIPAY 公钥验证

在信任 status 之前，务必验证回调 payload 中的 signature。使用交易查询 (Transaction Query) 接口获取完整的付款详情。

---

IPN 通知

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

---

交易查询 (Transaction Query)

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

---

来源

此页面派生自 GLODIPAY_Checkout_API_Specification_v2。