巴西支付API文档

关于回调：必读

1.收到支付成功回调后，订单金额以实际支付订单金额（orderActualAmount）为准。

2.重复回调：确认回调响应代码是否为{"code":200,"success":true}

3.IP加白操作：在客户端开发者中心 -> API KEY中的白名单输入框进行加白。

4.AccessKey无效：需将创建的AccessKey发送给技术客服进行二次加白。

5.IP受限：确认所有服务器IP和回调IP是否已完成加白。

1. 如何获取API Key

  用户登录收银台 -> 开发者中心 -> API Key -> 创建API key。API Key 都有单独的配置页，并绑定固定的 IP 地址（“0.0.0.0”表示不做 IP 拦截过滤，任何IP都可以访问），可配置不同的 API Key 满足不同的需求。请不要泄露您的 Access Key 及 Secret Key，以免造成资产损失。Secret Key 生成后将无法再次查看，请注意及时保存，如您忘记了 Secret Key，请在商户后台回收该密钥对并申请新的密钥对。

1.1 如何创建API KEY

• 点击开发者中心-API Key

• 1选择是否开启调试模式 ( 开启调试模式后，你有任何错误会有规范的提示信息和日志查看地址 ）

• 2选择API Key权限

• 3输入白名单地址 (0.0.0.0 表示任意IP地址可以访问)

注：( 输⼊⽩名单域名时应注意多个IP时用","隔离。)

• 4点击创建，可⽣成API KEY

(⽣成API KEY后可以在下⽅我的API KEY列表进⾏复制、查看、编辑和删除等操作，注意Secret key只在生成的时候出现一次，请妥善保存，如您忘记了Secret Key,请回收该密钥对并申请新的密钥对。)

• 点击编辑可关闭或开启【开始调试】及修改API Key权限和白名单地址，修改完成后点击保存即可

注意：创建或编辑API Key之后请耐心等待90秒API Key生效

2. 如何使用API Key

当前API Key是在请求的Header中添加参数列表

参数名	参数说明	类型	是否必须
access_key	Api Key 访问密钥 （如：TPhoa7ZQ）	String	是
timestamp	毫秒级时间戳（13位 如：1679669488472）	String	是
nonce	UUID（36位 如：02f7a04f-53cc-47d4-bb3f-fae69dab49ac） 五个部分分别为8个字符、4个字符、4个字符、4个字符、12个字符，中间用“-”号间隔	String	是
sign	参数签名 （如：GXx2wYUD6UVr+zcmeCSFFPzcBLA=）	String	是

3. 技术侧参数接入流程

4. 如何接口签名

签名说明

  API 请求在通过 internet 传输的过程中极有可能被篡改，为了确保请求未被更改，除公共接口（基础信息，行情数据等）外的私有接口均必须使用您的 API Key 做签名认证，以校验参数或参数值在传输途中是否发生了更改。

一个合法的请求由以下几部分组成：

• access_key： API 访问密钥；
• secret_key： 签名加密所使用的密钥（仅在后台申请 API Key 时可见一次，请复制保存在安全处，不可泄露）；
• timestamp： 您发出请求的时间 (UTC 时间) 。如：1632811287325（13位）。在查询请求中包含此值有助于防止第三方截取您的请求；
• nonce： 随机 UUID 字符串。如：053a1b81-48a0-4bb1-96b2-60f6e509d911（36位）；
• sign： 签名计算得出的值，用于确保签名有效和未被篡改；
• 所有接口都需要在http请求头 （header） 中传递以上除 secret_key 外的几个公共参数，公共参数包含（access_key ，timestamp，nonce，sign）其他涉及到签名参数以API接口说明为准 。

签名步骤

​ 1.定义一个 Map 字典类型对象，将请求中的参数以 key-value 的形式放入其中

​ 2.将 access_key、timestamp、nonce 也放入第一步定义的 Map 中

​ 3.将 Map 里面的属性按照 ASCII 码从小到大排序（字典序）并将 Map 转换输出为“key1=value1&key2=value2” 形式的字符串

​ 4.将上一步转换的字符串用 secret_key 进行 HMAC_SHA1 加密并进行 Base64 转码，得到 sign 参数值。secret_key 是在收银平台创建的 apikey 中的信息

​ 5.将 sign 值和其他所需参数加到请求头 header 中，发送请求目标接口

签名调试工具

• SignUtil: 用户登录收银台 -> 开发者中心 -> API 文档 -> 签名工具 打开签名工具页面 (工具中的access_key请使用有效的access_key 并且请设置允许这个access_key访问的IP白名单为 0.0.0.0,我们强烈推荐使用过的access_key调试完成后废弃)

• 

  

• 

5. 接口列表

5.1 测试接口连通性

请求方式

Get

请求URL

/ping

响应数据

{"version":"1.0.1","timestamp":1688116827306}

响应参数说明

Param	Type	Desc
version	String	返回该参数则本文档中所有接口都可正常请求
timestamp	int64	Unix时间戳

5.2 新建代收订单

请求方式

Post

请求URL

/api/v3/bra/createCollectingOrder

请求类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

请求头

Param	Desc	Sample
access_key	商户后台获取	pFqV75X3
timestamp	Unix时间戳13位 毫秒	1679724896223
nonce	UUID V4	794c26b0-d33c-4394-b2bb-c485eca16d9e
sign	计算出来的签名	kAXyh+eerqrefyaF8dyFB0M4FVo=

请求参数

{
	"amount": "21.1",
	"channelType": "PIX",
	"externalOrderId": "389508808434869257",
	"notifyUrl": "http://192.168.135:30002/abc",
	"remark": "123",
	"returnUrl": "http://192.168.135:30002/abc"
}

请求参数说明

Param	Desc	Sample	Require
amount	收款金额，小数点不能超过2位（String）	21.1	required
channelType	支付类型 oneof=PIX，PIX_DYNAMIC BOLETO（String）	PIX PIX_DYNAMIC BOLETO 三个参数根据实际情况选择一个	required
externalOrderId	商户订单号 max=64 （String）	389508808434869257	required
userInfoType	证件类型	CPF	optional
userInfoNo	证件号码	12312	optional
userInfoName	姓名	TEST	optional
notifyUrl	回调地址 （String，Url）	http://192.168.135:30002/abc	optional
remark	备注 max=255（String）	1312425	optional
returnUrl	返回地址 （String）	http://192.168.135:30002/abc	optional

响应类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

响应数据

{
	"code": "200",
	"success": true,
	"msg": "成功",
	"msgEn": "SUCCESS",
	"data": {
		"cashierCurrencyAmount": "21.1",
		"cashierExpireTime": 1690431343212,
		"cashierId": "OCURRPAID202307270345411690429541853DOCKER020000000200000775",
		"cashierUrl": "http://192.168.1.74:88/OCURRPAID202307270345411690429541853DOCKER020000000200000775?data=eyJjYXNoaWVyQ3VycmVuY3lBbW91bnQiOjIxLjEwLCJjYXNoaWVyRXhwaXJlVGltZSI6MTY5MDQzMTM0MzIxMiwiY2FzaGllcklkIjoiT0NVUlJQQUlEMjAyMzA3MjcwMzQ1NDExNjkwNDI5NTQxODUzRE9DS0VSMDIwMDAwMDAwMjAwMDAwNzc1IiwiY2FzaGllclVybCI6Imh0dHA6Ly8xOTIuMTY4LjEuNzQ6ODgvT0NVUlJQQUlEMjAyMzA3MjcwMzQ1NDExNjkwNDI5NTQxODUzRE9DS0VSMDIwMDAwMDAwMjAwMDAwNzc1IiwiY3VycmVuY3kiOiJCUkwiLCJjdXJyZW5jeU9yZGVyVm8iOnsiYW1vdW50IjoyMS4xMCwiY3VycmVuY3kiOiJCUkwiLCJleHRlcm5hbE9yZGVySWQiOiI4Mjg5MDU3NjA0MTE0NDk2MzUiLCJtZXJjaGFudE5hbWUiOiJhYXJvbiIsIm9yZGVySWQiOiJPQ1VSUlBBSUQyMDIzMDcyNzAzNDU0MzE2OTA0Mjk1NDM1MzFET0NLRVIwMjAwMDAwMDA0MDAwMDA3NzYiLCJvcmRlclN0YXR1cyI6IldhaXQgcGF5Iiwib3JkZXJTdGF0dXNDb2RlIjoxLCJvcmRlclRpbWUiOjE2OTA0Mjk1NDM1NzEsInBheVBhcmFtIjoiMDAwMjAxMDEwMjEyMjY1ODAwMTRCUi5HT1YuQkNCLlBJWDAxMzY3NDY5ZTVlNS1hZDViLTQzZDQtOWNmMC0wNzEyNWM4OWRkOGQ1MjA0MDAwMDUzMDM5ODY1NDA1MjEuMTA1ODAyQlI1OTI1TElRVUlETyBCUkwgUEFHQU1FTlRPUyBESTYwMTRCZWxvIEhvcml6b250ZTYxMDgzMDM4MDQwMzYyMjkwNTI1ZFdIMXlTaXVGd2R1dXJRcFAxd3Y3UlRvZjYzMDRCQzdBIiwicGF5VHlwZSI6MTAxLCJwYXlUeXBlTmFtZSI6IlBJWCIsInRyYWRlTm90ZSI6IjEyMyJ9LCJpc0NyZWF0ZU9yZGVyIjp0cnVlLCJwYXlUeXBlIjoxMDEsInJldHVyblVybCI6Imh0dHA6Ly8xOTIuMTY4LjEzNTozMDAwMi9hYmMiLCJ1c2VySW5mb05hbWUiOiJBbGlzaGEgTG92ZXRpbnNreSIsInVzZXJJbmZvTm8iOiIwMDgyODc2MTAwMCIsInVzZXJJbmZvVHlwZSI6IkNQRiIsInZlcnNpb24iOiJ2MSJ9\u0026pm=W3siY3VycmVuY3lUeXBlIjoiTVhOIiwicGF5VHlwZXMiOlt7ImNvZGUiOjEwMiwidmFsdWUiOiJCQU5LIn1dfSx7ImN1cnJlbmN5VHlwZSI6IlBFTiIsInBheVR5cGVzIjpbeyJjb2RlIjoxMDIsInZhbHVlIjoiQkFOSyJ9XX0seyJjdXJyZW5jeVR5cGUiOiJCUkwiLCJwYXlUeXBlcyI6W3siY29kZSI6MTAxLCJ2YWx1ZSI6IlBJWCJ9XX1d",
		"currency": "BRL",
		"currencyOrderVo": {
			"amount": "21.1",
			"currency": "BRL",
			"externalOrderId": "828905760411449635",
			"orderId": "OCURRPAID202307270345431690429543531DOCKER020000000400000776",
			"orderStatus": "Wait pay",
			"orderStatusCode": 1,
			"orderTime": 1690429543571,
			"payParam": "00020101021226580014BR.GOV.BCB.PIX01367469e5e5-ad5b-43d4-9cf0-07125c89dd8d520400005303986540521.105802BR5925LIQUIDO BRL PAGAMENTOS DI6014Belo Horizonte61083038040362290525dWH1ySiuFwduurQpP1wv7RTof6304BC7A",
			"payType": 101,
			"tradeNote": "123"
		},
		"isCreateOrder": true,
		"payType": 101,
		"returnUrl": "http://192.168.135:30002/abc",
		"userInfoName": "Alisha Lovetinsky",
		"userInfoNo": "00828761000",
		"userInfoType": "CPF",
		"payTypeCode": "PIX"
	}
}

响应参数说明

Param	Type	Desc
cashierCurrencyAmount	String	收款金额
cashierExpireTime	int64	过期时间
cashierId	String	收银台ID
cashierUrl	String	收银台链接
currency	String	币种编码 BRL
amount	String	收款金额
externalOrderId	String	商户订单号
orderId	String	系统订单ID
orderStatus	String	订单状态描述
orderStatusCode	int64	订单状态code 1-待支付 2-支付成功
orderTime	int64	订单时间
payParam	String	支付参数
tradeNote	String	交易备注
isCreateOrder	bool	是否已创建订单
payType	int64	支付类型 101-PIX
returnUrl	String	跳转地址
userInfoName	String	用户名称
userInfoNo	String	用户信息编号
userInfoType	String	用户信息类型
payTypeCode	String	支付类型code

5.3 新建代付订单 (PIX)

请求方式

Post

请求URL

/api/v3/bra/createTransferOrder

/api/v3/bra/pix/createTransferOrder

以上两个Url 任意一个即可

请求类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

请求头

Param	Desc	Sample
access_key	商户后台获取	pFqV75X3
timestamp	Unix时间戳13位 毫秒	1679724896223
nonce	UUID V4	794c26b0-d33c-4394-b2bb-c485eca16d9e
sign	计算出来的签名	kAXyh+eerqrefyaF8dyFB0M4FVo=

请求参数

{
	"currencyAmount": "20.01",
	"channelType": "PIX",
	"externalOrderId": "871049832638078444",
	"personIdType": "CPF",
	"personId": "18171847084",
	"personName": "bob",
	"accountType": "CPF",
	"accountId": "18171847684",
	"remark": "123",
	"notifyUrl": "http://192.168.1.135:30002/abc"
}

请求参数说明

注: 为了提高出款效率，下面参数列表建议用户全传

Param	Desc	Sample	Require
currencyAmount	代付金额 小数不能大于2位（String）	20.01	required
channelType	支付类型 oneof=PIX （String）	PIX	required
externalOrderId	商户订单号 max=64（String）	871049832638078444	required
personIdType	用户证件信息 oneof=CPF CNPJ（String）	CPF CNPJ 两个参数根据实际情况选择一个	required
personId	用户证件号（String）	18171847084	required
personName	用户姓名，max=255（String）	bob	required
accountType	银行账号类型 oneof=CPF CNPJ PHONE EMAIL EVP（String）	CPF CNPJ PHONE EMAIL EVP 五个参数根据实际情况选择一个	required
accountId	银行账号，参考accountType类型（String）	根据实际情况传递参数	required
remark	备注 max=255（String）	1312	optional
notifyUrl	通知URL（String）	http://192.168.1.135:30002/abc	optional

响应类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

响应数据

{
	"code": "200",
	"success": true,
	"msg": "成功",
	"msgEn": "SUCCESS",
	"data": {
		"currencyType": "BRL",
		"externalOrderId": "472512322065926592",
		"orderId": "OCURRDRAW202307270345461690429546358DOCKER020000000200000777",
		"orderStatus": "Accepted"
	}
}

响应参数说明

Param	Type	Desc
currencyType	String	法币类型
externalOrderId	String	商户订单id
orderId	String	系统订单ID
orderStatus	String	订单状态

5.4 新建代付订单(银行模式)

请求方式

Post

请求URL

/api/v3/bra/bank/createTransferOrder

请求类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

请求头

Param	Desc	Sample
access_key	商户后台获取	pFqV75X3
timestamp	Unix时间戳13位 毫秒	1679724896223
nonce	UUID V4	794c26b0-d33c-4394-b2bb-c485eca16d9e
sign	计算出来的签名	kAXyh+eerqrefyaF8dyFB0M4FVo=

请求参数

{
	"currencyAmount": "20.01",
    "channelType": "BANK",
	"externalOrderId": "871049832638078444",
	"personIdType": "CPF",
	"personId": "18171847084",
	"personName": "bob",
	"accountType": "CC",
	"accountId": "18171847684",
    "bankName":"Banco Keb Hana Do Brasil S.A.",
    "agency":"1",
	"remark": "123",
	"notifyUrl": "http://192.168.1.135:30002/abc"
}

请求参数说明

注: 为了提高出款效率，下面参数列表建议用户全传

Param	Desc	Sample	Require
currencyAmount	代付金额 小数不能大于2位（String）	20.01	required
channelType	支付类型 oneof=BANK（String）	BANK	required
externalOrderId	商户订单号 max=64（String）	871049832638078444	required
personIdType	用户证件信息 oneof=CPF CNPJ（String）	CPF CNPJ 两个参数根据实际情况选择一个	required
personId	用户证件号（String）	18171847084	required
personName	用户姓名，max=255（String）	bob	required
accountType	银行账号类型 oneof= CC CP （String）	CC CP 两个参数根据实际情况选择一个	required
bankName	银行名称(String)	Banco Keb Hana Do Brasil S.A.	required
agency	银行账户代理(String)	1	required
accountId	银行账号，参考accountType类型（String）	根据实际情况传递参数	required
remark	备注 max=255（String）	1312	optional
notifyUrl	通知URL（String）	http://192.168.1.135:30002/abc	optional

响应类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

响应数据

{
	"code": "200",
	"success": true,
	"msg": "成功",
	"msgEn": "SUCCESS",
	"data": {
		"currencyType": "BRL",
		"externalOrderId": "472512322065926592",
		"orderId": "OCURRDRAW202307270345461690429546358DOCKER020000000200000777",
		"orderStatus": "Accepted"
	}
}

响应参数说明

Param	Type	Desc
currencyType	String	法币类型
externalOrderId	String	商户订单id
orderId	String	系统订单ID
orderStatus	String	订单状态

5.5 查询代收订单

请求方式

Post

请求URL

/api/v3/bra/query/collectingOrder

请求类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

请求头

Param	Desc	Sample
access_key	商户后台获取	pFqV75X3
timestamp	Unix时间戳13位 毫秒	1679724896223
nonce	UUID V4	794c26b0-d33c-4394-b2bb-c485eca16d9e
sign	计算出来的签名	kAXyh+eerqrefyaF8dyFB0M4FVo=

请求参数

{
	"externalOrderId": "389508808434869257",
    "orderId": "OCURRPAID202307270301551690426915467DOCKER020000000400000744"
}

请求参数说明

Param	Desc	Require
externalOrderId	商户订单号 max=64（String）	required
orderId	系统订单号（String）	required

响应类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

响应数据

{
    "code": "200",
    "success": true,
    "msg": "成功",
    "msgEn": "success",
    "desc": null,
    "data": [
        {
            "orderId": "OCURRPAID202412120240311733971231000HAMBIT-U0000000400182687",
            "cashierId": "OCURRPAID202412120240301733971230962HAMBIT-U0000000200182686",
            "orderType": 1,
            "orderResourceType": 2,
            "userId": "1785945811976196097",
            "orderStatus": 1,
            "orderTime": 1733971231000,
            "channelOrderId": "17339712310364t1hisixt",
            "externalOrderId": "34086233",
            "requestType": 1,
            "businessId": "1733971231031ipp53q8s3fusie2966c",
            "userType": 2,
            "operatorId": 1785942045981990914,
            "orderAmount": "3.11",
            "orderActualAmount": null,
            "orderEntryAmount": null,
            "orderFee": null,
            "orderPayTime": null,
            "orderCompleteTime": null,
            "currencyType": "BRL",
            "payType": 101,
            "tradeNote": "test123",
            "notifyUrl": "https://gw.hambit.co/#/home/dashboard",
            "markStatus": 0,
            "errorMsg": null,
            "errorMsgEn": null,
            "accountType": "",
            "accountName": "",
            "accountNo": "",
            "expansionParam": ""
        }
    ]
}

响应参数说明

Param	Type	Desc
accountName	String	账户名称
orderActualAmount	String	实际订单金额
orderPayTime	int64	订单支付时间
orderCompleteTime	int64	订单完成时间
errorMsg	string	错误消息
errorMsgEn	string	错误消息
orderEntryAmount	String	订单录入金额
orderFee	string	订单费用
accountNo	String	账户账号
accountType	String	账户类型
cashierId	String	收银台ID
channelOrderId	String	订单关联渠道订单ID
currencyType	String	法币类型 BRL
errorMsg	String	错误信息
externalOrderId	String	商户订单号
notifyUrl	String	回调地址
orderAmount	String	订单金额
orderId	String	订单id
orderResourceType	int64	订单所属业务类型 2-法币订单
orderStatus	int64	订单状态 1-待支付 2- 支付成功
orderTime	int64	订单创建时间
orderType	int64	订单类型 1-收款 2-代付
payType	int64	支付类型 101-PIX
tradeNote	String	备注
userId	String	用户ID
payTypeCode	String	支付类型code
orderStatusCode	String	订单状态code
orderTypeCode	String	订单类型code

5.6 查询代付订单

请求方式

Post

请求URL

/api/v3/bra/query/transferOrder

请求类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

请求头

Param	Desc	Sample
access_key	商户后台获取	pFqV75X3
timestamp	Unix时间戳13位 毫秒	1679724896223
nonce	UUID V4	794c26b0-d33c-4394-b2bb-c485eca16d9e
sign	计算出来的签名	kAXyh+eerqrefyaF8dyFB0M4FVo=

请求参数

{
	"externalOrderId": "241534072867503522",
    "orderId": "OCARDDEPO202306090256051686279365706DOCKER020000000200001399"
}

请求参数说明

Param	Desc	Require
externalOrderId	商户订单号 max=64（String）	required
orderId	系统订单号 （String）	required

响应类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

响应数据

{
	"code": "200",
	"success": true,
	"msg": "成功",
	"msgEn": "SUCCESS",
	"data": [{
		"accountName": "",
		"accountNo": "18171847684",
		"accountType": "CPF",
		"cashierId": "",
		"channelOrderId": "",
		"currencyType": "BRL",
		"errorMsg": "",
		"externalOrderId": "472512322065926592",
		"notifyUrl": "http://192.168.1.135:30002/abc",
		"orderActualAmount": "20.21",
		"orderAmount": "20.01",
		"orderFee": "0.2",
		"orderId": "OCURRDRAW202307270345461690429546358DOCKER020000000200000777",
		"orderResourceType": 2,
		"orderStatus": 1,
		"orderTime": 1690429547000,
		"orderType": 2,
		"payType": 201,
		"tradeNote": "123",
		"userId": "1663371399710216194",
		"payTypeCode": "PIX",
		"orderStatusCode": "Accepted",
		"orderTypeCode": "Transfer"
	}]
}

响应参数说明

Param	Type	Desc
accountName	String	代付-账户名称
accountNo	String	代付-账户账号
accountType	String	代付-账户类型
cashierId	String	收银台ID
channelOrderId	String	订单关联渠道订单ID
currencyType	String	法币类型
errorMsg	String	错误原因
externalOrderId	String	商户订单号
notifyUrl	String	回调地址
orderAmount	String	订单金额
orderId	String	订单id
orderResourceType	int64	订单所属业务类型 2-法币订单
orderStatus	int64	订单状态 1-已受理 2-银行处理中 4-失败(银行未受理) 8-成功 16-失败
orderTime	int64	订单发起时间
orderType	int64	订单类型 1-收款 2-代付
payType	int64	支付类型 201-PIX
tradeNote	String	备注
userId	String	订单创建人ID
payTypeCode	String	支付类型code
oderStatusCode	String	订单状态code
oderTypeCode	String	订单类型code

5.7 查询余额

请求方式

GET

请求URL

/api/v3/bra/query/balance

请求头

Param	Desc	Sample
access_key	商户后台获取	pFqV75X3
timestamp	Unix时间戳13位 毫秒	1679724896223
nonce	UUID V4	794c26b0-d33c-4394-b2bb-c485eca16d9e
sign	计算出来的签名	kAXyh+eerqrefyaF8dyFB0M4FVo=

响应数据

{
	"code": "200",
	"success": true,
	"msg": "成功",
	"msgEn": "SUCCESS",
	"data": [{
		"accountBalance": "76.35",
		"accountFreezeAmount": "0",
		"accountStatusId": 4,
		"accountWaitSettledAmount": "0",
		"currencyType": "BRL",
		"accountStatus": "InAndOut"
	}]
}

响应参数说明

Param	Type	Desc
accountBalance	String	账户可用余额
accountFreezeAmount	String	账户冻结金额
accountStatusId	int64	账户状态id
accountWaitSettledAmount	String	账户待划转金额
currencyType	String	法币类型
accountStatus	String	账户状态

5.8 查询订单凭证

请求方式

Post

请求URL

/api/v3/bra/query/voucher

请求头

Param	Desc	Sample
access_key	商户后台获取	pFqV75X3
timestamp	Unix时间戳13位 毫秒	1679724896223
nonce	UUID V4	794c26b0-d33c-4394-b2bb-c485eca16d9e
sign	计算出来的签名	kAXyh+eerqrefyaF8dyFB0M4FVo=

请求参数

{
    "orderId":"OCURRDRAW202405060728241714980504932DEV001OO0000000200016143"
}

请求参数说明

Param	Desc	Sample	Require
orderId	订单号(String) oneof=BRL	OCURRDRAW202405060728241714980504932DEV001OO0000000200016143	required

响应类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

响应数据

{
        "code": "200",
        "success": true,
        "msg": "成功",
        "msgEn": "SUCCESS",
        "data": "https://t-receipt.sa-aws-store-centre.com/2024050606/OCURRDRAW202405020328081714620488447DEV001OO0000000200015846.pdf"
}

响应参数说明

Param	Desc	Sample
data	支付凭证链接	https://t-receipt.sa-aws-store-centre.com/2024050606/OCURRDRAW202405020328081714620488447DEV001OO0000000200015846.pdf

5.9 查询代付银行列表(银行模式)

请求方式

Post

请求URL

/api/v3/bra/query/bank

请求头

Param	Desc	Sample
access_key	商户后台获取	pFqV75X3
timestamp	Unix时间戳13位 毫秒	1679724896223
nonce	UUID V4	794c26b0-d33c-4394-b2bb-c485eca16d9e
sign	计算出来的签名	kAXyh+eerqrefyaF8dyFB0M4FVo=

请求参数

{
    "currencyType":"BRL"
}

请求参数说明

Param	Desc	Sample
currencyType	币种(String) oneof=BRL	BRL

响应类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

响应数据

{
    "code": "200",
    "success": true,
    "msg": "成功",
    "msgEn": "SUCCESS",
    "data": [
        {"bankNames": "Banco Do Brasil S.A."}
	]
}

响应参数说明

Param	Desc	Sample
bankNames	银行名称	Banco Do Brasil S.A.

银行列表

BankName
Banco Do Brasil S.A.
Banco Da Amazonia S.A.
Banco Do Nordeste Do Brasil S.A.
Bndes
Credicoamo Credito Rural Cooperativa
C.Suisse Hedging-Griffo Cv S/A
Banco Inbursa S.A.
State Street Br S.A. Bco Comercial
Ubs Brasil Cctvm S.A.
Cooperativa De Crédito Mútuo Dos Despachantes De Trânsito De Santa Catarina E Rio Grande Do Sul - Sicoob Creditran
Bny Mellon Bco S.A.
Bco Tricury S.A.
Banestes S.A. Banco Do Estado Do Espirito Santo
Bco Bandepe S.A.
Banco Alfa S.A.
Banco Itaú Consignado S.A.
Banco Santander (Brasil) S.A.
Bco Bbi S.A.
Banco Do Estado Do Pará S.A.
Bco Cargill S.A.
Banco Do Estado Do Rio Grande Do Sul S.A.
Banco Do Estado De Sergipe S.A.
Confidence Cc S.A.
Hipercard Bm S.A.
Banco Bradescard
Goldman Sachs Do Brasil Bm S.A
Bco Andbank S.A.
Bco Morgan Stanley S.A.
Banco Crefisa S.A.
Brb - Banco De Brasilia S.A.
Bco. J.Safra S.A.
Bco Abn Amro S.A.
Bco Kdb Brasil S.A.
Banco Inter S.A.
Haitong Bi Do Brasil S.A.
Picpay Bank - Banco Múltiplo S.A
B&T Cc Ltda.
Bancoseguro S.A.
Banco Topázio S.A.
Bco Da China Brasil S.A.
Sisprime Do Brasil - Cooperativa De Crédito
Cooperativa Central De Crédito - Ailos
Banco Randon S.A.
Credisan Cooperativa De Crédito
Cccm Unicred Central Rs
Brk S.A. Cfi
Polocred Scmepp Ltda.
Banco Finaxis
Travelex Banco De Câmbio S.A.
Banco B3 S.A.
Credisis - Central De Cooperativas De Crédito Ltda.
Credialiança Cooperativa De Crédito Rural
Uniprime Central Nacional - Central Nacional De Cooperativa De Credito
Planner Cv S.A.
Renascenca Dtvm Ltda
Xp Investimentos Cctvm S/A
Caixa Economica Federal
Lecca Cfi S.A.
Bco Bocom Bbm S.A.
Portocred S.A. - Cfi
Oliveira Trust Dtvm S.A.
Neon Ctvm S.A.
Central Cooperativa De Crédito No Estado Do Espírito Santo
Advanced Cc Ltda
Banco Western Union Do Brasil S.A.
Bco Rodobens S.A.
Banco Agibank S.A.
Bco Bradesco Berj S.A.
Bco Woori Bank Do Brasil S.A.
Banco Genial S.A.
Br Partners Bi
Codepe Cvc S.A.
Braza Bank S.A. Bco De Câmbio
Ubs Brasil Bi S.A.
Caruana S.A. - Sociedade De Crédito, Financiamento E Investimento
Tullett Prebon Brasil Cvc Ltda
Icbc Do Brasil Bm S.A.
Confederação Nacional Das Cooperativas Centrais De Crédito E Economia Familiar E Solidária - Cresol Confederação
Bgc Liquidez Dtvm Ltda
Confederação Nacional Das Cooperativas Centrais Unicred Ltda. - Unicred Do Brasil.
Get Money Cc Ltda
Intesa Sanpaolo Brasil S.A. Bm
Nu Invest Corretora De Valores S.A.
Master Bi S.A.
Broker Brasil Cc Ltda.
Treviso Cc S.A.
Bexs Banco De Câmbio S/A
Levycam Ccv Ltda
Guitta Cc Ltda
Facta S.A. Cfi
Icap Do Brasil Ctvm Ltda.
Casa Do Crédito S.A. Sociedade De Crédito Ao Microempreendedor
Commerzbank Brasil S.A. - Bco Múltiplo
Bco Olé Consignado S.A.
Brl Trust Dtvm Sa
Pefisa S.A. - Crédito, Financiamento E Investimento
Guide
Cm Capital Markets Cctvm Ltda
Socred S.A. - Sociedade De Crédito Ao Microempreendedor E À Empresa De Pequeno Porte
Bco Itaú Bba S.A.
Ativa S.A. Investimentos Cctvm
Hs Financeira
Servicoop
Nova Futura Ctvm Ltda.
Parmetal Dtvm Ltda
Valor Scd S.A.
Fair Cc S.A.
Stone Instituição De Pagamento S.A.
Banco Btg Pactual S.A.
Banco Original S.A.
Banco Arbi S.A.
Banco John Deere S.A.
Banco Bs2 S.A.
Bco Crédit Agricole Br S.A.
Banco Fibra S.A.
Banco Cifra
Banco Bradesco S.A.
Bco Classico S.A.
Banco Master S/A
Banco Abc Brasil S.A.
Banco Investcred Unibanco S.A.
Bcv - Bco, Crédito E Varejo S.A.
Bexs Cc S.A.
Paraná Banco S.A.
Moneycorp Bco De Câmbio S.A.
Nu Pagamentos S.A. - Instituição De Pagamento
Bco Fator S.A.
Bco Cedula S.A.
Bari Cia Hipotecária
Banco Hsbc S.A.
Sagitur Cc
Ib Cctvm S.A.
Agk Cc S.A.
Cooperativa De Crédito Rural De São Miguel Do Oeste - Sulcredi/São Miguel
Bmp Sociedade De Crédito Ao Microempreendedor E A Empresa De Pequeno Porte Ltda.
Banco Senff S.A.
Genial Investimentos Cvm S.A.
Primacredi Cooperativa De Crédito De Primavera Do Leste
Will Financeira S.A.Cfi
Cooperativa De Crédito Rural Coopavel
Rb Investimentos Dtvm Ltda.
Frente Cc S.A.
Uniprime Ouro - Cooperativa De Crédito De Ouro
Carol Dtvm Ltda.
Efx Cc Ltda.
Pagseguro Internet Instituição De Pagamento S.A.
Bs2 Dtvm S.A.
Lastro Rdv Dtvm Ltda
Oz Corretora De Câmbio S.A.
Vips Cc Ltda.
Banco Afinz S.A. - Banco Múltiplo
Bco La Nacion Argentina
Dock Instituição De Pagamento S.A.
Portopar Dtvm Ltda
Terra Investimentos Dtvm
Cambionet Cc Ltda
Vortx Distribuidora De Titulos E Valores Mobiliarios Ltda.
Dourada Corretora
Hscm - Sociedade De Crédito Ao Microempreendedor E À Empresa De Pequeno Porte Ltda.
Amazônia Cc Ltda.
Pi Dtvm S.A.
Banco Bmg S.A.
Om Dtvm Ltda
Bco Ccb Brasil S.A.
Crefaz Scmepp Ltda
Cooperativa De Crédito Rural De Abelardo Luz - Sulcredi/Crediluz
Mercado Pago Instituição De Pagamento Ltda.
Cartos Sociedade De Crédito Direto S.A.
Órama Dtvm S.A.
Parati - Credito, Financiamento E Investimento S.A.
Cecm Fabric Calçados Sapiranga
Qi Sociedade De Crédito Direto S.A.
Banco Bari De Investimentos E Financiamentos S.A.
Fram Capital Dtvm S.A.
Acesso Soluções De Pagamento S.A. - Instituição De Pagamento
Banco Besa S.A.
Banco Digio S.A.
Banco C6 S.A.
Superdigital Instituição De Pagamento S.A.
Itaú Unibanco S.A.
Creditas Scd
Ffa Scmepp Ltda.
Banco Xp S.A.
Al5 S.A. Crédito, Financiamento E Investimento
Cooperativa De Crédito Rural De Pequenos Agricultores E Da Reforma Agrária Do Centro Oeste Do Paraná - Crehnor Laranjeiras
Toro Ctvm S.A.
Necton Investimentos S.A Cvm
Ótimo Sociedade De Crédito Direto S.A.
Midway S.A. - Crédito, Financiamento E Investimento
Zema Crédito, Financiamento E Investimento S/A
Trinus Capital Dtvm
Cielo S.A. - Instituição De Pagamento
Singulare Ctvm S.A.
Efí S.A. - Instituição De Pagamento
Simpaul
Bco Societe Generale Brasil
Vitreo Dtvm S.A.
Banco Csf S.A.
Bco Mizuho S.A.
Warren Cvmc Ltda
Up.P Sep S.A.
Realize Crédito, Financiamento E Investimento S.A.
Banco J.P. Morgan S.A.
Bms Scd S.A.
Bco Brasileiro De Crédito S.A.
Cecm Cooperforte
Picpay Instituição De Pagamento S.A.
Bco Mercedes-Benz S.A.
Fidúcia Sociedade De Crédito Ao Microempreendedor E À Empresa De Pequeno Porte Limitada.
Ebanx Instituicao De Pagamentos Ltda.
Global Finanças Sociedade De Crédito Ao Microempreendedor E À Empresa De Pequeno Porte Ltda.
Cecm Dos Trab.Port. Da G.Vitor
Nu Financeira S.A. Cfi
Bco Toyota Do Brasil S.A.
Banco Mercantil Do Brasil S.A.
Bco Gm S.A.
Ccr De Ibiam
Bco Volkswagen S.A
Bco Bradesco Financ. S.A.
F D Gold Dtvm Ltda
Hub Instituição De Pagamento S.A.
Listo Sociedade De Credito Direto S.A.
Ideal Ctvm S.A.
Kirton Bank
Coop Creditag
Iugu Instituição De Pagamento S.A.
Cobuccio S/A - Sociedade De Crédito, Financiamento E Investimentos
Cora Sociedade De Crédito Direto S.A.
Sumup Sociedade De Crédito Direto S.A.
Accredito - Sociedade De Crédito Direto S.A.
Índigo Investimentos Distribuidora De Títulos E Valores Mobiliários Ltda.
Bonuspago Sociedade De Crédito Direto S.A.
Planner Sociedade De Crédito Direto
Via Certa Financiadora S.A. - Cfi
Social Bank Banco Múltiplo S/A
Banco Bv S.A.
Lend Scd S.A.
Lamara Scd S.A.
Zipdin Scd S.A.
Numbrs Sociedade De Crédito Direto S.A.
Lar Cooperativa De Crédito - Lar Credi
Banco Safra S.A.
Coluna S.A. Dtvm
Socinal S.A. - Crédito, Financiamento E Investimento
Neon Financeira - Cfi S.A.
Cooperativa De Credito Dos Servidores Da Universidade Federal Do Espirito Santo
Credsystem Sociedade De Crédito Direto S.A.
Crediare Cfi S.A.
Cooperativa De Credito Rural Seara - Crediseara
Br-Capital Dtvm S.A.
Delcred Sociedade De Crédito Direto S.A.
Trustee Dtvm Ltda.
Id Corretora De Títulos E Valores Mobiliários S.A.
Credibrf Coop
Magnetis - Dtvm
Credihome Scd
Trinus Sociedade De Crédito Direto S.A.
Plantae Cfi
Mirae Asset Cctvm Ltda
Hemera Dtvm Ltda.
Dm
Fitbank Instituição De Pagamentos Eletrônicos S.A.
J17 - Sociedade De Crédito Direto S/A
Credifit Sociedade De Crédito Direto S.A.
Mérito Dtvm Ltda.
Fênix Dtvm Ltda.
Bco Mufg Brasil S.A.
Uy3 Sociedade De Crédito Direto S/A
Hedge Investments Dtvm Ltda.
Ccm Serv. Públicos Sp
Unavanti Scd S/A
Asaas Gestão Financeira Instituição De Pagamento S.A.
Stark Sociedade De Crédito Direto S.A.
Azumi Dtvm
Bco Sumitomo Mitsui Brasil S.A.
Capital Consig Sociedade De Crédito Direto S.A.
Master S/A Cctvm
Portoseg S.A. - Credito, Financiamento E Investimento
Liga Invest Dtvm Ltda.
Cdc Scd S.A.
Cecm Serv Publ Pinhão
Bco Caixa Geral Brasil S.A.
Bco Yamaha Motor S.A.
Citibank N.A.
Gazincred S.A. Sociedade De Crédito, Financiamento E Investimento
Bco Itaubank S.A.
Superlógica Sociedade De Crédito Direto S.A.
Sbcash Scd
Maf Dtvm Sa
Deutsche Bank S.A.Bco Alemao
Jpmorgan Chase Bank
Ing Bank N.V.
Bco La Provincia B Aires Bce
Bco Credit Suisse S.A.
Rji
Scfi Efí S.A.
Avenue Securities Dtvm Ltda.
Celcoin Instituicao De Pagamento S.A.
Ffcred Scd S.A.
Magnum Sociedade De Crédito Direto S.A.
Finvest Dtvm
Atf Credit Scd S.A.
Qista S.A. Cfi
Mercado Crédito Scfi S.A.
Lions Trust Dtvm
Peak Sep S.A.
Red Scd S.A.
Hr Digital Scd
Wnt Capital Dtvm
Intercam Cc Ltda
Monetarie Scd
Aticca Scd S.A.
Reag Dtvm S.A.
Pinbank Brasil Instituição De Pagamento S.A.
Ser Finance Scd S.A.
Eagle Scd S.A.
Ewally Instituição De Pagamento S.A.
Maru Scd S.A.
Neon Pagamentos S.A. - Instituição De Pagamento
Microcash Sociedade De Crédito Ao Microempreendedor E À Empresa De Pequeno Porte Ltda.
Santinvest S.A. - Cfi
Fdo Garantidor Créditos
Senso Ccvm S.A.
U4c Instituição De Pagamento S.A.
Banco Luso Brasileiro S.A.
Banco Industrial Do Brasil S.A.
Banco Vr S.A.
Bco Paulista S.A.
Banco Guanabara S.A.
Omni Banco S.A.
Banco Pan S.A.
Bco C6 Consig
Banco Letsbank S.A.
Banco Rendimento S.A.
Banco Triangulo S.A.
Banco Sofisa S.A.
Bco Pine S.A.
Itaú Unibanco Holding S.A.
Banco Voiter S.A.
Banco Digimais S.A.
Banco Votorantim S.A.
Banco Daycoval S.A.
Banco Ourinvest S.A.
Bco Rnx S.A.
Banco Neon
Bco Cetelem S.A.
Banco Ribeirao Preto S.A.
Banco Semear S.A.
Banco Citibank S.A.
Banco Modal S.A.
Bco Rabobank Intl Brasil S.A.
Banco Cooperativo Sicredi S.A.
Scotiabank Brasil
Bco Bnp Paribas Brasil S A
Novo Banco Continental S.A. - Banco Múltiplo
Banco Sistema
Bank Of America Merrill Lynch Banco Múltiplo S.A.
Banco Cooperativo Sicoob S.A. - Banco Sicoob
Banco Keb Hana Do Brasil S.A.

6. 回调信息

6.1 如何回调接口验签

验签说明

​ API 请求在通过 internet 传输的过程中极有可能被篡改，为了确保回调未被更改， 您可设置回调参数签名认证。设置方法为：登录收银台 ->开发者中心 -> 回调地址 -> 添加。

验签步骤

整体流程和签名大体一致，仅仅是拿来验签的数据取法不一样，签名是自己构造数据，验签是获取数据（header、json）

1. 取出 header 中的 sign 值；
2. 定义一个 Map 字典类型对象，将请求中的json参数以 key-value 的形式放入其中
3. 取出 header 中的 access_key、timestamp、nonce 也放入上一步定义的 Map 中
4. 将 Map 中的 key 按照 ASCII 码从小到大排序（字典序）并将 Map 转换输出为“key1=value1&key2=value2” 形式的字符串；
5. 将上一步转换的字符串用 secret_key 进行 HMAC_SHA1 加密并进行 Base64 转码，得到 sign 签名值与第一步 header 中取出的 sign 进行字符串校验，相符则验签通过，反之则验签失败。此处的 secret_key 需与下单时的 access_key 相匹配。

6.2 支付回调

回调数据

{
	"currencyType": "BRL",
	"orderActualAmount": "21.1",
	"orderId": "OCURRPAID202307270345431690429543531DOCKER020000000400000776",
	"orderFee": "0.1",
	"orderStatus": "Payment success",
	"payParam": "00020101021226580014BR.GOV.BCB.PIX01367469e5e5-ad5b-43d4-9cf0-07125c89dd8d520400005303986540521.105802BR5925LIQUIDO BRL PAGAMENTOS DI6014Belo Horizonte61083038040362290525dWH1ySiuFwduurQpP1wv7RTof6304BC7A",
	"externalOrderId": "828905760411449635",
	"tradeNote": "123",
	"payTypeName": "PIX",
	"orderAmount": "21.1",
	"orderTime": 1690429544000,
	"payType": 101,
	"orderStatusCode": 2,
	"markStatus": 0,
	"orderPayTime": 1690429623000
}

回调数据说明

Param	Type	Desc
currencyType	String	法币类型
orderActualAmount	String	订单实际支付金额
orderId	String	订单ID
orderFee	String	订单手续费
orderStatus	String	orderStatusCode描述
payParam	String	支付参数
externalOrderId	String	商户订单ID
tradeNote	String	备注
payTypeName	String	支付类型名称
orderAmount	String	订单金额
orderTime	int64	订单创建时间
payType	int64	支付类型101-PIX
orderStatusCode	int64	订单状态 code 1-待支付 2- 支付成功
markStatus	int64	标记状态
orderPayTime	int64	订单支付时间
errorMsg	String	错误信息
errorMsgEn	String	错误信息en

​ 任意时候商户都可登录商户后台进行手动触发回调（不建议订单非终态发起手动回调），回调信息中订单状态等相关信息为真实实际状态（手动 回调请一定注意订单状态，如果手动回调订单的状态不是终态，在订单变为终态的时候平台依然会发起通知，请注意业务层面的冗余处理）

6.3 代付回调

回调数据

{
	"currencyType": "BRL",
	"userInfoNo": "18171847684",
	"orderId": "OCURRDRAW202307270345461690429546358DOCKER020000000200000777",
	"userInfoType": "CPF",
	"accountType": "CPF",
	"orderFee": "0.2",
	"orderStatus": "Success",
	"externalOrderId": "472512322065926592",
	"tradeNote": "123",
	"payTypeName": "PIX",
	"orderAmount": "20.01",
	"orderTime": 1690429547000,
	"payType": 201,
	"userInfoName": "joy",
	"accountNo": "18171847684",
	"orderStatusCode": 8,
	"markStatus": 0,
	"orderPayTime": 1690443316000
}

回调数据说明

Param	Type	Desc
currencyType	String	法币类型 BRL
userInfoNo	String	用户证件号
orderId	String	订单ID
userInfoType	String	用户证件信息类型
accountType	String	账户类型
orderFee	String	订单手续费
orderStatus	String	订单状态
externalOrderId	String	商户订单ID
tradeNote	String	备注
payTypeName	String	支付类型名称
orderAmount	String	订单金额
orderTime	int64	订单创建时间
payType	int64	支付类型 201-PIX
userInfoName	String	用户证件名
accountNo	String	账户号
orderStatusCode	int64	订单状态code 1-已受理 2-银行处理中 4-失败(银行未受理) 8-成功 16-失败
markStatus	int64	标记状态
orderPayTime	int64	订单支付时间
errorMsg	String	错误信息
errorMsgEn	String	错误信息en

任意时候商户都可登录商户后台进行手动触发回调（不建议订单非终态发起手动回调），回调信息中订单状态等相关信息为真实实际状态（手动 回调请一定注意订单状态，如果手动回调订单的状态不是终态，在订单变为终态的时候平台依然会发起通知，请注意业务层面的冗余处理）

6.4 回调响应

备注：所有的回调都包含签名信息，建议商户做回调验签，商户收到回调信息后，确定订单终态，请响应网

关如下信息（content-type: application/json）如果没有正常响应服务端会在30分钟内，间隔三分钟总计2

次通知

{"code":200,"success":true}

6.5 回调通知URL

登录商户后台可以配置统一回调地址（订单中手动指定回调UR地址，优先级高于统一配置的回调地址，例如：订单中指定了notifyUrl参数，不管是否有统一配置回调通知地址，都使用订单中的notifyUrl地址)

注意 http响应status_code优先级最高 只要收到响应status_code=200 响应数据则忽略

7. 公共响应代码

filed	Type	Default value and comment
code	String	成功"200" 其他请参考失败code
success	Bool	成功 true 失败false 和code保持意义上的同步
msg	String	一级code返回的文字性描述
data	Object	参考接口列表章节

8. 失败code

Code	Desc
200	成功
300	参数异常
301	IP无权限
307	签名错误
500	系统错误