商户接口文档

接入规则与签名

所有接口都需要以下四个请求头。时间戳为 Unix 秒，与服务端相差不超过 300 秒；随机串为 16–64 位英数字、下划线或短横线，同一商户 10 分钟内不可重复。

先对实际发送的原始请求体 UTF-8 字节求 SHA-256 小写十六进制值，再按下面六行拼接签名原文，行间仅使用换行符 \n，末尾不加换行。路径不含域名和查询串。空请求体使用空字符串的摘要。

ABCPAY-OPEN-1
POST
/abcpay/collection/create
{Abcpay-Timestamp}
{Abcpay-Nonce}
{SHA256_HEX(原始请求体)}

Abcpay-Signature = HMAC_SHA256_HEX(API密钥, 签名原文)。签名后不得重新排列 JSON 字段、改动空格或重新序列化请求体。

统一响应

{"requestId":"abc_示例请求标识","success":true,"error":null,"data":{...}}

失败时 success=false，error 包含 code 和 message；排查时提供 requestId。HTTP 状态码也反映失败类别。

1. 代收下单

POST /abcpay/collection/create。按已开通的代收产品创建订单，返回收银台地址及可用支付信息。

POST /abcpay/collection/create
{"merchantOrderNo":"C-20261013-001","channelCode":"示例代收产品编码","amount":1500.00,"callbackUrl":"https://merchant.example/notify/collection","redirectUrl":"https://merchant.example/result"}

{"requestId":"abc_...","success":true,"error":null,"data":{"merchantOrderNo":"C-20261013-001","paymentUrl":"https://...","upiText":"...","paymentLinks":[],"orderState":"processing"}}

paymentLinks 中每项包含 app、label、url。创建成功表示订单已受理，最终状态通过回调或订单查询确认。

2. 代付下单

POST /abcpay/payout/create。按已开通的代付产品发起出款。

POST /abcpay/payout/create
{"merchantOrderNo":"P-20261013-001","channelCode":"示例代付产品编码","amount":100.00,"callbackUrl":"https://merchant.example/notify/payout","beneficiary":{"account":"000000000000","name":"TEST USER","ifsc":"ABCD0001234"}}

{"requestId":"abc_...","success":true,"error":null,"data":{"merchantOrderNo":"P-20261013-001","platformOrderNo":"...","orderState":"processing"}}

受理状态不是到账证明。请以终态回调或订单查询为准。

3. 查余额

POST /abcpay/wallet/balance。请求体使用 {}；签名必须包含实际发送的请求体。

{"requestId":"abc_...","success":true,"error":null,"data":{"merchantNo":"ABC-示例商户号","balance":0.00,"availableBalance":0.00,"frozenBalance":0.00,"currency":"INR"}}

balance 为总余额，availableBalance 为可用余额，frozenBalance 为冻结余额。

4. UPI 查询

POST /abcpay/upi/query。查询指定 UPI 是否已登记在 ABCPAY 的平台 UPI 名录中。

{"upiAddress":"merchant@bank"}
{"requestId":"abc_...","success":true,"error":null,"data":{"upiAddress":"merchant@bank","platformUpi":false}}

platformUpi=false 仅表示未命中平台名录，不能据此判断任意外部 UPI 的真实性或可收款状态。

5. UTR 查询

POST /abcpay/utr/query。仅查询当前商户可见的 UTR 记录；bankUtr 最多 50 字符。

{"bankUtr":"123456789012"}
{"requestId":"abc_...","success":true,"error":null,"data":{"bankUtr":"123456789012","matched":true,"merchantOrderNo":"C-20261013-001","orderAmount":1500.00}}

未命中时返回 matched=false，订单字段不出现。

6. 代收回调

代收成功后，ABCPAY 向建单时的 callbackUrl 发送 POST JSON。回调使用与商户请求相同的四个 Abcpay-* 请求头和签名算法；签名路径为商户回调 URL 的路径部分。

{"noticeId":"ABCNC123_completed","noticeType":"collection.success","merchantOrderNo":"C-20261013-001","requestedAmount":1500.00,"actualAmount":1500.00,"orderState":"completed","bankUtr":"123456789012","eventTime":1791820000}

noticeId 标识这笔订单的事件，重试时保持一致。商户应先验签，再按 noticeId 幂等处理。

7. 代付回调

代付状态变化时，ABCPAY 向该单的 callbackUrl 发送 POST JSON，签名规则与代收回调相同。

{"noticeId":"ABCNP456_completed","noticeType":"payout.status","merchantOrderNo":"P-20261013-001","platformOrderNo":"...","requestedAmount":100.00,"actualAmount":100.00,"orderState":"completed","bankUtr":"123456789013","eventTime":1791820000}

orderState 可能为 processing、completed、failed 或 returned；同一订单不同状态拥有不同 noticeId。商户需按订单状态处理，不能把收到回调等同于出款成功。

两类回调共同的确认规则

商户处理完成后返回 HTTP 2xx，响应体原始字节必须精确为 ACK，不能附加空格、换行、引号或 JSON 包装。其他响应会进入重试；回调可能重复，请按 noticeId 去重，并可用订单查询复核。

8. 订单查询

POST /abcpay/order/query。一个入口查询代收或代付订单，只返回当前商户名下的结果。

{"businessType":"COLLECTION","merchantOrderNo":"C-20261013-001"}
{"requestId":"abc_...","success":true,"error":null,"data":{"businessType":"COLLECTION","merchantOrderNo":"C-20261013-001","requestedAmount":1500.00,"actualAmount":1500.00,"orderState":"completed","bankUtr":"123456789012"}}

代付结果包含 businessType、merchantOrderNo、requestedAmount、orderState、bankUtr。状态统一使用 processing、completed、failed；代付另可能返回 returned。

错误处理

文中的商户号、产品编码、订单号、URL 和 UTR 均为示例，不可作为真实联调凭据。