Transaction Message

Native Payment

Transaction Type: Backend transaction

Unified submission address (except for cashier payment): https://openapi.basicex.com/basicexpay/trade/gateway

Request Method: POST

Content-Type: application/json

Note: It is recommended to use the Cashier Payment (basicexpay.trade.cashier) interface for submitting payment orders;

If you choose to use native payment, please use the Transaction Pre-Creation (basicexpay.trade.precreate) interface for submission (only supports BasicEx multi-platform payment).

Cashier Payment (basicexpay.trade.cashier)

Transaction Type: Frontend transaction

Cashier payment is a frontend transaction that is submitted through a form.

Request Method: POST

Content-Type: application/x-www-form-urlencoded

Submission Address: https://openapi.basicex.com/basicexpay/trade/cashier

The parameters submitted through the form have a fixed name of "data", and the value of the parameter is a JSON string that the merchant backend signs and assembles according to the public parameters and request parameter instructions. Here is an example of the form submission page:

<form id="cashier" method="post" contentType="application/x-www-form-urlencoded;charset=utf-8" action="https://openapi.basicex.com/basicexpay/trade/cashier">
	<input type="hidden" name="data" id="data" value="{"merNo":"811496833912834","method":"basicexpay.trade.cashier","timestamp":"20230221155554","nonce":"PIYuG0gFpMhGaDIU","bizConent":"{\"merOrderNo\":\"lZUJVCNLfhlaH1ZzEHIrjszT\",\"clientIp\":\"192.168.1.2\",\"totalAmount\":100,\"currency\":\"USDT\",\"description\":\"TopUp\",\"orderSource\":\"WEB\",\"tradeStartTime\":\"2023-02-21 15:55:54\",\"expireTime\":900,\"notifyUrl\":\"https://www.test.com\",\"returnUrl\":\"https://www.test.com\",\"attach\":\"123\",\"goodsDetails\":[{\"goodsType\":\"112\",\"goodsId\":\"12\",\"goodsName\":\"TopUp\",\"quantity\":1,\"price\":100}]}","signType":"HmacSHA512","sign":"0AF6A4113EC32E9F4A69B62B8842D25AEA7B8C91B260FE98CCF8CEB622F19F1601A4A402999EE2A45CB78B1E8C1961DE4591B3273CB99A85DF5C46DE21B35476"}"/>
</form>
<script>document.forms['cashier'].submit();</script>

Request Parameter Instructions

Note: The order of these request parameters must follow the table below

Parameter	Type	Required	Parameter Description	Example
merOrderNo	string(32)	Yes	Merchant order number, unique within the merchant	202202161004008765432
clientIp	string(20)	Yes	Client IP address where the order is placed	192.168.1.12
totalAmount	decimal(12,2)	Yes	Total order amount, accurate to 2 decimal places	200
currency	string(100)	Yes	Currency, supports USDT, BUSD, BCNY	USDT
description	string(255)	Yes	Description of the goods, displayed on the cashier page	Top-up
orderSource	string(10)	Yes	Order source, APP/WEB/WAP/OTHERS	WEB
tradeStartTime	string(19)	Yes	Transaction initiation time in the format of yyyy-MM-dd HH:mm:ss	2022-02-16 10:04:00
expireTime	string(4)	No	Order expiration time, fixed value 900, in seconds	900
notifyUrl	string(255)	No	Backend notification URL, the callback address for receiving asynchronous payment results, must be accessible from the Internet	https://api.xxx.com/cashier/notify
returnUrl	string(255)	No	Frontend redirect URL, the address to return to the merchant's website after payment completion, must be accessible from the Internet	https://api.xxx.com/cashier/redirect
attach	string(100)	No	Additional data
**+**goodsDetails		No	Goods details (fill in if necessary)
└ goodsType	string(8)	Yes	Goods category	2101
└ goodsId	string(50)	Yes	Goods ID	1001121
└ goodsName	string(100)	Yes	Goods name	Top-up
└ quantity	int(10)	Yes	Goods quantity	1
└ price	string(12)	Yes	Goods unit price, accurate to 2 decimal places	200

Request Message Example

{
  "merOrderNo": "swR75kHGS2jQYfeN",
  "clientIp": "127.0.0.1",
  "totalAmount": 18.37,
  "currency": "USDT",
  "description": "Top-up",
  "orderSource": "APP",
  "tradeStartTime": "2023-03-31 22:03:53",
  "expireTime": 900,
  "notifyUrl": "https://google.com",
  "returnUrl": "https://google.com",
  "attach": "",
  "goodsDetails": [
    {
      "goodsType": "01",
      "goodsId": "100001",
      "goodsName": "Test",
      "quantity": 1,
      "price": 18.37
    }
  ]
}

Response Parameter Description

After submitting the parameters in the form, the page will automatically redirect to the BasicEx cashier page.

Transaction Pre-Creation (basicexpay.trade.precreate)

Transaction Type: Backend Transaction

Request Parameter Instructions

Note: The order of these request parameters must follow the table below

Parameter	Type	Required	Parameter Description	Example
merOrderNo	string(32)	Yes	Merchant order number, unique within the merchant	202202161004008765432
clientIp	string(20)	Yes	Client IP address where the order is placed	192.168.1.12
totalAmount	decimal(12,2)	Yes	Total order amount, accurate to 2 decimal places	200
currency	string(20)	Yes	Currency, supports USDT, BUSD, BCNY	USDT
network	string(20)	No	Transfer network, supports ERC20, TRC20, POLYGON, BSC, must be provided for external deposits	TRC20
description	string(255)	Yes	Description of the goods, may be displayed on the cashier page	Top-up
orderSource	string(10)	Yes	Order source, APP/WEB/WAP/OTHERS	WEB
tradeStartTime	string(19)	Yes	Transaction initiation time, 19 characters, format: yyyy-MM-dd HH:mm:ss	2022-02-16 10:04:00
expireTime	string(4)	No	Order expiration time, fixed value of 900, in seconds	900
notifyUrl	string(255)	No	Backend notification address, callback URL to receive asynchronous payment result notifications, must be accessible from the internet	https://api.xxx.com/cashier/notify
returnUrl	string(255)	No	Frontend redirect address, URL to return to the merchant's website after payment completion, must be accessible from the internet	https://api.xxx.com/cashier/redirect
attach	string(100)	No	Additional data
network	string(20)	No	Transfer network, supports ERC20, TRC20, POLYGON, BSC, must be provided for external deposits	TRC20
**+**goodsDetails		No	Goods details (fill in if applicable)
└ goodsType	string(8)	Yes	Goods category	2101
└ goodsId	string(50)	Yes	Goods ID	1001121
└ goodsName	string(100)	Yes	Goods name	Top-up
└ quantity	int(10)	Yes	Goods quantity	1
└ price	string(12)	Yes	Goods unit price, accurate to 2 decimal places	200

Request Message Example

{
  "merOrderNo": "swR75kHGS2jQYfeN",
  "clientIp": "127.0.0.1",
  "totalAmount": 18.37,
  "currency": "USDT",
  "description": "Top-up",
  "orderSource": "APP",
  "tradeStartTime": "2023-03-31 22:03:53",
  "expireTime": 900,
  "notifyUrl": "https://google.com",
  "returnUrl": "https://google.com",
  "attach": "",
  "goodsDetails": [
    {
      "goodsType": "01",
      "goodsId": "100001",
      "goodsName": "Test",
      "quantity": 1,
      "price": 18.37
    }
  ]
}

Response Parameter Description

Parameter	Type	Required	Parameter Description	Example
orderNo	string(32)	Yes	System order number generated by BasicEx	202201261004008765432
merOrderNo	string(32)	Yes	Merchant system internal payment order number, same as the request parameter	202201261004008765432
totalAmount	decimal(12,2)	Yes	Total order amount, accurate to 2 decimal places	200
currency	string(20)	Yes	Currency, supports USDT, BUSD, BCNY	USDT
network	string(20)	No	Transfer network, same as the request parameter	TRC20
orderSource	string(10)	Yes	Order source, same as the request parameter	WEB
codeUrl	string(255)	Yes	Payment QR code data, displayed as a QR code for users to scan and pay	https://qr.basicex.com/811496833912834/C1E988EBCE9EA8DD2CC3A99AB9354EF3
attach	string(100)	No	Additional data, same as the request parameter

Transaction Query (basicexpay.trade.query)

Transaction Type: Backend Transaction

Request Parameter Description

Note: The order of these request parameters must follow the table below

Parameter	Type	Required	Parameter Description	Example
merOrderNo	string(32)	No	Merchant system internal payment order number, cannot be empty when orderNo is empty	202202161004008765432
orderNo	string(32)	No	System order number generated by BasicEx, cannot be empty when merOrderNo is empty	202202161004008765431

Request Message Example

{
    "merOrderNo": "202202161004008765432"
}

Response Parameter Description

Parameter	Type	Required	Parameter Description	Example
orderNo	string(32)	Yes	System order number generated by BasicEx, same as the request parameter	202201261004008765432
merOrderNo	string(32)	Yes	Merchant system internal payment order number, same as the request parameter	202201261004008765432
totalAmount	decimal(12,2)	Yes	Total order amount, accurate to 2 decimal places, same as the request parameter	200
currency	string(20)	Yes	Currency, supports USDT, BUSD, BCNY, same as the request parameter	USDT
status	string(2)	Yes	Transaction status: 0: Waiting for user payment, 1: Processing, 2: Transaction successful, 3: Expired, 4: Transaction failed	2
tradeFinishTime	string(19)	Yes	Transaction completion time	2022-02-13 16:29:07
transactionId	string(60)	No	Transaction order number	202201261004008765432
buyerid	string(50)	No	Payer identifier
attach	string(100)	No	Additional data, same as the request parameter

Refund (basicexpay.trade.refund)

Transaction Type: Backend Transaction

Request Parameter Description

Note: The order of these request parameters must follow the table below

Parameter	Type	Required	Parameter Description	Example
merOrderNo	string(32)	No	Merchant system internal payment order number, cannot be empty when orderNo is empty	202202161004008765432
orderNo	string(32)	No	System order number generated by BasicEx, cannot be empty when merOrderNo is empty	202202161004008765431
merRefundOrderNo	string(32)	Yes	Merchant refund order number	202202161004008765435
refundAmount	decimal(12,2)	Yes	Refund amount	100
refundReason	string(100)	Yes	Refund reason	Refund
tradeStartTime	string(19)	Yes	Transaction initiation time, 19 digits, format: yyyy-MM-dd HH:mm:ss	2022-02-13 16:29:07

Request Message Example

{
    "merOrderNo": "202202161004008765432",
    "merRefundOrderNo": "202202161004008765123",
    "refundAmount": 100,
    "refundReason": "Refund",
    "tradeStartTime": "2022-02-13 16:29:07"
}

Response Parameter Description

Parameter	Type	Required	Parameter Description	Example
orderNo	string(32)	No	System order number generated by BasicEx, same as the request parameter	202201261004008765432
merOrderNo	string(32)	No	Merchant system internal payment order number, same as the request parameter	202201261004008765431
merRefundOrderNo	string(32)	Yes	Merchant refund order number	202201261004008765436
refundOrderNo	string(32)	Yes	System refund order number	202201261004008765435
refundAmount	decimal(12,2)	Yes	Refund amount, accurate to 2 decimal places, same as the request parameter	100
refundStatus	string(2)	Yes	Refund status: 0: Refund in progress, 1: Pending approval, 2: Refund successful, 3: Refund failed	2

Refund Query (basicexpay.trade.refund.query)

Transaction Type: Backend Transaction

Request Parameter Description

Note: The order of these request parameters must follow the table below

Parameter	Type	Required	Parameter Description	Example
merRefundOrderNo	string(32)	No	Merchant refund order number, cannot be empty when refund system order number orderNo is empty	202202161004008765432
refundOrderNo	string(32)	No	System refund order number generated by BasicEx, cannot be empty when merchant refund order number merOrderNo is empty	202202161004008765431

Request Message Example

{
    "merRefundOrderNo": "202202161004008765432"
}

Response Parameter Description

Parameter	Type	Required	Parameter Description	Example
refundOrderNo	string(32)	Yes	System refund order number generated by BasicEx, same as the request parameter	202201261004008765432
merRefundOrderNo	string(32)	Yes	Merchant refund order number, same as the request parameter	202201261004008765432
refundAmount	decimal(12,2)	Yes	Refund amount, accurate to 2 decimal places, same as the request parameter	200
status	string(2)	Yes	Transaction status: 0: Refund in progress, 1: Pending approval, 2: Refund successful, 3: Refund failed	2
tradeFinishTime	string(19)	Yes	Transaction completion time	2022-02-13 16:29:07
transactionId	string(60)	No	Transaction ID	202201261004008765432
attach	string(100)	No	Additional data, same as the request parameter

Agent Pay (basicexpay.trade.agentpay)

Transaction Type: Backend Transaction

Agent pay transaction is a settlement service provided by BasicEx Pay to meet the merchant's fund withdrawal needs, allowing the merchant to pay funds from their BasicEx Pay account to a specified BasicEx Wallet or a specified Blockchain wallet address.

BasicEx Wallet refers to personal or corporate users who register through the BasicEx Wallet official website. BasicEx Pay will create a BasicEx Wallet for them. The cash accounts of BasicEx Wallets can transfer funds to each other, and funds of different currencies are independent. The same email address, phone number, BasicEx ID, and username can uniquely identify a BasicEx Wallet. The recipient's wallet is determined by specifying the payment recipient type (targetType) and the recipient (target).

Blockchain wallet address: BasicEx Pay supports agent pay requests to wallet addresses on networks such as TRC20, ERC20, POLYGON, and BSC. When agent pay needs to be made to a blockchain wallet address, the recipient type (targetType) must be set to "ADDRESS", and the recipient (target) should be the specific blockchain wallet address.

When the transaction status (status) in the response message is "failed", the order has failed and the merchant can retry the transaction.

When the transaction status (status) in the response message is "processing", the merchant can independently call the Agent Pay Result Query interface to check the status of the order.

Before initiating an agent pay transaction, please ensure that the merchant's cash account has sufficient funds to reduce the chance of transaction failure.

Request Parameter Description

Note: The order of these request parameters must follow the table below

Parameter	Type	Required	Parameter Description	Example
merOrderNo	string(32)	Yes	Merchant order number, unique within the same merchant	202202161004008765432
clientIp	string(32)	No	Client IP address	192.168.1.12
targetType	string(12)	Yes	Type of recipient, can be EMAIL, TELEPHONE, BEID, USERID, ADDRESS	EMAIL
target	string(64)	Yes	Recipient [target] cannot be empty, can be email, phone number, BasicEx ID, username, or address	[email protected]
totalAmount	decimal(12,2)	Yes	Total order amount, accurate to 2 decimal places	100
currency	string(50)	Yes	Currency, supports USDT, BUSD, BCNY	USDT
network	string(50)	No	Network, supports TRC20, ERC20, POLYGON, BSC, required when targetType is ADDRESS	TRC20
description	string(255)	Yes	Description	Salary
orderSource	string(10)	Yes	Order source, APP/WEB/WAP/OTHERS	WEB
tradeStartTime	string(19)	Yes	Transaction start time, 19 digits, format: yyyy-MM-dd HH:mm:ss	2022-02-13 16:29:07
notifyUrl	string(255)	No	Agent pay result notification URL, the callback URL that asynchronously receives agent pay result notifications, must be accessible from the internet	https://api.xxx.com/cashier/notify
attach	string(100)	No	Additional data, will be returned as is

Request Message Example

{
  "merOrderNo": "drZW6FffaGpit7Db",
  "clientIp": "127.0.0.1",
  "targetType": "EMAIL",
  "target": "[email protected]",
  "totalAmount": 33.53,
  "currency": "USDT",
  "network": "TRC20",
  "description": "Salary",
  "orderSource": "APP",
  "tradeStartTime": "2023-03-31 22:27:46",
  "notifyUrl": "https://api.xxx.com/cashier/notify",
  "attach": ""
}

Response Parameter Description

Parameter	Type	Required	Parameter Description	Example
orderNo	String(32)	Yes	System order number generated by BasicEx Pay, same as the request parameter	202201261004008765432
merOrderNo	String(32)	Yes	Merchant system internal payment order number, same as the request parameter	202201261004008765432
totalAmount	Decimal(12,2)	Yes	Total order amount, accurate to 2 decimal places, same as the request parameter	200
currency	String(20)	Yes	Currency, supports USDT, BUSD, BCNY, same as the request parameter	USDT
orderSource	string(10)	Yes	Order source, APP/WEB/WAP/OTHERS	WEB
status	String(2)	Yes	Transaction status: 0: Processing, 1: Transaction successful, 2: Transaction failed	1
attach	String(100)	No	Additional data, same as the request parameter

Agent Pay Result Query (basicexpay.trade.agentpay.query)

Transaction Type: Backend Transaction

Request Parameter Description

Note: The order of these request parameters must follow the table below

Parameter	Type	Required	Parameter Description	Example
merOrderNo	string(32)	No	Merchant agent pay order number, merchant system internal agent pay order number, cannot be empty at the same time as system order number orderNo	202202161004008765432
orderNo	string(32)	No	System agent pay order number, unique order number generated by BasicEx Pay, cannot be empty at the same time as merchant agent pay order number	202202161004008765431

Request Message Example

{
    "merOrderNo": "202202161004008765432"
}

Response Parameter Description

Parameter	Type	Required	Parameter Description	Example
merOrderNo	string(32)	Yes	Merchant system internal payment order number, same as the transaction request parameter	202201261004008765431
orderNo	string(32)	Yes	System order number generated by BasicEx Pay, same as the transaction request parameter	202201261004008765432
targetType	string(12)	Yes	Type of recipient, same as the transaction request parameter	EMAIL
target	string(64)	Yes	Recipient, same as the transaction request parameter	[email protected]
totalAmount	decimal(12,2)	Yes	Total order amount, accurate to 2 decimal places, same as the transaction request parameter	200
currency	string(20)	Yes	Currency, supports USDT, BUSD, BCNY, same as the transaction request parameter	USDT
network	string(50)	No	Network, same as the transaction request parameter	TRC20
description	string(19)	Yes	Agent pay description, same as the transaction request parameter	Salary
orderSource	string(60)	No	Order source, same as the transaction request parameter	WEB
attach	string(100)	No	Additional data, same as the transaction request parameter
status	string(2)	Yes	Transaction status: 0: Processing, 1: Transaction successful, 2: Transaction failed	2
tradeFinishTime	string(19)	Yes	Transaction completion time	2022-02-13 16:29:07
transactionId	string(60)	No	Transaction ID	202201261004008765432

Exchange Rate Query (basicexpay.exchange.rate.query)

Transaction Type: Backend Transaction

Request Parameter Description

Note: The order of these request parameters must follow the table below

Parameter	Type	Required	Parameter Description	Example
source	string(10)	Yes	Source currency, supports USDT, BUSD, BCNY	USDT
target	string(10)	Yes	Target currency, supports CNY、EUR、HKD、INR、PHP、Rp、THB、USD、MXN	CNY

Request Message Example

{
    "source": "USDT",
    "target": "CNY"
}

Response Parameter Description

Parameter	Type	Required	Parameter Description	Example
source	string(10)	Yes	Source currency, same as the request parameter	USDT
target	string(10)	Yes	Target currency, same as the request parameter	CNY
rate	decimal(16,2)	Yes	Exchange rate, the rate at which one unit of source currency can be exchanged for target currency, for example 1 USDT = 6.96 CNY	6.96