Place Order

API is used by the merchant system to generate an Acquire order in the BonusPay backend, and response wallet address to receive the transfer.

The AcquireOrderStatus is a status machine that represents the status of the acquire order, which is the order created by the merchant through the BonusPay service. The status can be one of the following:

• CREATED: The order has been created.

• SUCCESS: The order has been successfully processed and completed.

• FAILURE: The order has failed to be processed.

• REFUNDED: The order has been refunded.

The API endpoint for this interface has two URLs:

For testing purposes, the URL is: http://api.testbonuspay.network/sgs/api/crypto/placeOrder

For production purposes, the URL is: https://api.bonuspay.network/sgs/api/crypto/placeOrder

Request Parameters

Submit an acquire order request. This is an idempotent interface. Repeated requests with the same merchantOrderNo will return the current status of the order. Idempotent requests do not check the request time. If there are multiple requests, the request time of the first request is used as the reference time.

Http Header

Field Name	Variable Name	Required	Type	Example	Description
Language	Content-Language	Optional	String(10)	en	en-English (default)
Signature	sign	Required	String
Partner ID	Partner-Id	Required	String(12)

Http Body

Field Name	Variable Name	Required	Type	Example	Description
Request Time	requestTime	Required	Timestamp(3)	1581493898000
Business Content	bizContent	Required	PlaceAcquireOrderRequest	-	Business Content

PlaceAcquireOrderRequest

Field Name	Variable Name	Required	Type	Example	Description
Merchant Order Number	merchantOrderNo	Required	String(64)	-
Product Name	subject	Required	String(64)	Ipad
Order Amount	totalAmount	Optional(when refAmount is exist)	Money	"totalAmount":{ "currency":"ETH", "amount":1.01 }	The total amount of the order
Reference Amount	refAmount	Optional	"refAmount":{ "exchangeCurrencyCode":"[Order Currency]", "refAmount":{ "amount":[Original amount], "currency":"[Original Currency]" } }	"refAmount":{ "exchangeCurrencyCode":"USDT", "refAmount":{ "amount":100000, "currency":"INR" } }	The refAmount will convert to exchangeCurrency and amount to be the total amount of orders,eg: send 10000 INR and convert to USDT to accecpt
Expiration Time	expiredTime	Optional	Timestamp(3)	1581493898000	Must not exceed 48 hours from the request time.<br>Default 2 hours.
Payee Member Number	payeeMid	Optional	String(20)	-	If not filled, it is the merchant itself by default.
Payment Scene Code	paySceneCode	Required	String(200)	-
Payment Scene Parameters	paySceneParams	Optional	String(512)	-	Parameters needed for the payment scene
Backend Notification URL	notifyUrl	Optional	String(200)	-	The URL for the merchant to receive notifications.
Accessory Content	accessoryContent	Optional	AccessoryContent	-
Reserved Field	reserved	Optional	String(200)	Merchant reserved field, the returned content will be same with the content submitted by the merchant

Request Example

Http Header
{
    "Content-Language": "en",
    "Content-Type": "application/json",
    "sign": "IXJI/QicPQotIsIDBcSGIg6jtJUXs1rTuifQFZUNd3KDTl25GKmpYO7OrkaKkTV0shDRitLmkxJCe3Z60zHE2ZSeVczrhwrnmuMG+bX9N22Hw821H6MydsXetYHRnyf5dPbgpmVja582w49grA6jRlVFAVMYdxKJDPSCb2X/IpltvyrLQ1Wt+lqr+fnpYXvyON6/PIZIQIknC8BVddVahxJnaC6HEagvJf6gskz22/DFfPHT1mlMA9pg8qrbh4O7DYZahf8TB3nIzAPc/FHOUZkYYTT2c8m4eLL8740nJVK7D3IOSqSnBAU/iJ2omjPPFvRCCSqzz17pkGsT7AW91w==",
    "Partner-Id": "200000000888"
}

Http Body
{
	"requestTime": 1581404947666,
	"bizContent": {
        "expiredTime": 1682595048033,
		"merchantOrderNo": "M965739182419",
		"subject": "Your subject",
		"totalAmount": {
			"currency": "ETH",
			"amount": 1.01
		//if place order with refAmount
		// "refAmount":{
                //"exchangeCurrencyCode":"USDT",
                //"refAmount":{
                //    "amount":10000000,
                //    "currency":"INR"
                //} 
		},
		"paySceneCode": "API",
        "paySceneParams": {
            "chainCode": "ETH",
            "payChannelCode": "CHAIN"
        },
        "reserved": "order desc",
	"notifyUrl": "http://www.yoursite.com",
		
		}
	}
}

Response Parameters

If the order status is CREATED, different interActionParams will be returned based on different paySceneCode.

Http Header

Field Name	Variable Name	Required	Type	Example	Description
Signature	sign	Required	String	-

The body field in Http Body is returned only when applyStatus is SUCCESS and code is 0.

Http Body

Field Name	Variable Name	Required	Type	Example	Description
Response Header	head	Required	ResponseHeader	-
Response Body	body	Optional	PlaceOrderResponse	-

PlaceAcquireOrderResponse

Field Name	Variable Name	Required	Type	Example	Description
Order Information	acquireOrder	Optional	AcquireOrder	-
Payment Parameters	interactionParams	Optional	InteractionParams	-

Response Example

Http Header
{
  "sign": "JzWjVQ245trg3p0CyuwUUHN+Ck40q/HDaMvhqueHDP8YHqC/Uw3c9VWCw4gKsNbk+CRShjT+bvKkck8Fc3aAiRK8wIVQz6eu95sPkJgZp5A0P+tfMH/44F+3CrejtbEIkrHdSwhy98Tv9TYs9QFe7Yni/vEJ8P4OU6FZJOi8LGOMF6Nc8+S5qftc7qLA17cNJ7NJYC+EW8suGe/NmGA9c5NMK5BwHTHzXYOjXwXLx8mw4M3hiirl0wtVym3hrOmbkujYZCH56h8uOVF0FbHGu5uoq61NuniJitLLs9qyiEprQzUe8oWsJnHKXeGAgEr//fLXIXgYsRYb7AWoJzs6Eg=="
}

Http Body
{
    "body":{
        "acquireOrder":{
            "merchantOrderNo":"510a42b5-9615-4f5d-91b6-0885768bb415",
            "orderNo":"131682663868005325",
            "status":"CREATED",
            "product":"Crypto Basic Payment Gateway",
            "totalAmount":{
                "currency":"USDT",
                "amount":10
            },
            "actualTotalAmount":{

            },
            "payeeMid":"200000344358",
            "expiredTime":1682750264084,
            "notifyUrl":"http://yoursite.com/api/notification",
            "subject":"ipad",
            "requestTime":1682663864087,
            "paySceneCode":"API",
            "reserved":"order desc"
        },
        "interActionParams":{
            "confirm":"27",
            "address":"TKGH6ag1DC4Z17XgUbJwnYSDzT2QToAfvk",
            "minDepositAmount":"1.00000000",
            "network":"TRON",
            "status":"ENABLED"
        }
    },
    "head":{
        "applyStatus":"SUCCESS",
        "code":"0",
        "msg":"SUCCESS",
        "traceCode":"000000"
    }
}

Response Code

Code	Msg	Reason	Solution
0	SUCCESS	Success
400	INVALID_PARAMETER	Invalid parameter	Adjust request parameters
400	REQUESTTIME_TOO_EARLY	The request time is too early	Adjust request time
400	REQUESTTIME_TOO_LATER	The request time is too late	Adjust request time
402	RATE_LIMIT_REJECT	Request too frequently	Reduce request frequency
403	UNAUTHORIZED	Unauthorized API	Contact BonusPay
404	SERVICE_NOT_AVAILABLE	API service not available	Contact BonusPay
500	SYSTEM_ERROR	System error	Contact BonusPay<br>Retry later
504	SERVICE_TIMEOUT	Service timeout	Retry later
601	RISK_FAIL	Risk verification fails	Adjust business
77001	ORDER_PAID	The order has been successfully supported and does not support revocation	Adjust merchant order number
77002	ORDER_FAILURE	Failed order initiated to create an order	Adjust merchant order number
77003	ORDER_SETTLED	Settled order initiated to create an order	Adjust merchant order number
77007	EXPIREDTIME_LESS_THAN_REQUESTTIME	The expiration time is less than the request time	Adjust the expiration time
77008	EXPIREDTIME_TOO_LATER	The expiration time exceeds 48 hours from the request time	Adjust the expiration time
77011	PAYSCENECODE_ILLEGAL	Illegal payment scenario code	Adjust payment scenario code
77012	MERCHANT_ORDER_NO_EXIST	The same order number but different business parameters are requested to create an order	Adjust order number
77021	CURRENCY_CODE_NOT_SUPPORTED	Currency code not supported	Adjust request parameters
77022	INVALID_CURRENCY_PRECISION	Invalid currency precision	Adjust request parameters
77023	PAYEEMID_NOT_EXIST	Incorrect recipient account number	Adjust recipient account