服务器到服务器卡支付 API

Ask AI

直接从您的服务器提交卡详情以向买家收费，而无需将其重定向到外部付款页面。

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

此接口要求您的服务器符合 PCI DSS 标准，因为原始卡数据会流经您的系统。

---

请求参数 (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
cardNumber	String(12–19)	M	卡号。例如：4111111111111111
cardMonth	String	M	到期月份。例如：12
cardYear	String	M	到期年份（2 位数字）。例如：30
cardSecurityCode	String(3–4)	M	CVV / CVC。例如：123
billingFirstName	String(max:255)	M	账单名字。例如：John
billingLastName	String(max:255)	M	账单姓氏。例如：Doe
billingEmail	String(max:255)	M	买家电子邮件地址。例如：john.doe@example.com
billingStreet1	String(max:255)	M	账单街道地址第 1 行。例如：123 Main St
billingStreet2	String(max:255)	O	账单街道地址第 2 行。例如：Suite 4B
billingCity	String(max:255)	M	账单城市。例如：New York
billingState	String(2–255)	C	账单州/省。当 billingCountry 为 US 或 CA 时必填。例如：NY
billingCountry	String	M	ISO 3166-1 alpha-2 国家代码。例如：US。请参阅 国家代码
billingPostalCode	String(max:25)	M	邮政编码。例如：10001
billingPhoneCountryCode	String(max:10)	O	电话国家代码。例如：1（美国）
billingPhoneNumber	String(max:30)	M	电话号码。例如：5551234567
customerIp	String	M	客户的 IP 地址。例如：203.0.113.42
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
websiteUrl	String(max:300)	O	商户网站 URL。例如：https://yoursite.com
expiresAt	String	O	ISO 8601 格式的会话过期时间。默认值：24 小时。例如：2026-04-22T10:00:00+00:00
browserDetails	JSON	M	浏览器指纹。请参阅 browserDetails 对象
signature	String(max:750)	M	RSA-MD5 签名。请参阅 签名

M = 必填 (Mandatory)，O = 可选 (Optional)，C = 条件必填 (Conditional)

---

browserDetails 对象

每个 S2S 卡片请求都必须提供。可以作为 JSON 对象（嵌套）或 JSON 编码的字符串提交。键使用下表所列的 snake_case；camelCase 也会被自动规范化。

字段	类型	是否必填	描述
accept_header	String	M	浏览器 Accept 标头
screen_width	String	M	以像素为单位的屏幕宽度
screen_height	String	M	以像素为单位的屏幕高度
screen_color_depth	String	M	以位为单位的屏幕颜色深度
window_width	String	M	以像素为单位的视口宽度
window_height	String	M	以像素为单位的视口高度
language	String	M	浏览器语言。例如：en-US
java_enabled	String	M	"true" 或 "false"
user_agent	String	M	浏览器用户代理字符串
time_zone	String	M	与 UTC 的时差（以小时为单位）。例如：7 表示 UTC+7
time_zone_name	String	M	IANA 时区名称。例如：Asia/Ho_Chi_Minh

JavaScript 代码段:

document.addEventListener('DOMContentLoaded', () => {
  const browserDetails = {
    accept_header: "{{ request()->header('Accept', 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8') }}",
    screen_width: window.screen.width.toString(),
    screen_height: window.screen.height.toString(),
    screen_color_depth: window.screen.colorDepth.toString(),
    window_width: String(window.innerWidth || document.documentElement.clientWidth || screen.width),
    window_height: String(window.innerHeight || document.documentElement.clientHeight || screen.height),
    language: navigator.language,
    java_enabled: 'false',
    user_agent: navigator.userAgent,
    time_zone: String(-new Date().getTimezoneOffset() / 60),
    time_zone_name: Intl.DateTimeFormat().resolvedOptions().timeZone
  };

  document.getElementById('browserDetails').value = JSON.stringify(browserDetails, null, 2);
});

---

响应 (Response)

此接口的所有响应均由网关包装：

{ "status": "...", "message": "...", "data": { ... } }

成功 (不需要 3DS)

{
  "status": "success",
  "message": "The transaction has been successfully completed.",
  "data": {
    "transactionId": "01jwz13qfcx4z61ded3jcj0tf2"
  }
}

需要 3DS 认证

{
  "status": "redirect",
  "message": "Please redirect the user to complete the payment.",
  "data": {
    "transactionId": "01jwz0ty1640apxvmyzqpvc18a",
    "url": "https://payment.gpayprocessing.com/card/3ds/01jwz0ty1640apxvmyzqpvc18a"
  }
}

将买家重定向到 data.url 以完成 3DS。验证后，GLODIPAY 处理交易并通过 IPN 将结果发送到 notificationUrl 并将买家重定向到 callbackUrl。

处理中 (Pending)

{
  "status": "pending",
  "message": "pending",
  "data": {
    "transactionId": "01jwz0ty1640apxvmyzqpvc18a"
  }
}

验证错误 (HTTP 422)

{
  "status": "error",
  "message": "Invalid request data.",
  "errors": [
    {
      "field": "billingEmail",
      "message": ["账单电子邮件字段是必填的。"]
    }
  ]
}

处理错误 (HTTP 400/500)

{
  "status": "error",
  "message": "No payment provider could process this transaction. Please try again or contact support.",
  "data": {
    "transactionId": "01jwz0ty1640apxvmyzqpvc18a"
  }
}

---

自动层叠 (Auto-Cascade)

当商户账户启用该功能时，网关会在返回最终响应之前，按照优先级顺序在所有活动 PSP 中自动重试扣款。在层叠过程中，单个 PSP 的失败将被屏蔽 —— 仅返回并发送最终结果。

---

IPN 通知

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

---

交易查询 (Transaction Query)

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

---

来源

此页面派生自 GLODIPAY_Server_To_Server_API_Specification_v2。