系统描述

本文档规定了接入支付系统使用的报文接口，包括业务处理流程、接口的通信方式、交易报文格式说明等。本文档是面向具有一定开发能力，了解相关计算机语言的接口对接开发、维护和管理人员。

协议规范与规则

传输方式：采用HTTPS传输

提交方式：POST

内容类型：application/json

字符编码：UTF-8

下行签名校验：HMAC(sha256,json_str, secretKey) == header(PAY-SIGN) ;用于校验平台返回的数据签名

上行鉴权校验: HMAC(sha256,json_str, secretKey) == header(PAY-ACCESS-SIGN)

交易金额：默认巴西雷亚尔，入参（请求）两位小数

时间参数：均使用精确到毫秒的13位时间戳，如：1622016572190。时间戳具体是指从格林尼治时间1970年01月01日00时00分00秒起至现在的毫秒数。

回调与接口响应

接口正常交互时，接口会在header返回PAY-SIGN
通知回调地址时，会在header传递PAY-SIGN

签名对json对象原始字符串进行hmacSHA256签名，无排序

举例：

接口正常响应时，只对data的json对象签名
- 返回示例：{"code":200,"msg":"SUCCESS","data":{"certImgUrl":"","createdAt":1730785433449,"mchTradeNo":"TEST_ORDER_1234567877884466","state":"SUCCESS","tradeNo":"O1853674577155104768"}}
- 以上述返回为例，只对这一部分签名 {"certImgUrl":"","createdAt":1730785433449,"mchTradeNo":"TEST_ORDER_1234567877884466","state":"SUCCESS","tradeNo":"O1853674577155104768"}
回调通知时，对请求body中整个json字符串进行hmacSHA256签名，无排序
校验hmac(sha256, jsonString , secretKey) == header(PAY-SIGN)

接口鉴权

签名说明

使用参数签名调用接口示例：

curl --request POST \
     --url ${HOST}/api/v1/account/balance \
     --header 'PAY-ACCESS-MCHNO: YourMchNo' \
     --header 'PAY-ACCESS-TIMESTAMP: 1733712250562' \
     --header 'PAY-ACCESS-SIGN: 22582bd0cff14c41edbf1ab98506286d' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{"currency":"BRL","reqTime":1733712250562}'

发起请求：

所有REST私有请求头都必须包含以下内容：

PAY-ACCESS-MCHNO 字符串类型的mchNo商户号。

PAY-ACCESS-TIMESTAMP 发起请求的毫秒时间戳（UTC时区），如： 1733712250562

PAY-ACCESS-SIGN 使用HMAC SHA256哈希函数获得哈希值，字母都小写。

所有请求都应该含有application/json类型内容，并且是有效的JSON。

签名：

PAY-ACCESS-SIGN 的请求头是对timestamp + body字符串（+表示字符串连接），以及SecretKey，使用HMAC SHA256方法加密而得到的（签名字符串的字母都小写）。

如：sign=CryptoJS.HmacSHA256(timestamp + '{"currency":"BRL","amount":"1.23","reqTime":1733712250562}', SecretKey)

注意：json字符串不需要排序，body传什么就拼接签名什么

其中，timestamp的值与PAY-ACCESS-TIMESTAMP请求头相同，为毫秒时间戳格式，如： 1733712250562

body是指请求主体的字符串（body不需要排序，body传什么就拼接签名什么），如果请求没有主体则body可省略。如： {"currency":"BRL","amount":"1.23","reqTime":1733712250562}

账户接口

查询账户余额

请求URL：/api/v1/account/balance

请求方式：POST

请求类型：application/json

请求示例

{
    "currency": "BRL",
    "reqTime": 1726306060918
}

请求参数

参数名	类型	必传	描述
currency	String	是	货币编码
reqTime	long	是	请求接口时间,13位时间戳

返回示例

{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "balance": "1001500060",
        "currency": "BRL",
        "frozenBalance": "0",
        "settlementBalance": ""
    }
}

返回参数

参数名	类型	必传	描述
balance	String	是	余额
frozenBalance	String	是	冻结余额
settlementBalance	String	是	结算中余额,在支付完成、代付退款完成后一分钟内同步到余额帐户"balance"
currency	String	是	三位货币代码,巴西币 BRL

支付接口

支付下单

请求URL：/api/v1/charge

请求方式：POST

请求类型：application/json

请求示例

{
  "amount": "9.99",
  "debtorDocumentNumber": "40959375805",
  "mchTradeNo": "TEST_ORDER_1727702220746947",
  "subject": "ThisIsOrderTitle",
  "notifyUrl": "https://www.xxx.com/notify",
  "debtorName": "tom",
  "currency": "BRL",
  "reqTime": 1727702220747,
  "body": "ThisIsOrderDesc"
}

请求参数

参数名	类型	必填	描述
mchTradeNo	String	是	商户生成的订单号，请确保唯一性
amount	String	是	订单金额（2位小数）
subject	String	是	标题，禁止出现标点符号，特殊符号，可能影响商户交易成功率
body	String	是	内容描述，禁止出现标点符号，特殊符号，可能影响商户交易成功率
currency	String	是	货币类型
notifyUrl	String	否	我方通知商户接收交易结果地址，需返回SUCCESS确定接收成功，传值才会发起回调
debtorName	String	否	付款人姓名
debtorDocumentNumber	String	否	付款人文件编号,填写CPF号
reqTime	long	是	请求接口时间,13位时间戳

返回示例

{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "mchTradeNo": "TEST_ORDER_12377022220746947",
        "payUrl": "http://pay.fakeurl.com?data=T3ZmZjZhd0tqQU1oVHpuYWJ=",
        "qrcode": "00020101021226820014br.gov.bcb.pix2560pix-h.fakebank.com.br/v2/cob/vcharge2eef46e0135044e195f7a6a7e5204000053039865802BR5907DELBANK6007ARACAJU62070503***Zi6nNaOi",
        "state": "PENDING",
        "tradeNo": "I1853319512628174848"
    }
}

返回参数

参数名	类型	必传	描述
tradeNo	String	是	平台支付订单号
mchTradeNo	String	是	商户传入的订单号
state	String	是	订单状态
payUrl	String	否	支付页,用于用户扫码支付的中间页
qrcode	String	否	支付代码,巴西支付使用的支付代码

查询支付订单

请求URL：/api/v1/charge/query

请求方式：POST

请求类型：application/json

请求示例

{
    "tradeNo": "I1726294720789M1726283265RJ27G",
    "mchTradeNo": "TEST_ORDER_123456789000004",
    "reqTime": 1726295520933
}

请求参数

参数名	类型	必传	描述
tradeNo	String	是	平台生成的订单号，与mchTradeNo二者传一即可,两者都传只认平台订单号
mchTradeNo	String	是	商户生成的订单号，与tradeNo二者传一即可
reqTime	long	是	请求接口时间,13位时间戳

返回示例

{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "amount": "9.99",
        "body": "ThisIsOrderDesc",
        "createdAt": 1730549791449,
        "currency": "BRL",
        "endToEndId": "E3822485720241106084751cn8ixlTCV",
        "mchNo": "M1726975515",
        "mchTradeNo": "TEST_ORDER_1727123220746941",
        "payUrl": "http://pay.fakeurl.com?data=T3ZmZjZGbEQyYz0=",
        "qrcode": "00020101021226820014br.gov.bcb.pix2560pix-h.fakebank.com.br/v2/cob/vcharge2eef46e0135044e195f7a6a7e5204000053039865802BR5907DELBANK6007ARACAJU62070503***4HE9yz8U",
        "state": "PENDING",
        "subject": "ThisIsOrderTitle",
        "successTime": 0,
        "tradeNo": "I1852686224167313408",
        "ext": "{\"sender_name\":\"xxx\",\"sender_document_number\":\"\"}",
        "refund": [
            {
                "refundNo": "",
                "refundOutOo": "",
                "refundAmount": "",
                "refundTime": 0
            }
        ]
    }
}

返回参数

参数名	类型	必传	描述
tradeNo	String	是	平台支付订单号
mchTradeNo	String	是	商户传入的订单号
amount	String	是	订单金额
currency	String	是	货币代码,三位货币代码,巴西币：BRL
endToEndId	String	是	银行流水号
state	String	是	订单状态
subject	String	是	商品标题
body	String	是	商品描述
createdAt	long	是	订单创建时间,13位时间戳
successTime	long	否	订单支付成功时间,13位时间戳
refund	array	否	退款记录
payUrl	String	是	支付中间页
qrcode	String	是	二维码内容
ext	String	是	根据业务单独解释

refund内容

参数名	类型	必传	描述
refundNo	String	是	退款单号
refundOutOo	String	是	商户退款单号
refundAmount	String	是	退款金额
refundTime	long	是	13位时间戳

ext内容

参数名	类型	必传	描述
sender_name	String	是	付款人姓名
sender_document_number	String	是	付款人文件编号

state字段说明:

state	描述
SUCCESS	支付成功
PENDING	交易创建，等待付款
REFUND	退款

支付通知

请求URL：该链接是通过统一下单接口提交的参数notifyUrl设置，如果无法访问链接，商户系统将无法接收到支付中心的通知。

请求方式：POST

请求类型：application/json

签名: header : PAY-SIGN

推送及时性: 默认及时,200 QPS

通知示例

{
  "mchNo": "M1729578167",
  "tradeNo": "I1853326882515230720",
  "mchTradeNo": "TEST_ORDER_1727222253166090",
  "amount": "10.12",
  "endToEndId": "E3822485720241106084751cn8ixlTCV",
  "payAmount": "10.12",
  "accountNo": "12345678901",
  "currency": "BRL",
  "subject": "ThisIsOrderTitle",
  "body": "ThisIsOrderDesc",
  "state": "SUCCESS",
  "createdAt": 1726298412000,
  "successTime": 1726298412000,
  "ext": "{\"sender_name\":\"xxx\",\"sender_document_number\":\"\"}",
  "refund": [
    {
      "refundNo": "",
      "refundOutOo": "",
      "refundAmount": "",
      "refundTime": ""
    }
  ]
}

通知参数

参数名	类型	必传	描述
tradeNo	String	是	平台支付流水号
mchNo	String	是	平台标识编码
mchTradeNo	String	是	商户传入的订单号
amount	String	是	订单金额
endToEndId	String	是	银行流水号
payAmount	String	是	实际付款金额
accountNo	String	是	收款帐户
currency	String	是	币种编码
subject	String	是	商品标题
body	String	是	商品描述
state	String	是	支付订单状态 SUCCESS-支付成功 PENDING-支付中 REFUND-已退款
createdAt	long	是	订单创建时间,13位时间戳
successTime	long	否	订单支付成功时间,13位时间戳
refund	Array	是	退款记录数组
ext	String	是	根据业务单独解释

商户返回结果

需要对这整个 JSON 字符串进行签名验签 hmac(sha256, jsonString , secretKey) == header("PAY-SIGN")

ext内容

参数名	类型	必传	描述
sender_name	String	是	付款人姓名
sender_document_number	String	是	付款人文件编号

state字段说明:

state	描述
SUCCESS	支付成功
PENDING	交易创建，等待付款
REFUND	退款

代付接口

代付下单

商户业务系统通过转账接口发起转账申请。

请求URL：/api/v1/transfer

请求方式：POST

请求类型：application/json

请求示例

{
    "amount": "3.12",
    "mchTradeNo": "TEST_ORDER_123456789000008",
    "accountNo": "+5579999999999",
    "accountType": "PHONE",
    "identityNo": "40959375805",
    "transferDesc": "test",
    "notifyUrl": "https://www.xxx.com/notify",
    "currency": "BRL",
    "reqTime": 1726306060918,
    "identityType": ""
}

请求参数

参数名	类型	必填	描述
mchTradeNo	String	是	商户生成的订单号，请确保唯一性
amount	String	是	代付金额(2位小数)即对方收款金额，实际扣款金额包含手续费可能大于此金额
currency	String	是	币种编码
accountNo	String	是	收款账号，有效pixKey列表： EVP: fc470f19-7a03-4f45-827f-6dc8cda78e68 Phone: +5541997586063(必须加区号,如+55) Email: xxxx@email.com Cnpj: 72723322000170 CPF: 40959375805
accountType	String	否	收款账号类型，有效列表： EVP PHONE EMAIL CNPJ CPF
identityNo	String	是	身份识别号，用于验证pixKey的持有者是否与提供的证件号码的持有者相同
transferDesc	String	否	转账描述信息
notifyUrl	String	否	异步通知地址
identityType	String	否	预留字段可不填
reqTime	long	是	请求接口时间,13位时间戳

返回示例

{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "accountNo": "3e35a0f8-89ed-45e5-ab66-d4ebc41b3560",
        "amount": "3.12",
        "mchTradeNo": "TEST_ORDER_123456789000008",
        "state": "PENDING",
        "tradeNo": "O1854838427334254592"
    }
}

返回参数

参数名	类型	必传	描述
mchTradeNo	String	是	商户生成的转账订单号
tradeNo	String	是	平台生成的转账单号
amount	String	是	代付金额
accountNo	String	是	收款账号，支付pixKey
state	String	是	转账状态

查询代付订单

请求URL：/api/v1/transfer/query

请求方式：POST

请求类型：application/json

请求示例

{
    "reqTime": 1726298455397,
    "tradeNo": "T1834854619749830658",
    "mchTradeNo": "xxxxxxxxxxx"
}

请求参数

参数名	类型	必填	描述
tradeNo	String	是	平台生成的代付单号，与mchTradeNo二者传一即可，都传时只认tradeNo
mchTradeNo	String	是	商户生成的代付单号，与tradeNo二者传一即可
reqTime	long	是	请求接口时间,13位时间戳

返回示例

{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "accountNo": "3e35a0f8-89ed-45e5-ab66-d4ebc41b3560",
        "amount": "20",
        "createdAt": 1730785433449,
        "currency": "BRL",
        "endToEndId": "E3822485720241106084751cn8ixlTCV",
        "failDesc": null,
        "mchTradeNo": "TEST_ORDER_1234567877884466",
        "refund": [
            {
                "refundAmount": "",
                "refundNo": "",
                "refundTime": 0
            }
        ],
        "state": "PENDING",
        "successTime": 0,
        "tradeNo": "O1853674577155104768",
        "transferDesc": "test"
    }
}

返回参数

参数名	类型	必传	描述
mchTradeNo	String	是	商户生成的代付订单号
tradeNo	String	是	平台生成的代付订单号
amount	String	是	转账金额
currency	String	是	货币编码
endToEndId	String	是	银行流水号
state	String	是	转账状态
accountNo	String	是	收款帐户,巴西支付pixKey
transferDesc	String	否	转账描述信息
createdAt	long	是	订单创建时间,13位时间戳
successTime	long	否	转账成功时间,13位时间戳
refund	array	否	退款记录
failDesc	String	否	错误描述

refund数据格式：

参数名	类型	必传	描述
refundAmount	String	否	退款金额，请校验实际退款金额，可能仅部分退款
refundNo	String	否	系统退款单号
refundTime	long	否	退款时间，毫秒时间戳

state字段说明：

state	描述
SUCCESS	交易完成
PENDING	下单成功等待结算转账
FAIL	转账执行失败(余额不足、账号无效等)
REFUND	退款

查询代付凭证

请求URL：/api/v1/transfer/cert/query

请求方式：POST

请求类型：application/json

请求示例

{
    "reqTime": 1726298455397,
    "tradeNo": "T1834854619749830658",
    "mchTradeNo": "xxxxxxxxxxx"
}

请求参数

参数名	类型	必填	描述
tradeNo	String(30)	是	平台生成的代付单号，与mchTradeNo二者传一即可，都传时只认tradeNo
mchTradeNo	String(30)	是	商户生成的代付单号，与tradeNo二者传一即可
reqTime	long	是	请求接口时间,13位时间戳

返回示例

{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "accountNo": "3e35a0f8-89ed-45e5-ab66-d4ebc41b3560",
        "amount": "20",
        "createdAt": 1730785433449,
        "currency": "BRL",
        "endToEndId": "E3822485720241106084751cn8ixlTCV",
        "mchTradeNo": "TEST_ORDER_1234567877884466",
        "recipientAccountBankCode": "",
        "recipientAccountBankIspb": "",
        "recipientAccountBankName": "",
        "recipientAccountBranch": "",
        "recipientAccountNumber": "",
        "recipientAccountType": "",
        "recipientDocumentNumber": "",
        "recipientName": "",
        "state": "PENDING",
        "successTime": 0,
        "tradeNo": "O1853674577155104768",
        "transferDesc": "test"
    }
}

返回参数

参数名	类型	必填	描述
mchTradeNo	String	是	商户生成的代付订单号
tradeNo	String	是	平台生成的代付订单号
amount	String	是	转账金额
currency	String	是	货币编码
state	String	是	转账状态
endToEndId	String	是	银行流水号
accountNo	String	是	收款帐户,巴西支付pixKey
transferDesc	String	否	转账描述信息
createdAt	long	是	订单创建时间,13位时间戳
successTime	long	否	转账成功时间,13位时间戳
recipientAccountBankCode	String	否	银行代码
recipientAccountBankIspb	String	否	银行ispb
recipientAccountBankName	String	否	银行名称
recipientAccountBranch	String	否	账户分支
recipientAccountNumber	String	否	账户号码
recipientAccountType	String	否	账户类型
recipientDocumentNumber	String	否	标识号码
recipientName	String	否	姓名

state字段说明：

state	描述
SUCCESS	交易完成
PENDING	下单成功等待结算转账
FAIL	转账执行失败(余额不足、账号无效等)
REFUND	退款

代付通知

请求URL：该链接是通过转账申请接口提交的参数notifyUrl设置，如果无法访问链接，商户系统将无法接收到支付中心的通知。

请求方式：POST

请求类型：application/json

签名： header: PAY-SIGN

推送及时性: 默认及时,200 QPS

通知示例数据

{
  "mchNo": "88000109",
  "tradeNo": "O1234567890987654321",
  "mchTradeNo": "TSTRORDER1234567890",
  "amount": "100",
  "accountNo": "12345678901",
  "currency": "BRL",
  "endToEndId": "E3822485720241106084751cn8ixlTCV",
  "state": "SUCCESS",
  "createdAt": 1726298412000,
  "successTime": 1726298412000,
  "refund": [
    {
      "refundNo": "",
      "refundAmount": "",
      "refundTime": "0"
    }
  ],
  "recipientAccountBankCode": "",
  "recipientAccountBankIspb": "16501555",
  "recipientAccountBankName": "STONE IP S.A.",
  "recipientAccountBranch": "0001",
  "recipientAccountNumber": "12345678",
  "recipientAccountType": "TRAN",
  "recipientDocumentNumber": "12345678901",
  "recipientName": "Tomás Moraes",
  "ext": ""
}

通知参数

参数名	类型	必填	描述
tradeNo	String	是	平台支付流水号
mchNo	String	是	平台唯一标识，即商户号
mchTradeNo	String	是	商户传入的订单号
amount	String	是	订单金额
endToEndId	String	是	银行流水号
accountNo	String	是	收款帐户
currency	String	是	币种编码
state	String	是	支付订单状态
createdAt	long	是	订单创建时间,13位时间戳
successTime	long	否	订单支付成功时间,13位时间戳
refund	array	否	退款记录
recipientAccountBankCode	String	是	银行简码
recipientAccountBankIspb	String	是	银行编号
recipientAccountBankName	String	是	银行名称
recipientAccountBranch	String	是	银行支行
recipientAccountNumber	String	是	银行帐号
recipientAccountType	String	是	银行帐号类型
recipientDocumentNumber	String	是	个人信息
recipientName	String	是	收据名称
ext	String	是	扩展字段，根据业务单独解释(订单状态(state)为FAIL时该字段为失败原因描述)

商户返回结果

需要对这整个 JSON 字符串进行签名验签 hmac(sha256, jsonString, secretKey) == header("PAY-SIGN")

state字段说明：

state	描述
SUCCESS	交易完成
PENDING	下单成功等待结算转账
FAIL	转账执行失败(余额不足、账号无效等)
REFUND	退款

refund数据格式：

参数名	类型	必传	描述
refundAmount	String	否	退款金额，请校验实际退款金额，可能仅部分退款
refundNo	String	否	系统退款单号
refundTime	String	否	退款时间，毫秒时间戳

沙箱支付

代收模拟支付

请求URL：/api/v1/sandbox/charge/simulatePayment

请求方式：POST、GET

请求类型：application/json

请求示例

{
    "tradeNo": "TEST_ORDER_1727222488355072"
}

请求参数

参数名	类型	必填	描述
tradeNo	String	是	系统订单号

返回示例

{
    "code": 200,
    "msg": "SUCCESS",
    "data": null
}

代付模拟成功

请求URL：/api/v1/sandbox/transfer/simulatePayment

请求方式：POST、GET

请求类型：application/json

请求示例

{
    "tradeNo": "TEST_ORDER_1727222488355072"
}

请求参数

参数名	类型	必填	描述
tradeNo	String	是	系统订单号

返回示例

{
    "code": 200,
    "msg": "SUCCESS",
    "data": null
}

代付模拟失败

请求URL：/api/v1/sandbox/transfer/simulatePaymentFail

请求方式：POST、GET

请求类型：application/json

请求示例

{
    "tradeNo": "TEST_ORDER_1727222488355072"
}

请求参数

参数名	类型	必填	描述
tradeNo	String	是	系统订单号

返回示例

{
    "code": 200,
    "msg": "SUCCESS",
    "data": null
}

代付模拟退款

请求URL：/api/v1/sandbox/transfer/refund/simulatePayment

请求方式：POST、GET

请求类型：application/json

请求示例

{
    "tradeNo": "TEST_ORDER_1727222488355072"
}

请求参数

参数名	类型	必填	描述
tradeNo	String	是	系统订单号

返回示例

{
    "code": 200,
    "msg": "SUCCESS",
    "data": null
}

接口状态码

The API uses the following error codes:

Code	提示	说明
200	SUCCESS	业务调用成功
400	Params error	参数异常
405	Invalid order no	业务条件不满足
429	Too many requests	请求过快
500	Internal service error	内部服务错误
1000	Merchant not exist or disabled	商户不存在或被禁用
1001	Invalid secret key	密钥错误
1002	IP is not on the whitelist	ip不在白名单
1003	Order repeat	商户订单号重复
1004	Create order failed	订单创建失败
1005	Order not exist	订单不存在
1006	Insufficient Balance	余额不足
1007	The order is non refundable	订单不可退款
1008	The refund amount is not correct	退款金额不正确
1011	Invalid notify url	无效回调通知url
1012	No notify URL whitelist configured	没有配置通知url白名单
1013	Wallet is less or disabled	钱包被禁或不存在
1014	The account triggers the risk control rule	该账户触发风控规则
1015	Invalid document number	无效debtorDocumentNumber（CPF/CNPJ）或debtorDocumentNumber与debtorName不匹配
1016	Invalid amount	无效金额
1100	Invalid timestamp	请求头`PAY-ACCESS-TIMESTAMP`时间戳过期或为空,请传入当前UTC时区的13位毫秒时间戳数字,且该值要参与签名
1101	Invalid mchNo	请求头`PAY-ACCESS-MCHNO`无效商户号
1102	Invalid Content-Type	请求头`Content-Type` 请使用“application/JSON”格式
1103	Invalid signature	请求头`PAY-ACCESS-SIGN`无效签名
2004	System error, please contact customer service	系统错误，请联系客服

系统描述

相关术语

平台

商户

商户号

商户私钥

后台异步回调

币种

支付类型

商户订单号

协议规范与规则

回调与接口响应

接口鉴权

签名说明

账户接口

查询账户余额

支付接口

支付下单

查询支付订单

支付通知

代付接口

代付下单

查询代付订单

查询代付凭证

代付通知

沙箱支付

代收模拟支付

代付模拟成功

代付模拟失败

代付模拟退款

接口状态码