同一终端内应用集成（V2）

提示

公共说明

本文根据以下约定每个参数字段的必要性。

M：必要参数
C：在满足某些条件时，是必要参数
O：可选参数
-：不存在常见参数如下：

参数	类型	请求	响应	说明
topic	string	M	M	Message topic identifier. Please refer to the topic Example: ecrhub.pay.order
request_id	string	C	C	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. fixed value:1.0
app_id	string	M	M	The payment app id registered in Codepay Gateway, Please refer to the Payment gateway integration guide
biz_data	JSONObject	O	O	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

每种交易类型都有一个消息主题：

Key	Name
ecrhub.pay.order	提交交易请求
ecrhub.pay.query	查询交易信息
ecrhub.pay.reprint	重打印
ecrhub.pay.batch.close	批结算
ecrhub.pay.tip.adjustment	小费调整

API列表

1. 提交交易请求

消息主题

ecrhub.pay.order

参数列表

参数	Type	请求s	响应	说明
trans_type	String	M	M	Transaction type. Please refer to Transaction type.
merchant_order_no	String	M	M	Merchant order number.This field is the refund request order number (distinct from the original transaction order number). No more than 32 alphanumeric characters.
orig_merchant_order_no	String	C	C	Original merchant order number. Required if trans_type is Void, Refund, or Completion (2, 3, 6).
price_currency	String	O	O	Price Currency, compliant with ISO-4217 standard, described with a three-character code.
order_amount	String	M	M	Order amount. Order amount in base currency units (e.g., 1.00 USD = one dollar).
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.
on_screen_tip	boolean	O	O	Whether or not to enter tips on the CodePay Register page, default is false, when "trans_type=1, 3, 4", this parameter can be set.
cashback_amount	String	O	O	Cashback amount. Expressed in the quoted currency, for example, One USD stands for one dollar, not one cent.
pay_method_id	String	O	O	Payment method id. Please Refer to Payment method If the trans_type is 3, this parameter will not required.
pay_scenario	String	O	O	Payment scene, please refer to PayScenario .
card_network_type	String	O	O	Bank card network, when this parameter is not required, the bank card transaction selects the network based on the type of card being read,please refer to Card Network 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	-	Receipt printing mode.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	Transaction status, please refer to Transaction status.
trans_end_time	string	-	M	Transaction completed time. If trans_status is 2, 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, It has been masked according to PCI specification. example: 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 channel,channel example: TSYS,ELAVON.
pay_channel_terminal_id	string	-	C	Terminal id of the payment channel,channel example: TSYS,ELAVON.

示例代码

Intent intent = new Intent();
intent.setAction("com.codepay.transaction.call");
intent.putExtra("version", "2.0");
intent.putExtra("topic", "ecrhub.pay.order");
intent.putExtra("app_id", "{YOUR_APP_ID}");
JSONObject jsonObject = new JSONObject();
try {
   jsonObject.put("trans_type", "1"); // Sale transaction
   jsonObject.put("merchant_order_no","202202222222");
   jsonObject.put("pay_scenario","SWIPE_CARD"); //Card payment
   jsonObject.put("card_type", "1") //Debit
   jsonObject.put("order_amount","2.15");
   intent.putExtra("biz_data", jsonObject.toString());
} catch (JSONException e) {
   e.printStackTrace();
}
startActivityForResult(intent, 1);

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
   String responseCode = data.getStringExtra("response_code");
   String responseMsg = data.getStringExtra("response_msg");
   String bizData = data.getStringExtra("biz_data");
   if (responseCode.equals("000")){
       try {
           JSONObject jsonObject = new JSONObject(bizData);
           String amount = jsonObject.getString("order_amount");
       }catch(JSONException e){
           e.printStackTrace();
       }
   }
}

2. 查询交易

消息主题

ecrhub.pay.query

参数列表

参数	Type	请求s	响应	说明
merchant_order_no	String	M	M	Merchant order number of the original transaction
trans_type	String	-	M	Transaction type. Please refer to Transaction type.
price_currency	String	-	M	Price Currency, compliant with ISO-4217 standard, described with a three-character code.
order_amount	String	-	M	Order amount. This field represents the transaction ordered amount, For example, one USD stands for one dollar, not one cent.
tip_amount	String	-	O	Tip amount. This field represents the transaction tip amount. For example, 1 USD stands for one dollar, not one cent.
cashback_amount	String	-	O	Cashback amount. Expressed in the quoted currency, for example, One USD stands for one dollar, not one cent.
attach	String	-	O	Additional data.Allows merchants to submit additional data, which will be returned as is.
pay_scenario	String	-	O	Payment scene, If trans_status is 2, the returned data will include the following parameters, please refer to Please Refer to PayScenario .
pay_method_id	String	-	O	Payment method id. If trans_status is 2, the returned data will include the following parameters. Please Refer to Payment method If the trans_type is 3, this parameter will not required.
card_network_type	String	-	O	Bank card network, when this parameter is not required, the bank card transaction selects the network based on the type of card being read,please refer to Card Network Type.
trans_no	String	-	M	Transaction number of CodePay. which uniquely identifies a transaction.
trans_status	String	-	M	Transaction status, please refer to Transaction status.
trans_end_time	string	-	M	Transaction completed time. If trans_status is 2, 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 - Swipe magnetic stripe card;2 - Contact chip card; 3 - Contactless chip card;4 - Manual entry input.
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 channel,channel example: TSYS,ELAVON
pay_channel_terminal_id	string	-	C	Terminal id of the payment channel,channel example: TSYS,ELAVON

示例代码

Intent intent = new Intent();
intent.setAction("com.codepay.transaction.call");
intent.putExtra("version", "2.0");
intent.putExtra("topic", "ecrhub.pay.query");
intent.putExtra("app_id", "{YOUR_APP_ID}");
JSONObject jsonObject = new JSONObject();
try {
   jsonObject.put("merchant_order_no","202202222222");
   intent.putExtra("biz_data", jsonObject.toString());
} catch (JSONException e) {
   e.printStackTrace();
}
startActivityForResult(intent, 1);

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
   String responseCode = data.getStringExtra("response_code");
   String responseMsg = data.getStringExtra("response_msg");
   String bizData = data.getStringExtra("biz_data");
   if (responseCode.equals("000")){
       try {
           JSONObject jsonObject = new JSONObject(bizData);
           String amount = jsonObject.getString("order_amount");
       }catch(JSONException e){
           e.printStackTrace();
       }
   }
}

3. 重打印

消息主题

ecrhub.pay.reprint

参数列表

参数	Type	请求s	响应	说明
merchant_order_no	String	M	-	Merchant order number of the original transaction.

示例代码

Intent intent = new Intent();
intent.setAction("com.codepay.transaction.call");
intent.putExtra("version", "2.0");
intent.putExtra("topic", "ecrhub.pay.reprint");
intent.putExtra("app_id", "{YOUR_APP_ID}");
JSONObject jsonObject = new JSONObject();
try {
   jsonObject.put("trans_type", "22");
   jsonObject.put("merchant_order_no","202202222222");
   intent.putExtra("biz_data", jsonObject.toString());
} catch (JSONException e) {
   e.printStackTrace();
}
startActivityForResult(intent, 1);

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
   String responseCode = data.getStringExtra("response_code");
   String responseMsg = data.getStringExtra("response_msg");
}

4. 批结算

消息主题

ecrhub.pay.batch.close

示例代码

Intent intent = new Intent();
intent.setAction("com.codepay.transaction.call");
intent.putExtra("version", "2.0");
intent.putExtra("topic", "ecrhub.pay.batch.close");
intent.putExtra("app_id", "{YOUR_APP_ID}");
startActivityForResult(intent, 1);

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
   String responseCode = data.getStringExtra("response_code");
   String responseMsg = data.getStringExtra("response_msg");
}

5. 小费调整

消息主题

ecrhub.pay.tip.adjustment

参数列表

参数	Type	请求s	响应	说明
merchant_order_no	String	M	-	Merchant order number requiring tip adjustment transaction
tip_adjustment_amount	String	M	-	Tip adjustment amount. For example, 1 USD stands for one dollar, not one cent.

示例代码

Intent intent = new Intent();
intent.setAction("com.codepay.transaction.call");
intent.putExtra("version", "2.0");
intent.putExtra("topic", "ecrhub.pay.tip.adjustment");
intent.putExtra("app_id", "{YOUR_APP_ID}");
JSONObject jsonObject = new JSONObject();
try {
   jsonObject.put("merchant_order_no", "202202222222");
   jsonObject.put("tip_adjustment_amount", "10.00");
   intent.putExtra("biz_data", jsonObject.toString());
} catch (JSONException e) {
   e.printStackTrace();
}
startActivityForResult(intent, 1);

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
   String responseCode = data.getStringExtra("response_code");
   String responseMsg = data.getStringExtra("response_msg");
}

集成Demo

example projects

同一终端内应用集成（V2）

公共说明​

API列表​

1. 提交交易请求​

2. 查询交易​

3. 重打印​

4. 批结算​

5. 小费调整​

集成Demo​

公共说明

API列表

1. 提交交易请求

2. 查询交易

3. 重打印

4. 批结算

5. 小费调整

集成Demo