Parameters

PaySceneCode

PaySceneCode	Description
API	Chain Payment
PLATON_QRPAY	PlatON QRPAY

PaySceneParams

If PaySceneCode=	paySceneParams
API	chainCode (Required) payChannelCode (Required) payerEmail (Optional)

If PaySceneCode=	paySceneParams
PLATON_QRPAY	none

InteractionParams

If PaySceneCode=	interactionParams
API	payChannelCode=CHAIN address confirm network status
PLATON_QRPAY	qrcontent

redirectUrl: The website address provided by the merchant. After the order payment is successful, the user will be redirected to this address.

payChannelCode: The payment channel code specified by the merchant, e.g. CHAIN.

address: The address returned to the merchant to complete the payment through a chain address transfer.

payerEmail: The email of the payer. A payment success email will be sent to this email address.

confirm: The block height confirmed.

network: The network code.

status: The deposit address status, e.g. ENABLED.

qrcontent: A URL link for QR code payments

Supported currencies (currency)

Currency	Precision	Description
USDT	2	Tether stablecoin
ETH	6	Ethereum cryptocurrency
USDC	2	USD Coin stablecoin
BTC	2	Bitcoin cryptocurrency

This table shows the relationship matrix between currencies and chain codes.

Currency\ChainCode	TRON	ETH	BTC
USDT	Y	Y	N
ETH	N	Y	N
USDC	Y	Y	N
BTC	N	N	Y

Note: TRON and ETH chain codes support the USDT and USDC currencies, while the BTC chain code only supports the BTC currency.

Merchant Order Number (merchantOrderNo)

The merchant's payment order number is generated by the merchant, and only supports the combination of English half-width characters such as letters, numbers, hyphens (-), and underscores (_). BonusPay requires that the merchant order number remain unique (it is recommended to generate the order number based on the current system time plus a random sequence). When initiating a new payment, the original order number should be used to avoid duplicate payments; order numbers that have already been paid or have been cancelled (see the API list below) cannot be used to initiate a new payment.

Field Type Description

AcquireOrder

Field Name	Variable Name	Required	Type	Example	Description
Request Time	requestTime	Required	Timestamp(3)	1581493898000	The time when the order was created
Merchant Order No	merchantOrderNo	Required	String(64)	S10000	The unique order number generated by the merchant
BonusPay Order No	orderNo	Required	String(32)	O1000	The unique order number generated by BonusPay
Order Status	status	Required	AcquireOrderStatus	-	The current status of the order
Payment Info	paymentInfo	Optional	PaymentInfo	-	The payment information, including payment channel and payment address
Settlement Info	settlementInfo	Optional	SettlementInfo	-	The settlement information, including currency and settlement amount
Product Name	product	Required	String(200)	Crypto Basic Payment Gateway	The name of the product purchased
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	Money	"refAmount":{ "exchangeCurrencyCode":"USDT", "refAmount":{ "amount":10000000, "currency":"INR" } }	The refAmount will convert to exchangeCurrency and amount to be the total amount of orders
Actual Amount	actualTotalAmount	Optional	Money		The actual amount of the order after discounts or promotions
Payee Member ID	payeeMid	Required	String(200)	200000023456	The ID of the payee member
Expiration Time	expiredTime	Required	Timestamp(3)	1581493898000	The expiration time of the order
Notify URL	notifyUrl	Required	String(200)	-	The URL to which the notification of the order status will be sent
Subject	subject	Required	String(200)	-	The title of the product purchased
Accessory Content	accessoryContent	Optional	AccessoryContent	-	Additional information about the order, such as the order description or the product image
Payment Scene Code	paySceneCode	Required	String(200)	-	The code for the payment scene, such as CHECK_OUT or API
Fail Code	failCode	Optional	String(50)	-	The code for the reason why the order failed
Fail Description	failDes	Optional	String(200)	-	The description for the reason why the order failed
Reserved	reserved	Optional	String(200)		Merchant reserved field, the returned content will be the same as the content submitted by the merchant

PaymentInfo

Field Name	Variable Name	Required	Type	Example	Description
Payment Amount	paidAmount	Required	Money	-
Payment Time	paidTime	Required	Timestamp(3)	-
Payer Fee	payerFeeAmount	Optional	Money	-
Payment Channel	payChannelCode	Required	String(32)	-	CHAIN-Chain Payment
txHash	txHash	Optional	String(100)	-	If payChannelCode=PLATON_QRPAY
Payee Address	payeeAddress	Optional	String(32)	-	If payChannelCode=PLATON_QRPAY
Payer Address	payerAddress	Optional	String(32)	-	If payChannelCode=PLATON_QRPAY

SettlementInfo

Field Name	Variable Name	Required	Type	Example	Description
Settlement Time	settledTime	Required	Timestamp(3)	-
Payee Fee	payeeFeeAmount	Optional	Money	-
Settlement Amount	settlementAmount	Optional	Money	-

Money

Field Name	Variable Name	Required	Type	Example	Description
Amount	amount	Required	Decimal(12,8)	123.45	Amount of money
Currency	currency	Required	String(32)	BUSD	Currency type

AccessroyContent

Field Name	Variable Name	Required	Type	Example	Description
Amount Detail	amountDetail	Optional	AmountDetail	-	Detailed information of the amount involved in the transaction
Goods Detail	goodsDetail	Optional	GoodsDetail	-	Detailed information of the goods in the transaction
Terminal Detail	terminalDetail	Optional	TerminalDetail	-	Detailed information of the terminal used for the transaction

AmountDetail

Field Name	Variable Name	Required	Type	Example	Description
Discountable Amount	discountableAmount	Optional	Money	-	The amount that can be discounted from the transaction amount
Net Amount	amount	Optional	Money	-	The net amount of the transaction
VAT Amount	vatAmount	Optional	Money	-	The amount of value-added tax involved in the transaction
Tip Amount	tipAmount	Optional	Money	-	The tip amount involved in the transaction

GoodsDetail

Field Name	Variable Name	Required	Type	Example	Description
Product Description	body	Optional	String(64)	Apple Gifts	A brief description of the product
Product Category Tree	categoriesTree	Optional	String(64)	-	The category tree of the product
Product Category	goodsCategory	Optional	String(64)	-	The category of the product
Product ID	goodsId	Optional	String(200)	10	The ID of the product
Product Name	goodsName	Optional	String(64)	iPad Pro	The name of the product
Product Price	price	Optional	Money	-	The price of the product
Product Quantity	quantity	Optional	Decimal(12,2)	12	The quantity of the product
Product URL	showUrl	Optional	String(500)	-	The URL of the product

TerminalDetail

Field Name	Variable Name	Required	Type	Example	Description
Operator ID	operatorId	Optional	String(200)	8729	The ID of the operator
Store ID	storeId	Optional	String(200)	AD210	The ID of the store
Terminal ID	terminalId	Optional	String(200)	T367	The ID of the terminal
Merchant Name	merchantName	Optional	String(64)	KFC	The name of the merchant or vendor
Store Name	storeName	Optional	String(64)	KFC	The name of the store or branch location

RefundOrder：

Field Name	Variable Name	Required	Type	Example	Description
Merchant Order No.	refundMerchantOrderNo	Required	String(64)	RF1234	Merchant defined refund order number, unique for each refund transaction
BonusPay Order No.	orderNo	Required	String(32)	10003000202	BonusPay generated order number for the transaction to be refunded
Original Merchant Order No.	originMerchantOrderNo	Required	String(64)	O134	Merchant defined order number for the original transaction
Refund Fee	refundFee	Optional	Money	-	Fee charged for processing the refund transaction
Chain Code	chainCode	Optional	String(32)	-	Code for the chain on which the refund is processed
Refund Address	refundAddress	Optional	String(128)	-	Address for the refund transaction on the chain
Refund Status	status	Required	RefundOrderStatus	-	Current status of the refund transaction
Refund Amount	refundAmount	Required	Money	-	Amount to be refunded to the user for the transaction
Notification URL	notifyUrl	Optional	String(200)	-	URL for the backend notification of the refund transaction
Refund Reason	reason	Optional	String(64)	-	Reason for the refund transaction
Error Code	failCode	Optional	String(50)	-	Code for the reason of the failed transaction
Error Description	failDes	Optional	String(200)	-	Description of the reason for the failed transaction
Reserved Field	reserved	Optional	String(200)	-	Field for merchant use, BonusPay will return the same content submitted by the merchant

RefundSummary：

Field Name	Variable Name	Required	Type	Example	Description
Acquire Amount	acquireAmount	Required	Money	-	Amount acquired for the original transaction, the maximum refund amount
Remain Refund Amount	remainRefundAmount	Required	Money	-	Remaining refundable amount for the original transaction, based on the previous refund transactions

ResponseHeader

Field Name	Variable Name	Required	Type	Example Value	Description
Request State	applyStatus	Required	String(16)	SUCCESS	SUCCESS - application successful FAIL - application failed ERROR - application exception
Return Error Code	code	Required	String(10)	0	The return code
Return Message	msg	Optional	String(200)	-	Return message

OrderIndexRequest

Field Name	Variable Name	Required	Type	Example Value	Description
Merchant Order No	merchantOrderNo	Optional	String(64)	T0101	Either merchantOrderNo or orderNo is required, they cannot be empty at the same time and cannot have values at the same time
BonusPay Order No	orderNo	Optional	String(32)	22000000000001

ChainPaymentOrder

Field Name	Variable Name	Required	Type	Example Value	Description
Network	network	Required	String(64)	TRON
Deposit Address	address	Optional	String(32)	22000000000001
Deposited Amount	depositedAmount	Optional	Money
Payment Completion Time	paidTime	Optional	Timestamp(3)
Order Status	status	Required	ChainPaymentOrderStatus	COMPLETED
Creation Time	createdTime	Required	Timestamp(3)
Payer Email	payerEmail	Optional	String(200)

PaymentDepositEvent

The PaymentDepositEvent is an event that indicates a payment deposit has been confirmed and completed on the blockchain network. Here are the field descriptions:

Field Name	Variable Name	Required	Type	Example	Description
Event ID	id	Required	String(64)	PD001	Unique ID for the event
Network	network	Required	String(64)	TRON	The blockchain network name
Payer Address	payerAddress	Required	String(200)	TAUy...	The address of the payer
Receiver Address	receiverAddress	Required	String(200)	TBRv...	The address of the receiver or deposit address
Deposit Amount	amount	Required	Money	100.00 BUSD	The deposited amount and currency
Confirmed Time	confirmedTime	Required	Timestamp(3)	1620451345000	The confirmed time of the deposit, in milliseconds since Unix epoch
Created Time	createdTime	Required	Timestamp(3)	1620451323000	The time when the event was created, in milliseconds since Unix epoch
Transaction Hash	txHash	Required	String(200)	0xabc...	The transaction hash of the deposit transaction on the blockchain network

The PaymentDepositEvent is typically used to confirm that a payment has been successfully deposited on the blockchain network and to trigger further actions or notifications, such as updating a user's account balance or sending a confirmation email.