IPN 通知

GLODIPAY 通过 即时付款通知 (Instant Payment Notification - IPN) 将实时付款结果传送到您的服务器 —— 即向您在创建交易时提供的 notificationUrl 发送 HTTP POST 请求。

方法: POST
Content-Type: application/json

重试策略: 如果您的服务器未在 30 秒 内响应 {"returnCode":"100"}，GLODIPAY 将重试发送。您的处理程序应该是幂等的 —— 同一个通知可能会被多次传送。

什么会触发 IPN: 任何向终端或重要状态的转换：successful、failed、error、refund_successful、refund_failed、void_successful 等。

Payload 字段

字段	类型	是否必填	描述
merchantId	String	M	商户 ID
transactionId	String	M	GLODIPAY 交易 ID (ULID)
transactionNumber	String	M	GLODIPAY 人类可读的交易编号
ref	String	M	商户的 `orderRef`
currency	String	M	ISO 4217 货币代码
amount	Float	M	发票金额
paidAmount	Float	O	实际向买家收取的金额（包括买家费用）
settlementAmount	Float	O	结算给商户的金额
estimationSettlementAt	ISO 8601 datetime	O	预计结算日期时间
fees	JSON	O	费用明细。请参阅下方的 fees 对象
status	String	M	交易状态。请参阅状态值
statusCode	Number	M	数字状态码。请参阅状态码
metadata	JSON	O	原始结账会话中的键值对
transactionDocuments	JSON	O	原始会话中的辅助文档
paymentMethodDetails	JSON	O	所使用的付款方式。请参阅下方的 paymentMethodDetails 对象
message	String	O	人类可读的状态消息
descriptor	String	O	交易描述符
transactionCreatedAt	ISO 8601 datetime	M	GLODIPAY 系统中的交易创建时间
originalTransactionCreatedAt	ISO 8601 datetime	M	支付渠道侧的交易创建时间
signature	String	M	RSA-MD5 签名 —— 使用 GLODIPAY 公钥验证。请参阅签名

fees 对象

字段	类型	描述
buyer	Float	面向买家的费用金额
seller	Float	商户费用金额
rolling	Float	滚动保证金金额
operate	Float	总运营费用（渠道商 + GLODIPAY + 合作伙伴）
estimationRollingReleaseAt	ISO 8601 datetime	预计滚动保证金释放日期时间

paymentMethodDetails 对象

字段	类型	描述
displayName	String	向买家显示的付款方式标签
group	String	付款方式组类型
family	String	付款方式系列类型
type	String	付款方式类型（例如 `card`、`wallet`）
`{type}`	JSON	可选。付款方式特定的详情。键名等于 `type` 的值。目前仅在提供卡详情的卡支付中存在。请参阅下方的 card 对象

card 对象 (`paymentMethodDetails.card`)

字段	描述
name	持卡人姓名
firstSixDigits	卡号的前 6 位 (BIN)
lastFourDigits	卡号的后 4 位
expiryMonth	到期月份 (MM)
expiryYear	到期年份 (YY)
type	卡品牌（`visa`、`mastercard`、`amex`、`jcb` 等）
issuer	发卡行名称 (取决于渠道商)
issuerCountryCode	发卡行的 ISO 3166-1 alpha-2 国家代码 (取决于渠道商)
funding	卡资金类型：`credit`、`debit` 或 `prepaid` (取决于渠道商)
authorizationCode	发卡行的授权码 (取决于渠道商)
clientIP	付款时的客户 IP 地址 (取决于渠道商)
checks	AVS/CVC 验证结果对象 (取决于渠道商)
threeDSecure	3D Secure 认证详情对象 (取决于渠道商)

checks 对象字段（存在时）：

字段	描述
addressLine1Check	AVS 地址第 1 行检查结果
addressPostalCodeCheck	AVS 邮政编码检查结果
cvcCheck	CVC/CVV 检查结果

threeDSecure 对象字段（存在时）：

字段	描述
authFlow	所使用的认证流程
eci	电子商务指标 (Electronic Commerce Indicator)
result	3DS 认证结果
version	3DS 协议版本

IPN Payload 示例 (成功的卡支付)

{
  "merchantId": "1100000123",
  "transactionId": "01jza90dy6w82dfrrqvadn5vs4",
  "transactionNumber": "2604-1713100800",
  "ref": "ORDER-001",
  "currency": "USD",
  "amount": 100.00,
  "paidAmount": 105.00,
  "settlementAmount": 95.00,
  "estimationSettlementAt": "2026-04-16T00:00:00+00:00",
  "fees": {
    "buyer": 5.00,
    "seller": 5.00,
    "rolling": 2.00,
    "operate": 3.00,
    "estimationRollingReleaseAt": "2026-05-14T00:00:00+00:00"
  },
  "status": "successful",
  "statusCode": 6,
  "paymentMethodDetails": {
    "displayName": "Credit / Debit Card",
    "group": "card",
    "family": "card",
    "type": "card",
    "card": {
      "name": "John Doe",
      "firstSixDigits": "411111",
      "lastFourDigits": "1111",
      "expiryMonth": "01",
      "expiryYear": "30",
      "type": "visa",
      "issuer": "Example Bank",
      "issuerCountryCode": "US",
      "funding": "credit",
      "authorizationCode": "ABC123"
    }
  },
  "metadata": { "orderId": "12345" },
  "message": null,
  "descriptor": "GLODIPAY*ORDER-001",
  "transactionCreatedAt": "2026-04-14T10:00:00+00:00",
  "originalTransactionCreatedAt": "2026-04-14T10:00:01+00:00",
  "signature": "base64-encoded-rsa-signature"
}

确认响应

您的服务器必须在 30 秒 内返回以下 JSON。任何其他响应或超时都将被视为传送失败，GLODIPAY 将重试。

{
  "returnCode": "100",
  "description": "Received"
}

字段	类型	是否必填	描述
returnCode	String	M	必须为 `"100"` 以确认收到
description	String(max:1500)	O	可选描述

退款 IPN

退款通知使用与原始交易相同的 notificationUrl。Payload 格式有所不同 —— 请参阅退款 API 了解退款特定的 IPN Payload 字段。

Payload 字段​

fees 对象​

paymentMethodDetails 对象​

card 对象 (paymentMethodDetails.card)​

IPN Payload 示例 (成功的卡支付)​

确认响应​

退款 IPN​

Bookmarks