跳到主要内容

商户接入文档

对接说明

两个功能:代收、代付。全部接口为 HTTPS + POST + JSON,接口地址 https://api.nickpay.net。你要写的只有签名、调接口、接通知三件事。

版本 v2.3 更新于 2026-11-02

通用约定

凭据与白名单

运营提供 merchant_no(商户号)与 api_secret(签名密钥,只展示一次), 并登记你的出口 IP。平台不登记默认回调地址:代收与代付的通知通常打到不同接收端,请每笔请求自带 notify_url。 平台推送的通知一律从 54.179.178.170 发出,接收端可据此做 IP 白名单(仍须验签)。

请求头

Content-Type: application/json,并设置自定义 User-Agent(如 MyShop/1.0)。

金额

一律字符串。请求传整数 VND("50000"),响应固定 2 位小数("50000.00")。

时间

expire_at、paid_at 为越南时间 UTC+7,格式 YYYY-MM-DD HH:mm:ss; timestamp 为 Unix 秒,与服务器相差超过 5 分钟拒绝。

响应外壳

{"code":"0000","msg":"success","data":{…},"sign":"…"},HTTP 恒为 200,看 code。

幂等

同一 merchant_order_no 参数一致的重复请求返回同一笔单;参数不一致返回 1005。 请求超时、返回 9999 或 HTTP 非 200 请用同一单号重发或查单,不要换单号。

签名

HMAC-SHA256,请求、响应、通知三个方向用同一个算法。

  1. 1

    取字段

    请求 JSON 第一层全部字段(不含 sign),去掉值为空字符串的。

  2. 2

    拼接

    按字段名 ASCII 升序拼成 k1=v1&k2=v2&…。

  3. 3

    HMAC

    sign = hex(HMAC_SHA256(拼接串, api_secret)),小写。

    响应验签:对 data 内的字段签。通知验签:对通知 JSON 去掉 sign 后的全部字段签。

sign.py
import hashlib, hmac

def sign(params: dict, secret: str) -> str:
    items = sorted(
        (k, v) for k, v in params.items()
        if k != "sign" and v != ""
    )
    raw = "&".join(f"{k}={v}" for k, v in items)
    return hmac.new(
        secret.encode(), raw.encode(), hashlib.sha256
    ).hexdigest()

# 通知验签
def verify_notify(body: dict, secret: str) -> bool:
    got  = body.get("sign", "")
    rest = {k: v for k, v in body.items() if k != "sign"}
    return hmac.compare_digest(got, sign(rest, secret))

# 响应验签:对 data 签,错误响应没有 sign
def verify_resp(resp: dict, secret: str) -> bool:
    return resp.get("code") == "0000" and \
        hmac.compare_digest(resp.get("sign", ""), sign(resp["data"], secret))

接口

代收三个,代付三个(加一个银行列表),户名查询(付费)一个,余额一个。请求都带 merchant_no、timestamp、sign。

POST /api/v1/pay/create pay_method 由运营告知(当前 BANK_QR)。 付款人四项传真实值。订单 60 分钟有效。

pay_type=URL:引导用户打开 pay_payload(平台收银台,整段原样使用); pay_type=QRCODE:把 pay_payload 渲染成二维码。按字段判断,不要写死。

请求
{
  "merchant_no":        "M1001",
  "merchant_order_no":  "ORD20260820001",  // ≤ 64
  "amount":             "50000",           // 整数 VND
  "currency":           "VND",             // 选填
  "pay_method":         "BANK_QR",
  "payer_name":         "NGUYEN VAN A",
  "payer_email":        "a@example.com",
  "payer_phone":        "0912345678",
  "payer_account_no":   "0123456789",
  "payer_account_type": "BANK",            // 选填,或 PHONE
  "user_id":            "U10086",          // 选填
  "notify_url":         "https://your.domain/nickpay/notify",  // 请每笔都传:本笔通知地址;不传则不推送通知、只能查单
  "timestamp":          "1755657600",
  "sign":               "9f8e...c1"
}
响应 data
{
  "order_no":          "P2408201234",
  "merchant_order_no": "ORD20260820001",
  "amount":            "50000.00",
  "currency":          "VND",
  "pay_type":          "URL",
  "pay_payload":       "https://api.nickpay.net/pay/P24...?t=...",
  "expire_at":         "2026-08-20 15:30:00"
}

错误码

code 为 0000 表示成功。HTTP 403 + 纯文本 error code: 1010 不是本接口错误,是安全防护拦了你的 User-Agent,换成自定义 UA 即可。

请求

1001 验签失败
1002 参数缺失或非法看 msg
1003 金额必须为整数 VND
1008 请求过期校准时钟
1009 IP 不在白名单联系运营登记

订单

1005 订单号重复且参数不一致代收 / 户名查询换新单号;代付先查单,原单 FAILED 才换单号
1006 支付方式不支持联系运营;户名查询:未配置查询价格
1007 订单不存在查单返回时:平台确实没有这笔单
1010 金额超出单笔限额msg 给出范围

商户与系统

1004 商户不存在或已停用
1012 可用余额不足代付:不够冻结;户名查询:不够一次查询费,未扣费
1013 代付:未开通联系运营
2001 渠道暂不可用稍后重试;户名查询未扣费,同号重试
9999 系统错误,结果未知下单 / 代付返回:同单号查单,不要换单号;户名查询返回:同号重发;查单返回:稍后重查

沙箱

代收下单请求多带 "sandbox": "1"(参与签名),其余不变:不产生真实支付, order_no 以 T 开头,pay_payload 是模拟收银台, 页面上点「模拟支付成功 / 失败」即触发与生产完全一致的通知;查单同样带 "sandbox": "1"。 T 开头的单号绝不能发货。沙箱不支持代付。

还有问题?

联调阶段的疑问直接找运营对接人确认。