在本地网络下与Register SDK快速集成

1. 概述

在跨终端应用集成解决方案中，有两种本地网络连接模式可供选择：WLAN和USB。要使用API方法进行集成，开发人员需要在WebSocket通信或串行端口通信方面有一定的经验。CodePay提供RegisterSDK，对通信协议层进行二次封装，帮助开发者快速完成两种模式下的支付集成。

2. 功能亮点

与API接口开发相比，RegisterSDK集成更容易，在不理解串行或套接字通信协议的情况下提供函数方法调用。在ECRHub服务模块中注册SDK构建可以提供更好的商业体验，主要有以下几点：

• 自动网络发现
  • 在WLAN模式下，可以自动发现同一本地网络上的POS设备和终端，而无需手动配置IP地址和端口，并且不受更改IP地址的影响。
  • 在USB模式下，支持检查插入和拔出的USB电缆，并自动检测串行端口。一旦找到可用的串行端口，它就会自动连接。
• 安全配对
  • 配对机制仅适用于WLAN模式。它可以确保本地网络中的通信安全。当商店中有多个POS设备或多个终端时，它还可以更好地隔离连接。
  • 配对操作支持从终端发起（需要管理员权限），POS端自动确认，无需任何操作；它还支持从POS端发起，终端手动确认，但开发者需要开发配对管理功能。
• 连接管理
  • 在WLAN模式下，提供实时网络连接状态检查；在网络恢复后自动重新发送事务。
  • 在USB增强模式下，提供心跳检测机制，实时监测网络连接状态；在网络恢复后自动重新发送事务。

3. 设备配对

备注

注意：只有WLAN连接模式需要首先配对，USB电缆模式不需要配对。

CodePay Register提供设备配对功能，通过应用内置的ECRHub服务和SDK，实现终端和POS设备的网络信息注册，发现并记录彼此的网络信息，完成快速连接和安全通信。

• 该配对机制简化了手动配置网络地址的过程，并且不受终端IP地址变化的影响。
• 它可以确保局域网中的通信安全，只有管理员权限才能设置终端连接到合法的POS设备。
• 如果商店中有多个POS设备和终端，则更容易控制和隔离它们。

POS设备和终端可以发起配对操作。考虑到简化了开发者的集成工作量，SDK只提供从终端应用程序发起并由POS设备自动确认的配对请求。以下是配对过程：

• POS应用程序启动后，Register SDK会自动在局域网中注册设备网络信息，在同一网络中的终端上运行的Register应用程序可以发现这些信息。
• 商店管理员在终端上搜索可配对的设备，选择POS设备并发起配对请求。
• POS终端上的Register SDK收到请求后，会自动确认配对，并记录终端的网络地址信息。
• 配对的POS设备根据终端网络地址发送连接请求和交易命令。

设备配对过程工作流：

4. 交易处理工作流

5. SDKs

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

6. 交易消息

本文件根据以下约定对每个字段的不同方面进行了定义。

• M：必须参数
• C：满足某些条件时所需的参数
• O：可选参数
• -：不存在

6.1 消费

销售交易是指持卡人在向商家购买商品或服务时进行的支付操作。交易金额从持卡人的账户中扣除并转移到商户的账户。

提示

响应程序逻辑：请判断“Response_code”的值，然后判断“trans_status”的值；当“Response_code=000”时，再响应“C”和“O”范围内的参数。

参数	类型	请求	响应	说明
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 返现

“现金返还销售”通常用于银行卡交易，指的是客户在用借记卡支付购买时，除了商品或服务成本外，还可以从银行账户申请额外的现金。这项服务通常在零售店或超市的收银台提供，顾客可以在收银时选择这一选项，从而避免了去银行或ATM取现的麻烦。

例如，如果你在杂货店购物花费50美元，想要20美元现金，你可以申请70美元的交易，其中50美元支付给超市，剩余的20美元作为现金退还给你。这笔交易可能会在您的银行账户记录中显示为“带现金返还的销售”，总额为70美元。

提示

响应程序逻辑：请判断“Response_code”的值，然后判断“trans_status”的值；当“Response_code=000”时，再响应“C”和“O”范围内的参数。

参数	类型	请求	响应	说明
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 撤销

无效交易通常是指在交易完成后的短时间内，商家因某种原因（如商家错误、客户改变主意等）需要取消交易。

• 作废通常必须在交易的同一天和批量结算之前完成。
• 一旦成功作废，原始交易金额将退还给持卡人的账户，就好像交易从未发生过一样。
• 作废通常需要原始交易凭证或相关信息才能进行操作。

提示

响应程序逻辑：请判断“Response_code”的值，然后判断“trans_status”的值；当“Response_code=000”时，再响应“C”和“O”范围内的参数。

参数	类型	请求	响应	说明
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 退款

退款交易是指持卡人在交易结算后，出于某种原因（如物品问题、对服务的不满等）需要退还物品或取消服务，并要求将支付的金额退还给卡账户的过程。

• 退款可能发生在交易的同一天，或者几天或更长时间后。
• 退款通常要求持卡人提供购买证明和退款理由，商家在审查退款后会将适当的金额退还给持卡人的卡账户。
• 银行卡交易可以省略原始订单号，二维码移动支付交易需要原始商户订单号。

提示

响应程序逻辑：请判断“Response_code”的值，然后判断“trans_status”的值；当“Response_code=000”时，再响应“C”和“O”范围内的参数。

参数	类型	请求	响应	说明
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 预授权

授权交易是一种卡交易授权，通过这种授权，商家可以确保交易金额被冻结或保存在客户的账户中，直到交易完成。

在授权阶段，商家向客户的银行请求特定金额的授权，如果客户的账户中有足够的可用余额或信用额度，该金额将被暂时冻结。这意味着该金额尚未实际扣除，但客户在此期间不能将资金用于其他购买。

授权通常用于最终交易金额不确定的情况，常见于住宿服务、租赁服务、无人值守自助服务等。

提示

响应程序逻辑：请判断“Response_code”的值，然后判断“trans_status”的值；当“Response_code=000”时，再响应“C”和“O”范围内的参数。

参数	类型	请求	响应	说明
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 预授权完成

完成交易是指在授权后，当服务或商品的实际消费完成并确定最终金额时，要求商家正式从客户账户中扣除先前授权金额的过程。此步骤是授权的后续步骤，确保商家收到付款。

例如，当客户在入住结束时退房时，酒店会将之前授权的金额与实际花费的金额进行比较；如果实际花费的金额更高，酒店将要求额外的授权来弥补差额；如果实际支出金额较低，则仅扣除实际支出金额，授权金额的剩余部分将退还给客户的账户。

提示

响应程序逻辑：请判断“Response_code”的值，然后判断“trans_status”的值；当“Response_code=000”时，再响应“C”和“O”范围内的参数。

参数	类型	请求	响应	说明
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 查询

当订单的付款状态不清楚或超时时，需要此功能来查询订单的最终状态。

提示

响应程序逻辑：请判断“Response_code”的值，然后判断“trans_status”的值；当“Response_code=000”时，再响应“C”和“O”范围内的参数。

参数	类型	请求	响应	说明
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 关闭

关闭订单是对支付终端上正在处理的订单的主动终止。以下是可能需要关闭订单的一些情况：

• 缺货：如果商家无法提供订单中的商品，可能需要关闭订单或对订单进行调整。
• 客户取消：客户可能会因为某种原因决定取消订单。
• 订单错误：如果订单信息不正确，例如项目数量不正确、价格不正确，则可能需要关闭不正确的订单并创建新的正确订单。

参数	类型	请求	响应	说明
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