商户接口文档

接入规则与签名

所有接口都需要以下四个请求头。时间戳为 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 字段、改动空格或重新序列化请求体。

请求头示例中的时间戳、随机串和签名必须在每次请求时重新计算。三个完整代码样例会读取 JSON 文件的原始字节，签名与发送使用同一份字节。

请求头格式示例

POST /abcpay/wallet/balance HTTP/1.1
Content-Type: application/json; charset=UTF-8
Abcpay-Merchant: ABCDEMO001
Abcpay-Timestamp: <当前 Unix 秒>
Abcpay-Nonce: <本次生成的 16–64 位随机串>
Abcpay-Signature: <按原始请求体计算的 64 位十六进制签名>

{}

统一响应

{"requestId":"abc_0123456789abcdef0123456789abcdef","success":true,"error":null,"data":{}}

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

1. 代收下单

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

请求报文示例

{"merchantOrderNo":"C-20261013-001","channelCode":"COLLECTION_DEMO","amount":1500.00,"callbackUrl":"https://merchant.example/notify/collection","redirectUrl":"https://merchant.example/result"}

成功响应报文示例（HTTP 200）

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

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

2. 代付下单

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

请求报文示例

{"merchantOrderNo":"P-20261013-001","channelCode":"PAYOUT_DEMO","amount":100.00,"callbackUrl":"https://merchant.example/notify/payout","beneficiary":{"account":"000000000000","name":"TEST USER","ifsc":"ABCD0001234"}}

成功响应报文示例（HTTP 200）

{"requestId":"abc_0123456789abcdef0123456789abcdef","success":true,"error":null,"data":{"merchantOrderNo":"P-20261013-001","platformOrderNo":"PLATFORM-DEMO-001","orderState":"processing"}}

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

3. 查余额

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

请求报文示例

{}

成功响应报文示例（HTTP 200）

{"requestId":"abc_0123456789abcdef0123456789abcdef","success":true,"error":null,"data":{"merchantNo":"ABCDEMO001","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"}

成功响应报文示例（HTTP 200）

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

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

5. UTR 查询

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

请求报文示例

{"bankUtr":"123456789012"}

成功响应报文示例（HTTP 200，已命中）

{"requestId":"abc_0123456789abcdef0123456789abcdef","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 的路径部分。

ABCPAY 发给商户的请求报文示例

以下以商户地址 https://merchant.example/notify/collection 为例；请求头按上方签名规则实时生成。

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

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

商户返回给 ABCPAY 的响应报文示例（HTTP 200）

ACK

7. 代付回调

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

ABCPAY 发给商户的请求报文示例

以下以商户地址 https://merchant.example/notify/payout 为例。

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

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

商户返回给 ABCPAY 的响应报文示例（HTTP 200）

ACK

两类回调共同的确认规则

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

8. 订单查询

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

请求报文示例

{"businessType":"COLLECTION","merchantOrderNo":"C-20261013-001"}

成功响应报文示例（HTTP 200）

{"requestId":"abc_0123456789abcdef0123456789abcdef","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。

Java、PHP、Python 对接样例

以下三个单文件样例均可发送上面六个接口的签名请求，也可接收代收、代付回调并验签。先下载对应文件，设置环境变量；商户号与 API 密钥请使用自己账户中的真实值，切勿把密钥写入网页或提交到代码仓库。

export ABCPAY_MERCHANT='你的商户号'
export ABCPAY_API_KEY='你的 API 密钥'
export ABCPAY_BASE_URL='https://abc.yamipay.cc'

上述为 Linux/macOS shell 写法；CentOS 宝塔服务器可在终端使用。Windows PowerShell 请改用 $env:ABCPAY_MERCHANT='...' 等同名变量。接口域名按实际分配的接入地址设置。

将对应章节的请求 JSON 原样保存为 UTF-8 body.json，不带 BOM。程序会读取文件原始字节，签名和发送同一份内容。默认运行查余额，请求体固定为 {}；其他接口把路径和文件名作为参数传入。下单前须换成已开通的产品编码、唯一商户订单号和可访问的回调地址。回调演示服务监听本机 8080 端口，正式接收回调时需在宝塔站点配置 HTTPS 和对应路径的转发。

javac AbcpayExample.java
java AbcpayExample
java AbcpayExample /abcpay/collection/create body.json
java AbcpayExample serve

源码加载中…

php abcpay_example.php
php abcpay_example.php /abcpay/payout/create body.json
php -S 127.0.0.1:8080 abcpay_example.php

源码加载中…

python abcpay_example.py
python abcpay_example.py /abcpay/order/query body.json
python abcpay_example.py serve

源码加载中…

回调源码演示了验签和返回 ACK 的流程。接入真实业务时，应在返回 ACK 前按 noticeId 持久化、去重并完成业务处理；处理失败时返回非 2xx，等待平台重试。

错误处理

失败响应报文示例（HTTP 401）

{"requestId":"abc_0123456789abcdef0123456789abcdef","success":false,"error":{"code":"AUTH_SEAL","message":"签名无效"},"data":null}

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