NAV
Português

系统描述

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

相关术语

平台

平台是指提供支付能力的我司系统。

商户

商户是指接入平台的使用者。

商户号

商户号是商户在交易平台的唯一标识,是用来判断商户在平台合法性的唯一条件。

商户私钥

商户私钥是商户在进行交易请求前,对数据做加密验签使用的密钥。是平台验证商户交易请求合法性的唯一判断条件,商户应当妥善保管加密密钥,如有泄露,应及时联系平台进行处理,避免不必要的损失。

后台异步回调

系统在接收到交易数据处理完成后,交易系统主动发起通知给商户的网站,同时携带处理完成的结果信息反馈给商户网站

币种

币种是平台用来区分货币类型的字段,具体描述见接口描述。

支付类型

支付类型是平台用来区分支付产品类别的字段,具体描述见接口描述

商户订单号

商户订单号是有商户系统每生成一笔订单会产生的一个唯一标识该笔订单的号码,商户必须保证订单号的唯一性

协议规范与规则

传输方式:采用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秒起至现在的毫秒数。

回调与接口响应

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

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

举例:

  1. 接口正常响应时,只对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"}
  2. 回调通知时,对请求body中整个json字符串进行hmacSHA256签名,无排序
  3. 校验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 系统错误,请联系客服