Rapid integration with Register-SDK under local network

1. Overview

In the cross-terminal application integration solution, there are two local network connection modes to choose from: WLAN and USB. To integrate using the API method, developers need to have some experience in WebSocket communication or serial port communication. CodePay provides the RegisterSDK, which secondary packages the communication protocol layer, helping developers quickly complete payment integration in both modes.

2. Function highlights

Compared with API interface development, RegisterSDK integration is easier, providing function method calls without understanding serial or socket communication protocols. Register SDK build-in an ECRHub service module can provide better commercial experience, with the following highlights:

• Automatic network discovery
  • In WLAN mode, POS devices and terminals on the same local network can be automatically discovered without having to manually configure IP addresses and ports, and are not affected by changing IP addresses.
  • In USB mode, checking for plugged and unplugged USB cables is supported, and serial ports are automatically detected. Once an available serial port is found, it is automatically connected.
• Secure pairing
  • A pairing mechanism is only for WLAN mode. It provided to ensure communication security within the local network. It also better isolates connection when there are multiple POS devices or multiple terminals in the store.
  • The pairing operation supports initiated from the terminal (requires administrator permissions), and the POS end automatically confirms without any operation; it also supports initiating from the POS end, and the terminal manually confirms, but the developer needs to develop a pairing management function.
• Connection management
  • In WLAN mode, real-time network connection status checks are provided; transactions are automatically re-sent after the network is restored.
  • In USB enhanced mode, a heart beat detection mechanism is provided to real-time monitor the network connection status; transactions are automatically re-sent after the network is restored.

3. Device pairing

note

Note: Only WLAN connection mode needs to be paired first, USB cables mode does not need to be paired.

CodePay Register provides a device pairing function, through the application of the built-in ECRHub service and SDK to realize the registration of network information of terminals and POS devices, to discover and record each other's network information, and to complete the fast connection and secure communication.

• The pairing mechanism simplifies the process of manually configuring network addresses and is not affected by changes in terminal IP addresses.
• It can ensure the communication security in the LAN, and only the administrator authority can set the terminal to connect to the legal POS devices.
• If there are multiple POS devices and terminals in a store, it is easier to control and isolate them.

POS devices and terminals can initiate pairing operations. Considering the simplification of the integration workload of the developers, SDK only provides a pairing request initiated from the terminal app and automatically confirmed by the POS device. The following is the pairing process:

• After the POS application is launched, Register SDK automatically registers the device network information in the LAN, which can be discovered by the Register application running on the terminal in the same network.
• The store administrator searches for pairable devices on the terminal, selects the POS device and initiates a pairing request.
• After receiving the request, the Register SDK on the POS terminal automatically confirms the pairing and records the network address information of the terminal.
• The paired POS device sends connection requests and transaction commands according to the terminal network address.

Device pairing process workflow:

4. Transaction process workflow

5. SDKs

• Register-SDK for JAVA
• Register-SDK for Android

6. Transaction message

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

6.1 Sale

Sale transaction refers to the payment operation performed by the cardholder when purchasing goods or services from a merchant. The transaction amount is deducted from the cardholder's account and transferred to the merchant's account.

tip

Response program logic: Please judge the value of "response_code", then judge the value of "trans_status", when "response_code = 000", then respond to the parameter in the range of "C" and "O".

Key	Type	Request	Response	Description
app_id	string	M	M	The payment app id registered in Codepay Gateway, Please refer to the Payment gateway integration guide
merchant_order_no	string	M	M	The order number of the merchant's point of sale application or business system must be unique in its system. Example: 121775014073233368018
price_currency	string	O	O	Price Currency, compliant with ISO-4217 standard, described with a three-character code Example：USD
order_amount	string	M	M	Order amount. For example, one USD stands for one dollar, not one cent. Example: 34.50
tip_amount	string	O	O	Tip amount. This field represents the transaction tip amount. For example, 1 USD stands for one dollar, not one cent. Example: 3.50
on_screen_tip	boolean	O	-	Whether or not to enter tips on the CodePay Register page, default is false Example: true
pay_scenario	string	O	C	Payment scene, please refer to Payment scenario Example: SWIPE_CARD When "trans_status=2", the Response includes this parameter
pay_method_id	string	O	C	Specify a payment method. This field is mandatory only when "pay_scenario" is set to "SCANQR_PAY" or "BSCANQR_PAY". Refer to Payment method Example: Visa When "trans_status=2", the Response includes this parameter
card_type	string	O	-	Type of bank card，please refer to Card type
attach	string	O	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. Example: iPhone Pro
notify_url	string	O	-	Callback address for payment notification. Receive payment notifications from the Gateway to call back the server address, and only when the transaction goes through the payment gateway will there be a callback. Example: http://www.abc.com/callback?id=12345
expires	string	O	-	Order expires time, after the expires time is not allowed to be paid, unit: seconds Example: 180
confirm_on_terminal	boolean	O	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
on_screen_signature	boolean	O	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
response_code	string	-	M	Response code, Refer to Response code Example: 000
response_msg	string	-	C	Example: success
trans_no	string	-	C	Transaction number.This field represents Gateway transaction number, which uniquely identifies a transaction. Example: 5021000010210602000003 When "response_code=000", the Response includes this parameter
trans_status	string	-	C	Transaction status, please refer to Transaction status Example: 2 When "response_code=000", the Response includes this parameter
pay_channel_trans_no	string	-	C	Payment channel transaction numbers, such as RRN for Visa, Mastercard, etc. Example: 000000123 When "trans_status=2", the Response includes this parameter
discount_bmopc	string	-	O	Payment channel merchant discount amount,The merchant gives the customer a preferential amount through the payment channel, and this part of the payment channel will not be settled to the merchant. Example: 3.00 When "trans_status=2", the Response includes this parameter
discount_bpc	string	-	O	Payment channel discount amount,Discount the amount of the payment channel to the customer, and this part of the funds will be settled into the merchant account. Example: 5.00 When "trans_status=2", the Response includes this parameter
trans_end_time	string	-	C	Transaction completed time. Timezone: Local time zone, the time zone set by the payment terminal, Format: YYYY-MM-DD HH:mm:ss Example: 2021-06-03 12:48:51 When "trans_status=2", the Response includes this parameter

6.2 Sale with cashback

"Sale with Cashback" is commonly used in bank card transactions to refer to the ability of a customer to request an additional amount of cash from their bank account in addition to the cost of goods or services when paying for a purchase with a debit card. This service is usually found at the checkout counter of retail stores or supermarkets, where customers can select this option at checkout, thus avoiding the hassle of going to a bank or ATM to withdraw cash.

For example, if you spend $50 on a grocery store purchase and want $20 in cash, you can request a $70 transaction where $50 is paid to the supermarket and the remaining $20 is returned to you as cash. This transaction may appear in your bank account records as "Sale with Cashback" and total $70.

tip

Response program logic: Please judge the value of "response_code", then judge the value of "trans_status", when "response_code = 000", then respond to the parameter in the range of "C" and "O".

Key	Type	Request	Response	Description
app_id	string	M	M	The payment app id registered in Codepay Gateway, Please refer to the Payment gateway integration guide
merchant_order_no	string	M	M	The order number of the merchant's point of sale application or business system must be unique in its system. Example: 121775014073233368018
price_currency	string	O	O	Price Currency, compliant with ISO-4217 standard, described with a three-character code Example：USD
order_amount	string	M	M	Order amount. For example, one USD stands for one dollar, not one cent. Example: 34.50
cashback_amount	string	M	M	Cashback amount. Expressed in the quoted currency, for example, One USD stands for one dollar, not one cent Example: 20.00
pay_scenario	string	O	C	Payment scene, please refer to Payment scenario Example: SWIPE_CARD When "trans_status=2", the Response includes this parameter
pay_method_id	string	O	C	Specify a payment method. This field is mandatory only when "pay_scenario" is set to "SCANQR_PAY" or "BSCANQR_PAY". Refer to Payment method Example: Visa When "trans_status=2", the Response includes this parameter
card_type	string	O	-	Type of bank card，please refer to Card type
attach	string	O	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. Example: iPhone Pro
notify_url	string	O	-	Callback address for payment notification. Receive payment notifications from the Gateway to call back the server address, and only when the transaction goes through the payment gateway will there be a callback. Example: http://www.abc.com/callback?id=12345
expires	string	O	-	Order expires time, after the expires time is not allowed to be paid, unit: seconds Example: 180
confirm_on_terminal	boolean	O	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
on_screen_signature	boolean	O	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
response_code	string	-	M	Response code, Refer to Response code Example: 000
response_msg	string	-	C	Example: success
trans_no	string	-	C	Transaction number.This field represents Gateway transaction number, which uniquely identifies a transaction. Example: 5021000010210602000003 When "response_code=000", the Response includes this parameter
trans_status	string	-	C	Transaction status, please refer to Transaction status Example: 2 When "response_code=000", the Response includes this parameter
pay_channel_trans_no	string	-	C	Payment channel transaction numbers, such as RRN for Visa, Mastercard, etc. Example: 000000123 When "trans_status=2", the Response includes this parameter
discount_bmopc	string	-	O	Payment channel merchant discount amount,The merchant gives the customer a preferential amount through the payment channel, and this part of the payment channel will not be settled to the merchant. Example: 3.00 When "trans_status=2", the Response includes this parameter
discount_bpc	string	-	O	Payment channel discount amount,Discount the amount of the payment channel to the customer, and this part of the funds will be settled into the merchant account. Example: 5.00 When "trans_status=2", the Response includes this parameter
trans_end_time	string	-	C	Transaction completed time. Timezone: Local time zone, the time zone set by the payment terminal, Format: YYYY-MM-DD HH:mm:ss Example: 2021-06-03 12:48:51 When "trans_status=2", the Response includes this parameter

6.3 Void

Void transaction usually means that within a short period of time after the transaction has been completed, the merchant needs to cancel the transaction for some reason (e.g., merchant error, customer change of mind, etc.).

• The void must usually be done on the same day of the transaction and before the batch settlement.
• Upon successful void, the original transaction amount will be refunded to the cardholder's account as if the transaction never occurred.
• A void usually requires the original transaction voucher or related information for the operation.

tip

Response program logic: Please judge the value of "response_code", then judge the value of "trans_status", when "response_code = 000", then respond to the parameter in the range of "C" and "O".

Key	Type	Request	Response	Description
app_id	string	M	M	The payment app id registered in Codepay Gateway, Please refer to the Payment gateway integration guide
merchant_order_no	string	M	M	The order number of the merchant's point of sale application or business system must be unique in its system. Example: 121775014073233368018
orig_merchant_order_no	string	M	M	Original merchant order number. Example: 221775014073233368018
price_currency	string	-	O	Price Currency, compliant with ISO-4217 standard, described with a three-character code Example：USD
order_amount	string	-	C	Order amount. For example, one USD stands for one dollar, not one cent. Example: 34.50 When "response_code=000", the Response includes this parameter
tip_amount	string	-	O	Tip amount. This field represents the transaction tip amount. For example, 1 USD stands for one dollar, not one cent. Example: 3.50 When "response_code=000", the Response includes this parameter
cashback_amount	string	-	O	Cashback amount. Expressed in the quoted currency, for example, One USD stands for one dollar, not one cent Example: 20.00 When "response_code=000", the Response includes this parameter
pay_scenario	string	-	O	Payment scene, please refer to Payment scenario Example: SWIPE_CARD When "trans_status=2", the Response includes this parameter
pay_method_id	string	-	O	Specify a payment method. This field is mandatory only when "pay_scenario" is set to "SCANQR_PAY" or "BSCANQR_PAY". Refer to Payment method Example: Visa When "trans_status=2", the Response includes this parameter
attach	string	-	O	Additional data. Allows merchants to submit additional data, which will be returned as is.
description	string	-	O	Description of ordered goods or services. A brief description of the goods or services purchased by the customer. Example: iPhone Pro
confirm_on_terminal	boolean	O	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
required_terminal_authentication	boolean	O	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	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
response_code	string	-	M	Response code, Refer to Response code Example: 000
response_msg	string	-	C	Example: success
trans_no	string	-	C	Transaction number.This field represents Gateway transaction number, which uniquely identifies a transaction. Example: 5021000010210602000003 When "response_code=000", the Response includes this parameter
trans_status	string	-	C	Transaction status, please refer to Transaction status Example: 2 When "response_code=000", the Response includes this parameter
pay_channel_trans_no	string	-	C	Payment channel transaction numbers, such as RRN for Visa, Mastercard, etc. Example: 000000123 When "trans_status=2", the Response includes this parameter
discount_bmopc	string	-	O	Payment channel merchant discount amount,The merchant gives the customer a preferential amount through the payment channel, and this part of the payment channel will not be settled to the merchant. Example: 3.00 When "trans_status=2", the Response includes this parameter
discount_bpc	string	-	O	Payment channel discount amount,Discount the amount of the payment channel to the customer, and this part of the funds will be settled into the merchant account. Example: 5.00 When "trans_status=2", the Response includes this parameter
trans_end_time	string	-	C	Transaction completed time. Timezone: Local time zone, the time zone set by the payment terminal, Format: YYYY-MM-DD HH:mm:ss Example: 2021-06-03 12:48:51 When "trans_status=2", the Response includes this parameter

6.4 Refund

A refund transaction is a process in which a cardholder needs to return an item or cancel a service for some reason (e.g., a problem with the item, dissatisfaction with the service, etc.) after the transaction has cleared and requests that the amount paid be returned to the card account.

• The refund may occur on the same day of the transaction, or a few days or more later.
• Refunds usually require the cardholder to provide proof of purchase and a reason for the refund, and the merchant will refund the appropriate amount to the cardholder's card account after reviewing the refund.
• The original order number can be left out for bank card transactions, and the original merchant order number is required for QR mobile payment transactions.

tip

Response program logic: Please judge the value of "response_code", then judge the value of "trans_status", when "response_code = 000", then respond to the parameter in the range of "C" and "O".

Key	Type	Request	Response	Description
app_id	string	M	M	The payment app id registered in Codepay Gateway, Please refer to the Payment gateway integration guide
merchant_order_no	string	M	M	The order number of the merchant's point of sale application or business system must be unique in its system. Example: 121775014073233368018
orig_merchant_order_no	string	M	M	Original merchant order number. Example: 221775014073233368018
price_currency	string	O	O	Price Currency, compliant with ISO-4217 standard, described with a three-character code Example：USD
order_amount	string	M	M	Order amount. For example, one USD stands for one dollar, not one cent. Example: 34.50
tip_amount	string	O	O	Tip amount. This field represents the transaction tip amount. For example, 1 USD stands for one dollar, not one cent. Example: 3.50
on_screen_tip	boolean	O	-	Whether or not to enter tips on the CodePay Register page, default is false Example: true
cashback_amount	string	O	O	Cashback amount. Expressed in the quoted currency, for example, One USD stands for one dollar, not one cent Example: 20.00
pay_scenario	string	O	C	Payment scene, please refer to Payment scenario Example: SWIPE_CARD When "trans_status=2", the Response includes this parameter
pay_method_id	string	O	C	Specify a payment method. This field is mandatory only when "pay_scenario" is set to "SCANQR_PAY" or "BSCANQR_PAY". Refer to Payment method Example: Visa When "trans_status=2", the Response includes this parameter
card_type	string	O	-	Type of bank card，please refer to Card type
attach	string	O	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. Example: iPhone Pro
notify_url	string	O	-	Callback address for payment notification. Receive payment notifications from the Gateway to call back the server address, and only when the transaction goes through the payment gateway will there be a callback. Example: http://www.abc.com/callback?id=12345
expires	string	O	-	Order expires time, after the expires time is not allowed to be paid, unit: seconds Example: 180
confirm_on_terminal	boolean	O	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
required_terminal_authentication	boolean	O	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	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
response_code	string	-	M	Response code, Refer to Response code Example: 000
response_msg	string	-	C	Example: success
trans_no	string	-	C	Transaction number.This field represents Gateway transaction number, which uniquely identifies a transaction. Example: 5021000010210602000003 When "response_code=000", the Response includes this parameter
trans_status	string	-	C	Transaction status, please refer to Transaction status Example: 2 When "response_code=000", the Response includes this parameter
pay_channel_trans_no	string	-	C	Payment channel transaction numbers, such as RRN for Visa, Mastercard, etc. Example: 000000123 When "trans_status=2", the Response includes this parameter
discount_bmopc	string	-	O	Payment channel merchant discount amount,The merchant gives the customer a preferential amount through the payment channel, and this part of the payment channel will not be settled to the merchant. Example: 3.00 When "trans_status=2", the Response includes this parameter
discount_bpc	string	-	O	Payment channel discount amount,Discount the amount of the payment channel to the customer, and this part of the funds will be settled into the merchant account. Example: 5.00 When "trans_status=2", the Response includes this parameter
trans_end_time	string	-	C	Transaction completed time. Timezone: Local time zone, the time zone set by the payment terminal, Format: YYYY-MM-DD HH:mm:ss Example: 2021-06-03 12:48:51 When "trans_status=2", the Response includes this parameter

6.5 Authorization

Authorization transactions are a type of card transaction authorization by which a merchant can ensure that the transaction amount is frozen or held in the customer's account until the transaction is completed.

During the authorization stage, the merchant requests authorization from the customer's bank for a specific amount, which is temporarily frozen if the customer has a sufficient available balance or credit limit in their account. This means that the amount is not actually deducted yet, but the customer cannot use the funds for other purchases during this time.

Authorization is commonly used in those situations where the final transaction amount is uncertain, common in lodging service, rental service, unattended self-service, etc.

tip

Response program logic: Please judge the value of "response_code", then judge the value of "trans_status", when "response_code = 000", then respond to the parameter in the range of "C" and "O".

Key	Type	Request	Response	Description
app_id	string	M	M	The payment app id registered in Codepay Gateway, Please refer to the Payment gateway integration guide
merchant_order_no	string	M	M	The order number of the merchant's point of sale application or business system must be unique in its system. Example: 121775014073233368018
price_currency	string	O	O	Price Currency, compliant with ISO-4217 standard, described with a three-character code Example：USD
order_amount	string	M	M	Order amount. For example, one USD stands for one dollar, not one cent. Example: 34.50
tip_amount	string	O	O	Tip amount. This field represents the transaction tip amount. For example, 1 USD stands for one dollar, not one cent. Example: 3.50
on_screen_tip	boolean	O	-	Whether or not to enter tips on the CodePay Register page, default is false Example: true
pay_scenario	string	O	C	Payment scene, please refer to Payment scenario Example: SWIPE_CARD When "trans_status=2", the Response includes this parameter
pay_method_id	string	O	C	Specify a payment method. This field is mandatory only when "pay_scenario" is set to "SCANQR_PAY" or "BSCANQR_PAY". Refer to Payment method Example: Visa When "trans_status=2", the Response includes this parameter
card_type	string	O	-	Type of bank card，please refer to Card type
attach	string	O	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. Example: iPhone Pro
notify_url	string	O	-	Callback address for payment notification. Receive payment notifications from the Gateway to call back the server address, and only when the transaction goes through the payment gateway will there be a callback. Example: http://www.abc.com/callback?id=12345
expires	string	O	-	Order expires time, after the expires time is not allowed to be paid, unit: seconds Example: 180
confirm_on_terminal	boolean	O	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
on_screen_signature	boolean	O	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
response_code	string	-	M	Response code, Refer to Response code Example: 000
response_msg	string	-	C	Example: success
trans_no	string	-	C	Transaction number.This field represents Gateway transaction number, which uniquely identifies a transaction. Example: 5021000010210602000003 When "response_code=000", the Response includes this parameter
trans_status	string	-	C	Transaction status, please refer to Transaction status Example: 2 When "response_code=000", the Response includes this parameter
pay_channel_trans_no	string	-	C	Payment channel transaction numbers, such as RRN for Visa, Mastercard, etc. Example: 000000123 When "trans_status=2", the Response includes this parameter
discount_bmopc	string	-	O	Payment channel merchant discount amount,The merchant gives the customer a preferential amount through the payment channel, and this part of the payment channel will not be settled to the merchant. Example: 3.00 When "trans_status=2", the Response includes this parameter
discount_bpc	string	-	O	Payment channel discount amount,Discount the amount of the payment channel to the customer, and this part of the funds will be settled into the merchant account. Example: 5.00 When "trans_status=2", the Response includes this parameter
trans_end_time	string	-	C	Transaction completed time. Timezone: Local time zone, the time zone set by the payment terminal, Format: YYYY-MM-DD HH:mm:ss Example: 2021-06-03 12:48:51 When "trans_status=2", the Response includes this parameter

6.6 Completion

Completion transaction is the process of requesting the merchant to formally debit the customer's account for the previously authorized amount after the authorization, when the actual consumption of the service or goods is complete and the final amount is determined. This step is a follow-up to the authorization and ensures that the merchant receives the payment.

For example, when a customer checks out of a hotel at the end of their stay, the hotel will compare the previously authorized amount to the actual amount spent; if the actual amount spent is higher, the hotel will request an additional authorization to cover the difference; if the actual amount spent is lower, only the actual amount spent will be deducted, and the remainder of the authorized amount will be released back to the customer's account.

tip

Response program logic: Please judge the value of "response_code", then judge the value of "trans_status", when "response_code = 000", then respond to the parameter in the range of "C" and "O".

Key	Type	Request	Response	Description
app_id	string	M	M	The payment app id registered in Codepay Gateway, Please refer to the Payment gateway integration guide
merchant_order_no	string	M	M	The order number of the merchant's point of sale application or business system must be unique in its system. Example: 121775014073233368018
orig_merchant_order_no	string	M	M	Original merchant order number. Example: 221775014073233368018
price_currency	string	O	O	Price Currency, compliant with ISO-4217 standard, described with a three-character code Example：USD
order_amount	string	M	M	Order amount. For example, one USD stands for one dollar, not one cent. Example: 34.50
tip_amount	string	O	O	Tip amount. This field represents the transaction tip amount. For example, 1 USD stands for one dollar, not one cent. Example: 3.50
pay_scenario	string	O	C	Payment scene, please refer to Payment scenario Example: SWIPE_CARD When "trans_status=2", the Response includes this parameter
pay_method_id	string	O	C	Specify a payment method. This field is mandatory only when "pay_scenario" is set to "SCANQR_PAY" or "BSCANQR_PAY". Refer to Payment method Example: Visa When "trans_status=2", the Response includes this parameter
attach	string	O	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. Example: iPhone Pro
notify_url	string	O	-	Callback address for payment notification. Receive payment notifications from the Gateway to call back the server address, and only when the transaction goes through the payment gateway will there be a callback. Example: http://www.abc.com/callback?id=12345
expires	string	O	-	Order expires time, after the expires time is not allowed to be paid, unit: seconds Example: 180
confirm_on_terminal	boolean	O	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
on_screen_signature	boolean	O	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
response_code	string	-	M	Response code, Refer to Response code Example: 000
response_msg	string	-	C	Example: success
trans_no	string	-	C	Transaction number.This field represents Gateway transaction number, which uniquely identifies a transaction. Example: 5021000010210602000003 When "response_code=000", the Response includes this parameter
trans_status	string	-	C	Transaction status, please refer to Transaction status Example: 2 When "response_code=000", the Response includes this parameter
pay_channel_trans_no	string	-	C	Payment channel transaction numbers, such as RRN for Visa, Mastercard, etc. Example: 000000123 When "trans_status=2", the Response includes this parameter
discount_bmopc	string	-	O	Payment channel merchant discount amount,The merchant gives the customer a preferential amount through the payment channel, and this part of the payment channel will not be settled to the merchant. Example: 3.00 When "trans_status=2", the Response includes this parameter
discount_bpc	string	-	O	Payment channel discount amount,Discount the amount of the payment channel to the customer, and this part of the funds will be settled into the merchant account. Example: 5.00 When "trans_status=2", the Response includes this parameter
trans_end_time	string	-	C	Transaction completed time. Timezone: Local time zone, the time zone set by the payment terminal, Format: YYYY-MM-DD HH:mm:ss Example: 2021-06-03 12:48:51 When "trans_status=2", the Response includes this parameter

6.7 Query

This function is needed to query the final status of an order when the payment status of the order is unclear or timeout.

tip

Response program logic: Please judge the value of "response_code", then judge the value of "trans_status", when "response_code = 000", then respond to the parameter in the range of "C" and "O".

Key	Type	Request	Response	Description
app_id	string	M	M	The payment app id registered in Codepay Gateway, Please refer to the Payment gateway integration guide
merchant_order_no	string	M	M	The order number of the merchant's point of sale application or business system must be unique in its system. Example: 121775014073233368018
price_currency	string	-	O	Price Currency, compliant with ISO-4217 standard, described with a three-character code Example：USD
order_amount	string	-	O	Order amount. For example, one USD stands for one dollar, not one cent. Example: 34.50
tip_amount	string	-	O	Tip amount. This field represents the transaction tip amount. For example, 1 USD stands for one dollar, not one cent. Example: 3.50
cashback_amount	string	-	O	Cashback amount. Expressed in the quoted currency, for example, One USD stands for one dollar, not one cent Example: 20.00
pay_scenario	string	O	C	Payment scene, please refer to Payment scenario Example: SWIPE_CARD When "trans_status=2", the Response includes this parameter
pay_method_id	string	O	C	Specify a payment method. This field is mandatory only when "pay_scenario" is set to "SCANQR_PAY" or "BSCANQR_PAY". Refer to Payment method Example: Visa When "trans_status=2", the Response includes this parameter
attach	string	O	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. Example: iPhone Pro
response_code	string	-	M	Response code, Refer to Response code Example: 000
response_msg	string	-	C	Example: success
trans_no	string	-	C	Transaction number.This field represents Gateway transaction number, which uniquely identifies a transaction. Example: 5021000010210602000003 When "response_code=000", the Response includes this parameter
trans_status	string	-	C	Transaction status, please refer to Transaction status Example: 2 When "response_code=000", the Response includes this parameter
trans_type	string	-	C	Transaction type. This field represents currently supporting transaction type. For transaction, please refer to Transaction type Example: 1 When "response_code=000", the Response includes this parameter
pay_channel_trans_no	string	-	C	Payment channel transaction numbers, such as RRN for Visa, Mastercard, etc. Example: 000000123 When "trans_status=2", the Response includes this parameter
discount_bmopc	string	-	O	Payment channel merchant discount amount,The merchant gives the customer a preferential amount through the payment channel, and this part of the payment channel will not be settled to the merchant. Example: 3.00 When "trans_status=2", the Response includes this parameter
discount_bpc	string	-	O	Payment channel discount amount,Discount the amount of the payment channel to the customer, and this part of the funds will be settled into the merchant account. Example: 5.00 When "trans_status=2", the Response includes this parameter
trans_end_time	string	-	C	Transaction completed time. Timezone: Local time zone, the time zone set by the payment terminal, Format: YYYY-MM-DD HH:mm:ss Example: 2021-06-03 12:48:51 When "trans_status=2", the Response includes this parameter

6.8 Close

Closing an order is the active termination of an order being processed on the payment terminal. The following are some of the situations where an order may need to be closed:

• Out of stock: If the merchant is unable to provide the items in the order, it may be necessary to close the order or make adjustments to the order.
• Customer Cancellation: The customer may decide to cancel the order for some reason.
• Order Error: If the order information is incorrect, such as incorrect item quantity, incorrect price, it may be necessary to close the incorrect order and create a new correct order.

Key	Type	Request	Response	Description
app_id	string	M	M	The payment app id registered in Codepay Gateway, Please refer to the Payment gateway integration guide
merchant_order_no	string	M	M	The order number of the merchant's point of sale application or business system must be unique in its system. Example: 121775014073233368018
response_code	string	-	M	Response code, Refer to Response code Example: 000
response_msg	string	-	C	Example: success