API structure

Our REST API communicates with the terminal using JSON messages.

All requests and responses use the same JSON message format. Each message includes both system information and transaction data in one JSON object.

The message contains these common fields:

• topic – The topic of message for transaction.
• request_id – A unique ID used to match the request and response.
• app_id – Identifies the app that sends the message.
• timestamp – The time when the message is created.
• version – The message protocol version.
• biz_data – Contains the transaction business data.

The biz_data object holds the main transaction details. Its structure changes depending on the transaction type.

For example:

• A payment request includes fields like trans_type, order_amount, and merchant_order_no.
• A payment response includes the transaction result information.

More details about each field and the biz_data structure are explained in the following sections.

Common data

Different aspects of each field are defined in this document according to the following conventions.

• M: Required parameters
• C: Required parameters when some conditions are met
• O: Optional parameters
• -: Not Present

The common parameters is as follows:

Key	Parameter type	Request	Response	Description
topic	string	M	O	Message topic identifier. Please refer to the topic
request_id	string	O	O	Transaction Request ID, used to receive the corresponding response. The caller needs to remain unique.This parameter must be present when using terminal confirmation mode.
timestamp	string	O	O	Timestamp Example: 1698302992263
version	string	O	O	The API version.
app_id	string	M	O	The payment app id registered in CodePay PayPilot, Please refer to the Create payment app id
biz_data	JSONObject	M	M	Business Data. each transaction type has own business data
response_code	string	-	M	The order payment status code returned by CodePay Register, 000 means the transaction was successful, other means the transaction failed.Please refer to Response code
response_msg	String	-	C	Failed transaction error message returned by CodePay Register

Topic

Each transaction type has a message topic:

Key	Name
ecrhub.pay.order	Submit transaction
ecrhub.pay.query	Query transaction
ecrhub.pay.close	Close transaction
ecrhub.pay.batch.close	Batch close
ecrhub.pay.tip.adjustment	Tip adjustment

Transaction message

1. Submit transaction

Send transaction requests to the terminal, such as sale, void, refund, etc.

Message Topic

ecrhub.pay.order

Parameter list

Name	Type	Request	Response	Description
trans_type	String	M	M	Sale, Void, Refund etc. Please refer to Transaction type.
merchant_order_no	String	M	M	A unique id assigned by your POS to identify this transaction. No more than 32 alphanumeric characters.
orig_merchant_order_no	String	C	C	The merchant_order_no from the original transaction. If the transaction type is Void, Refund, Completion, it must be required.
price_currency	String	O	O	Price Currency, compliant with ISO-4217 standard, described with a three-character code. For example: "USD"
order_amount	String	M	M	Order amount in base currency units.
tip_amount	String	O	O	Amount paid for a tip.
tax_amount	String	O	O	Amount paid for a tax.
on_screen_tip	boolean	O	O	Whether or not to enter tips on the CodePay Register page, default is false.
cashback_amount	String	O	O	The cash-back amount included in the Sale payment request.
pay_method_id	String	O	O	Payment method id. Please refer to Payment method If the trans_type is Refund, this parameter will not required.
pay_scenario	String	O	O	Please refer to PayScenario .
card_network_type	String	O	O	Please refer to Card Type.
attach	String	O	-	Additional data. Allows merchants to submit additional data, which will be returned as is.
description	String	O	O	Description of ordered goods or services.A brief description of the goods or services purchased by the customer.
notify_url	String	O	-	Callback address for payment notification.Receive payment notifications from the CodePay gateway to call back the server address, and only when the transaction goes through the CodePay payment gateway will there be a callback.
expires	String	O	-	Order expires time, after the expires time is not allowed to be paid, unit: seconds.
confirm_on_terminal	boolean	O	-	Do you need terminal confirmation before proceeding with payment operations? The default is false. When set to true, you need to confirm the order first, otherwise you will directly enter the card reading interface.
receipt_print_mode	Integer	O	-	0: No printing, default value; 1: Print merchant copy; 2: Print customer copy; 3: Print merchant copy + customer.
required_terminal_authentication	boolean	O	-	When refund or void a transaction, does the store manager role need to authorize this operation on the terminal? default value: false.
on_screen_signature	boolean	O	-	This parameter controls the display logic of electronic signatures: true: Display the electronic signature page and print the signature information on the purchase order false: The electronic signature page will not be displayed, but the signature area needs to be printed on the purchase order But even if this parameter is set, CodePay Register still processes electronic signatures according to the following logic in the following situations: Credit card network, APP does not display signature page, fixed on receipt to print signature column Pin debit transactions do not require a signature, the APP does not display a signature page, and the receipt is not printed either .
trans_no	String	-	M	Transaction number of CodePay. which uniquely identifies a transaction.
trans_status	String	-	M	Please refer to Transaction status.
trans_end_time	string	-	M	Transaction completed time. If trans_status is successful, the returned data will include this parameters. Timezone: Local time zone, the time zone set by the payment terminal, Format: YYYY-MM-DD HH:mm:ss.
cashier	string	O	-	The cashier's id number or name, the transaction will record this field for easy tip counting.
auth_code	string	-	C	Authentication code. Returned for card transactions.
ref_no	string	-	C	Retrieval Reference Number .Returned for card transactions.
card_no	string	-	C	Card PAN number, Masked per PCI DSS (e.g., 430277****5723). Returned for card transactions.
entry_mode	string	-	C	Returned for card transactions: 1: Magnetic stripe swipe, 2: Contact chip, 3: Contactless, 4: Manual entry.
merchant_no	string	-	C	The merchant number.
merchant_name	string	-	C	The merchant name.
pay_channel_merchant_id	string	-	C	Merchant id of the payment processor.
pay_channel_terminal_id	string	-	C	Terminal id of the payment processor.
signature_url	string	-	C	The image URL of the handwritten signature value needs to be downloaded, converted to Base64, and stored in your database
card_holder_name	string	-	C	The name of the card holder

2. Query transaction

Retrieve a previous transaction, using merchant order no.

Message Topic

ecrhub.pay.query

Parameter list

Name	Type	Request	Response	Description
merchant_order_no	String	M	M	The merchant_order_no from the original transaction.
trans_type	String	-	M	Please refer to Transaction type.
price_currency	String	-	M	Price Currency, compliant with ISO-4217 standard, described with a three-character code. For example: "USD"
order_amount	String	-	M	Order amount in base currency units.
tip_amount	String	-	O	Amount paid for a tip.
tax_amount	String	-	O	Amount paid for a tax.
cashback_amount	String	-	O	The cash-back amount included in the Sale payment request.
attach	String	-	O	Additional data. Allows merchants to submit additional data, which will be returned as is.
pay_scenario	String	-	O	Please refer to PayScenario .
pay_method_id	String	-	O	Please refer to Payment method.
card_network_type	String	-	O	Please refer to Card Type.
trans_no	String	-	M	Transaction number of CodePay. which uniquely identifies a transaction.
trans_status	String	-	M	Please refer to Transaction status.
trans_end_time	string	-	M	Transaction completed time. If trans_status is successful, the returned data will include this parameters. Timezone: Local time zone, the time zone set by the payment terminal, Format: YYYY-MM-DD HH:mm:ss.
cashier	string	-	-	The cashier's id number or name, the transaction will record this field for easy tip counting.
auth_code	string	-	C	Authentication code. Returned for card transactions.
ref_no	string	-	C	Retrieval Reference Number .Returned for card transactions.
card_no	string	-	C	Card PAN number, Masked per PCI DSS (e.g., 430277****5723). Returned for card transactions.
entry_mode	string	-	C	Returned for card transactions: 1: Magnetic stripe swipe, 2: Contact chip, 3: Contactless, 4: Manual entry.
merchant_no	string	-	C	The merchant no.
merchant_name	string	-	C	The merchant name.
pay_channel_merchant_id	string	-	C	Merchant id of the payment processor.
pay_channel_terminal_id	string	-	C	Terminal id of the payment processor.

3. Close transaction

Cancel the current pending transaction screen.

Message Topic

ecrhub.pay.close

Parameter list

Name	Type	Request	Response	Description
merchant_order_no	String	C	C	The merchant_order_no from the original transaction.

4. Batch Close

Message Topic

ecrhub.pay.batch.close

5. Tip Adjustment

Message Topic

ecrhub.pay.tip.adjustment

Parameter list

Name	Type	Request	Response	Description
merchant_order_no	String	M	-	The merchant_order_no from the original transaction.
tip_adjustment_amount	String	M	-	Amount for tip adjustment