API Document

# Brazilian payment API documentation

# 1. How to get API Key

   The user logs in to the cash register -> Developer Center -> API Key -> Create API key. API Key has a separate configuration page and is bound to a fixed IP address ("0.0.0.0" means no IP interception filtering, any IP can be accessed), and different API Keys can be configured to meet different needs. Please do not disclose your Access Key and Secret Key to avoid asset loss. After the Secret Key is generated, it cannot be viewed again. Please save it in time. If you forget the Secret Key, please recycle the key pair in the backstage of the merchant and apply for a new key pair.

# 1.1 How to create API KEY

• Click Developer Center-API Key

• 1Choose whether to enable the debug mode (After debugging mode is enabled, you will have a standard prompt message and log view address for any errors )

• 2Select API Key permission

• 3Enter the whitelist address (0.0.0.0 means any IP address can be accessed)

Note: (When entering the whitelist domain name, you should pay attention to using "," to isolate multiple IPs.)

• 4 click create to generate API KEY

(After the API KEY is generated, you can copy, view, edit, and delete it in the My API KEY list below. Note that the Secret key only appears once when it is generated. Please save it properly. If you forget the Secret Key, Please recycle the key pair and apply for a new one.)

• Click Edit to close or open [Start Debugging] and modify the API Key permission and whitelist address. After the modification is complete, click Save

Note: Please wait patiently for 90 seconds for the API Key to take effect after creating or editing the API Key

# 2. How to use API Key

The current API Key is to add a parameter list in the header of the request

Parameter name Parameter description Type Required
access_key Api Key access key (eg: TPhoa7ZQ) String Yes
timestamp Millisecond-level timestamp (13 digits, such as: 1679669488472) String Yes
nonce UUID (36 bits such as: 02f7a04f-53cc-47d4-bb3f-fae69dab49ac) The five parts are 8 characters, 4 characters, 4 characters, 4 characters, and 12 characters, with "-" in the middle interval String yes
sign Parameter signature (eg: GXx2wYUD6UVr+zcmeCSFFPzcBLA=) String Yes

# 3. Technology side parameter access process

# 4. How to sign the interface

# Signature Description

   API requests are very likely to be tampered with during transmission over the internet. In order to ensure that the request has not been changed, all private interfaces except public interfaces (basic information, market data, etc.) must use your API Key is used for signature verification to verify whether parameters or parameter values have changed during transmission.

A legitimate request consists of the following parts:

  • access_key: API access key;
  • secret_key: The key used for signature encryption (only visible once when applying for an API Key in the background, please copy and save it in a safe place, and do not disclose it);
  • timestamp: The time (UTC time) when you made the request. Such as: 1632811287325 (13 digits). Including this value in a query request helps prevent third parties from intercepting your request;
  • nonce: random UUID string. Such as: 053a1b81-48a0-4bb1-96b2-60f6e509d911 (36 bits);
  • sign: The value calculated by the signature, which is used to ensure that the signature is valid and has not been tampered with;
  • All interfaces need to pass the above public parameters except secret_key in the http request header (header). The public parameters include (access_key, timestamp, nonce, sign) and other signature parameters are described in the API interface as allow.

# Signature steps

​ 1. Define a Map dictionary type object, and put the parameters in the request into it in the form of key-value

​ 2. Put access_key, timestamp, and nonce into the Map defined in the first step

​ 3. Sort the attributes in the Map in ascending order (lexicographic order) according to the ASCII code and convert the Map to a string in the form of "key1=value1&key2=value2"

​ 4. Encrypt the character string converted in the previous step with secret_key by HMAC_SHA1 and perform Base64 transcoding to obtain the value of the sign parameter. secret_key is the information in the apikey created on the cashier platform

​ 5. Add the sign value and other required parameters to the request header, and send the request to the target interface

# Signature debugging tools

  • SignUtil: User login to cash register -> Developer Center -> API Documentation -> Signature Tool The Signature tool page is displayed (The access_key in the tool, please use a valid access_key and please set the IP whitelist that allows this access_key access to 0.0.0.0, we strongly recommend the used Access_key is discarded after debugging)

# 5. Interface list

# 5.1 Test interface connectivity

request method

Get

Request URL

/ping

response data

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

Response parameter description

Param Type Desc
version String If this parameter is returned, all interfaces in this document can be requested normally
timestamp int64 Unix timestamp

# 5.2 Create a new collection order

request method

post

Request URL

/api/v3/bra/createCollectingOrder

Request type

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

request header

Param Desc Sample
access_key Acquisition from merchant background pFqV75X3
timestamp Unix timestamp 13 digits milliseconds 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign Calculated signature kAXyh+eerqrefyaF8dyFB0M4FVo=

request parameters

{
	"amount": "21.1",
	"channelType": "PIX",
	"externalOrderId": "389508808434869257",
	"notifyUrl": "http://192.168.135:30002/url",
	"remark": "123",
	"returnUrl": "http://192.168.135:30002/url",
    "userIdentity": "2348937596"
	"inputCpf": 0
}

Description of request parameters

Param Desc Sample Require
amount Amount of payment, the decimal point cannot exceed 2 digits (String) 21.1 required
channelType payment type oneof=PIX、PIX_DYNAMIC、BOLETO(String) Choose one of the three parameters based on the actual situation, PIX, PIX-DYNAMIC, or BOLETO required
externalOrderId Merchant order number max=64 (String) 389508808434869257 required
notifyUrl notification URL (String, Url) http://192.168.135:30002/abc optional
remark remark max=255 (String) 1312425 optional
returnUrl return address (String) http://192.168.135:30002/abc optional
userIdentity Retain the CPF information entered by the user in the subsequent cash register, and use a string ID as a mapping. If the passed string ID matches the corresponding CPF, use the stored CPF to directly submit the order . This parameter only needs to be enabled if It has already been saved and directly skips the CPF input. If it is not saved, the user needs to enter it manually (if this field is not passed, the system will generate CPF by default) (String) 2348937596 optional
inputCpf Whether to customize and upload CPF information oneof=0-(No) 1-(Yes) (int64) As long as it is enabled, the user will be required to manually enter the CPF Choose 0 or 1 according to the actual situation optional

response type

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

response data

{
	"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"
	}
}

Response parameter description

Param Type Desc
cashierCurrencyAmount String Receipt amount
cashierExpireTime int64 expiration time
cashierId String Cashier ID
cashierUrl String cashier link
currency String currency code
amount String Receipt amount
externalOrderId String Merchant order ID
orderId String System order ID
orderStatus String order status
orderStatusCode int64 order status code 1-pending payment
2-payment successful
orderTime int64 order time
payParam String payment parameter
payType String payment type
tradeNote String Trade Note
isCreateOrder bool Whether an order has been created
payType int64 payment type
returnUrl String Jump URL
userInfoName String username
userInfoNo String user information number
userInfoType String UserInfoType
payTypeCode String payment type code

# 5.3 Create a new transfer order(PIX)

request method

post

Request URL

/api/v3/bra/createTransferOrder

/api/v3/bra/pix/createTransferOrder

Either of the above two Urls is sufficient

Request type

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

request header

Param Desc Sample
access_key Acquisition from merchant background pFqV75X3
timestamp Unix timestamp 13 digits milliseconds 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign Calculated signature kAXyh+eerqrefyaF8dyFB0M4FVo=

request parameters

{
	"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"
}

Description of request parameters

Note: In order to improve the efficiency of payment, the following parameter list is recommended for users to upload

Param Desc Sample Require
currencyAmount Amount to pay on behalf, the decimal cannot be greater than 2 digits (String) 20.01 required
channelType payment type oneof=PIX (String) PIX required
externalOrderId Merchant order number max=64 (String) 871049832638078444 required
personIdType User ID information oneof=CPF (String) CPF CNPJ Choose one of the two parameters according to the actual situation required
personId User ID number (String) 18171847084 required
personName User name，max=255 (String) bob required
accountType bank account type oneof=CPF CNPJ PHONE EMAIL EVP (String) CPF CNPJ PHONE EMAIL EVP Choose one of the five parameters based on the actual situation required
accountId bank account number, refer to accountType type (String) Pass parameters according to the actual situation required
remark remark max=255 (String) 1312 optional
notifyUrl notification URL (String) http://192.168.1.135:30002/abc optional

response type

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

response data

{
	"code": "200",
	"success": True,
	"msg": "成功",
	"msgEn": "SUCCESS",
	"data": {
		"currencyType": "BRL",
		"externalOrderId": "123981",
		"orderId": "OCURRDRAW202306150152001686793920183DOCKER0200001233457",
		"orderStatus": "Accepted"
	}
}

Response parameter description

Param Type Desc
currencyType String Fiat currency type
externalOrderId String merchant order id
orderId String System order ID
orderStatus String order statusState

# 5.4 Create a new transfer order(Bank)

request method

post

Request URL

/api/v3/bra/bank/createTransferOrder

Request type

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

request header

Param Desc Sample
access_key Acquisition from merchant background pFqV75X3
timestamp Unix timestamp 13 digits milliseconds 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign Calculated signature kAXyh+eerqrefyaF8dyFB0M4FVo=

request parameters

{
	"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"
}

Description of request parameters

Note: In order to improve the efficiency of payment, the following parameter list is recommended for users to upload

Param Desc Sample Require
currencyAmount Amount to pay on behalf, the decimal cannot be greater than 2 digits (String) 20.01 required
channelType payment type oneof=BANK(String) BANK required
externalOrderId Merchant order number max=64 (String) 871049832638078444 required
personIdType User ID information oneof=CPF (String) CPF CNPJ Choose one of the two parameters according to the actual situation required
personId User ID number (String) 18171847084 required
personName User name，max=255 (String) bob required
accountType bank account type oneof=CC CP (String) CC CP Choose one of the two parameters based on the actual situation required
bankName bankName(String) Banco Keb Hana Do Brasil S.A. required
agency Bank account agent(String) 1 required
accountId bank account number, refer to accountType type (String) Pass parameters according to the actual situation required
remark remark max=255 (String) 1312 optional
notifyUrl notification URL (String) http://192.168.1.135:30002/abc optional

response type

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

response data

{
	"code": "200",
	"success": True,
	"msg": "成功",
	"msgEn": "SUCCESS",
	"data": {
		"currencyType": "BRL",
		"externalOrderId": "123981",
		"orderId": "OCURRDRAW202306150152001686793920183DOCKER0200001233457",
		"orderStatus": "Accepted"
	}
}

Response parameter description

Param Type Desc
currencyType String Fiat currency type
externalOrderId String merchant order id
orderId String System order ID
orderStatus String order statusState

# 5.5 Query Collection Orders

request method

post

Request URL

/api/v3/bra/query/collectingOrder

Request type

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

request header

Param Desc Sample
access_key Acquisition from merchant background pFqV75X3
timestamp Unix timestamp 13 digits milliseconds 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign Calculated signature kAXyh+eerqrefyaF8dyFB0M4FVo=

request parameters

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

Description of request parameters

Param Desc Require
externalOrderId Merchant order number max=64 (String) required
orderId system order number (String) required

response type

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

response data

{
    "code": "200",
    "success": true,
    "msg": "Success",
    "msgEn": "SUCCESS",
	"data": [{
            "accountName": "",
            "accountNo": "",
            "accountType": "",
            "cashierId": "OCURRPAID202306200656091687244169608BMS001OO0000000200000048",
            "channelOrderId": "83cd516a-c745-43a9-8576-86577626116b",
            "currencyType": "BRL",
            "errorMsg": "",
            "externalOrderId": "397985113671560647",
            "notifyUrl": "",
            "orderAmount": "10.21",
            "orderId": "OCURRPAID202306200656091687244169633BMS001OO0000000200000049",
            "orderResourceType": 2,
            "orderStatus": 1,
            "orderTime": 1687244170000,
            "orderType": 1,
            "payType": 101,
            "tradeNote": "",
            "userId": "1670971275447685121",
            "payTypeCode": "PIX",
            "orderStatusCode": "Wait pay",
            "orderTypeCode": "Pay"
	}]
}

Response parameter description

Param Type Desc
accountName String account name
accountNo String account number
accountType String account type
cashierId String Cashier ID
channelOrderId String The order ID of the channel associated with the order
currencyType String Fiat currency type
errorMsg String error reason
externalOrderId String external order number
notifyUrl String callback address
orderAmount String order amount
orderId String order id
orderResourceType int64 The business type of the order
orderStatus int64 order status 1- pending payment
2- payment successful
orderTime int64 order initiation time
orderType int64 order type
payType int64 payment type 101-PIX
tradeNote String Trade Note
userId String user ID
payTypeCode String payment type code
orderStatusCode String order status code
orderTypeCode String order type code

# 5.6 Query transfer orders

request method

post

Request URL

/api/v3/bra/query/transferOrder

Request type

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

request header

Param Desc Sample
access_key Acquisition from merchant background pFqV75X3
timestamp Unix timestamp 13 digits milliseconds 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign Calculated signature kAXyh+eerqrefyaF8dyFB0M4FVo=

request parameters

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

Description of request parameters

Param Desc Require
externalOrderId Merchant order number max=64 (String) required
orderId system order number (String) required

response type

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

response data

{
    "code": "200",
    "success": true,
    "msg": "Success",
    "msgEn": "SUCCESS",
    "data": [{
        "accountName": "",
        "accountNo": "",
        "accountType": "",
        "cashierId": "OCURRPAID202306200656091687244169608BMS001OO0000000200000048",
        "channelOrderId": "83cdjfoa-c745-43a9-8576-837128779247",
        "currencyType": "BRL",
        "errorMsg": "",
        "externalOrderId": "241534072867503522",
        "notifyUrl": "",
        "orderAmount": "10.21",
        "orderId": "OCARDDEPO202306090256051686279365706DOCKER020000000200001399",
        "orderResourceType": 2,
        "orderStatus": 1,
        "orderTime": 1687244170000,
        "orderType": 1,
        "payType": 101,
        "tradeNote": "",
        "userId": "167097127544130811",
        "payTypeCode": "PIX",
        "orderStatusCode": "Wait pay",
        "orderTypeCode": "Pay"
	}]
}

Response parameter description

Param Type Desc
accountName String transfer account name
accountNo String transfer account number
accountType String transfer account type
cashierId String Cashier ID
channelOrderId String The order ID of the channel associated with the order
currencyType String Fiat currency type
errorMsg String error reason
externalOrderId String Merchant order ID
notifyUrl String callback address
orderAmount String order amount
orderId String system order id
orderResourceType int64 The business type of the order
orderStatus int64 order status 1-accepted
2-bank processing
4-Failed(Bank rejection)
8-success
16-Failed
orderTime int64 order initiation time
orderType int64 order type
payType int64 payment type
tradeNote String Trade Note
userId String order creator ID
payTypeCode String payment type code
orderStatusCode String order status code
orderTypeCode String order type code

# 5.7 Query balance

request method

GET

Request URL

/api/v3/bra/query/balance

request header

Param Desc Sample
access_key Acquisition from merchant background pFqV75X3
timestamp Unix timestamp 13 digits milliseconds 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign Calculated signature kAXyh+eerqrefyaF8dyFB0M4FVo=

response data

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

Response parameter description

Param Type Desc
accountBalance String Available account balance
accountFreezeAmount String Account Freeze Amount
accountStatusId int64 Account Status id
accountWaitSettledAmount String Amount to be transferred from the account
currencyType String Fiat currency type
accountStatus String account status

# 5.8 Query Order Vouchers

request method

Post

Request URL

/api/v3/bra/query/voucher

request header

Param Desc Sample
access_key Acquisition from merchant background pFqV75X3
timestamp Unix timestamp 13 digits milliseconds 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign Calculated signature kAXyh+eerqrefyaF8dyFB0M4FVo=

request parameters

{
    "orderId":"OCURRDRAW202405060728241714980504932DEV001OO0000000200016143"
}

Description of request parameters

Param Desc Sample Require
orderId orderId(String) OCURRDRAW202405060728241714980504932DEV001OO0000000200016143 required

response type

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

response data

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

Response parameter description

Param Desc Sample
data Payment voucher link https://t-receipt.sa-aws-store-centre.com/2024050606/OCURRDRAW202405020328081714620488447DEV001OO0000000200015846.pdf

# 5.9 Query the list of payment banks (Bank)

request method

post

Request URL

/api/v3/bra/query/bank

Request type

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

request header

Param Desc Sample
access_key Acquisition from merchant background pFqV75X3
timestamp Unix timestamp 13 digits milliseconds 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign Calculated signature kAXyh+eerqrefyaF8dyFB0M4FVo=

request parameters

{
    "currencyType":"BRL"
}

Description of request parameters

Param Desc Sample
currencyType Currency(String) oneof=BRL BRL

response type

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

response data

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

Response parameter description

Param Desc Sample
bankNames bank Name Banco Do Brasil S.A.

Bank List

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. Callback information

# 6.1 How to call back interface check

# Signature verification instructions

​ API requests are likely to be tampered with during transmission over the internet. To ensure that callbacks have not been changed, you can set callback parameter signature authentication. The setting method is: log in to the cashier -> developer center -> callback address -> add.

# Signature verification steps

The overall process is roughly the same as the signature, except that the data used to verify the signature is different. The signature is to construct the data by itself, and the signature is to obtain the data (header, json)

  1. Take out the sign value in the header;

  2. Define a Map dictionary type object, put the json parameters in the request in the form of key-value

  3. Take out the access_key, timestamp, and nonce in the header and put them into the Map defined in the previous step

  4. Sort the keys in the Map according to the ASCII code from small to large (lexicographic order) and convert the Map into a string in the form of "key1=value1&key2=value2";

  5. Use the secret_key to encrypt the character string converted in the previous step with HMAC_SHA1 and perform Base64 transcoding to obtain the signed value and the sign extracted from the header in the first step for string verification. If they match, the signature verification will pass, otherwise, the signature verification will fail. The secret_key here needs to match the access_key when placing an order.

# 6.2 Payment callback

callback data

{
	"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
}

Callback data description

Param Type Desc
currencyType String Fiat currency type
orderActualAmount String The actual payment amount of the order
orderId String order ID
order fee String Order handling fee
orderStatus String orderStatusCode description
payParam String payment parameters
externalOrderId String Merchant order ID
tradeNote String Remark
payTypeName String payment type name
orderAmount String order amount
orderTime int64 Order creation time
payType int64 Payment Type 101-PIX
orderStatusCode int64 Order status code 1-pending payment
2- payment successful
markStatus int64 mark status
orderPayTime int64 order payment time
errorMsg String Error message
errorMsgEn String Error message en

At any time, the merchant can log in to the backstage of the merchant to manually trigger the callback (it is not recommended to initiate a manual callback if the order is not final), and the relevant information such as the order status in the callback information is the actual status (manualPlease pay attention to the order status when calling back. If the status of the manual callback order is not final, the platform will still initiate a notification when the order becomes final. Please pay attention to redundant processing at the business level)

# 6.3 Transfer callback

callback data

{
	"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
}

Callback data description

Param Type Desc
currencyType String Fiat currency type
userInfoNo String User ID number
orderId String order ID
userInfoType String User certificate information type
accountType String account type
orderFee String Order handling fee
orderStatus String Order Status
externalOrderId String Merchant order ID
TradeNote String Remark
payTypeName String payment type name
orderAmount String order amount
orderTime int64 Order creation time
payType int64 Payment Type 201-PIX
userInfoName String User credential name
accountNo String account number
orderStatusCode int64 Order status code 1-accepted
2-bank processing
4-Failed(Bank rejection)
8-success
16-Failed
groundStatus int64 mark status
orderPayTime int64 order payment time
errorMsg String Error message
errorMsgEn String Error message en

At any time, the merchant can log in to the backstage of the merchant to manually trigger the callback (it is not recommended to initiate a manual callback if the order is not final), and the relevant information such as the order status in the callback information is the actual status (manualPlease pay attention to the order status when calling back. If the status of the manual callback order is not final, the platform will still initiate a notification when the order becomes final. Please pay attention to redundant processing at the business level)

# 6.4 Callback response

Remarks: All callbacks include signature information. It is recommended that merchants do a callback signature verification. After receiving the callback information, the merchant will confirm the final status of the order. Please respond to the website

Regarding the following information (content-type: application/json), if there is no normal response from the server, it will be within 30 minutes, with a total of 2 every three minutes

Notice

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

# 6.5 Callback notification URL

*** Log in to the backstage of the merchant to configure the unified callback address (manually specify the callback UR address in the order, which has a higher priority than the uniformly configured callback address. For example, if the notifyUrl parameter is specified in the order, it will be used regardless of whether there is a unified configuration of the callback notification address. notifyUrl address in the order)***

Note that the http response status_code has the highest priority, as long as the response status_code=200 is received, the response data will be ignored

# 7. Public response code

filed Type Default value and comment
code String Success "200" For others, please refer to failure code
success Bool success true, failure false, and code to keep the meaning of synchronization
msg String The textual description returned by the first-level code
data Object Reference interface list chapter

# 8. Failure code

Code Desc
200 Success
300 Parameter exception
301 IP Unauthorized
307 Signature error
500 System Error