Payment App to App

Inter-App Communication

Complete the order collection through the App-to-App method

1. Interface Protocol

---

1.1 Sale

• Action: Sale

Request Params

Variable	Type	Required	Description
action	enum	Y	Actions: Sale, Void, Refund, ...
referenceID	String	Y	Reference ID: Every time a transaction request is initiated, it is crucial to ensure the uniqueness of this ID. Failure to do so will render any subsequent operations on the transaction invalid.
customerOrderID	String	N	The order ID of the customer's transaction
paymentMethod	enum	N	Payment methods: -credit_card, -fps, -octopus. -consumer_presented_qr_code, If the payment method is transmitted, it will directly redirect to the target page
currency	String	Y	Example: HKD / USD / RMB
amount	String	Y	Sale amount
print	enum	N	YES/NO: To define whether the transaction is printed or not. YES means to print, and NO means not to print. default is YES
callback	String	N	When Softpos finishes processing a sale, use this Deep Link to pass the response parameters. This parameter requires the address to be encoded (URLEncoder)

Example:

String callback = "merchantpos://public/payment/result";

String encodedCallback = URLEncoder.encode(callback, "UTF-8");

Uri uri = Uri.parse(
  "wondermpos://public/payment?action=Sale&...&callback=" + encodedCallback
);

wondermpos://public/payment?action=Sale&referenceID=5debf769-49d7-4c9b-b6f4-8a9d90e1a874&customerOrderID=123&currency=HKD&amount=100.00&callback={encodedCallback}

Response Params

Variable	Type	Required	Description
status	String	Y	Response status: Success / Failed
errorCode	String	Y
errorMessage	String	Y
customerOrderID	String	N	The order ID of the customer's transaction
currency	String	N	Example: HKD / USD / RMB
amount	String	N	Sale amount
paymentMethod	String	N	Payment method
paymentEntryType	String	N	Payment entry types, Example: contactless
rrn	String	N	Receiver Reference Number
brn	String	N	Bindo Reference Number
transactionType	String	N	Transaction type: Sale / PreAuth / Void / Refund
transactionTime	Datetime	N	Transaction Time
creditCard	Object	N
creditCard.panPrefix6Digits	String	Y	First 6 digits of the credit card number
creditCard.panLast4Digits	String	Y	Last 4 digits of the credit card number
creditCard.panHash	String	Y	SHA512
creditCard.panToken	String	Y

---

1.2 PreAuth

• Action: PreAuth

Request Params

Variable	Type	Required	Description
action	enum	Y	Actions: Sale, Void, Refund, ...
referenceID	String	Y	Reference ID: Every time a transaction request is initiated, it is crucial to ensure the uniqueness of this ID. Failure to do so will render any subsequent operations on the transaction invalid.
customerOrderID	String	N	The order ID of the customer's transaction
paymentMethod	enum	N	Payment methods: -credit_card
currency	String	Y	Example: HKD / USD / RMB
amount	String	Y	Sale amount
print	enum	N	YES/NO: To define whether the transaction is printed or not. YES means to print, and NO means not to print. default is YES
callback	String	N	When Softpos finishes processing a sale, use this Deep Link to pass the response parameters. This parameter requires the address to be encoded (URLEncoder)

Example:

String callback = "merchantpos://public/payment/result";

String encodedCallback = URLEncoder.encode(callback, "UTF-8");

Uri uri = Uri.parse(
  "wondermpos://public/payment?action=PreAuth&...&callback=" + encodedCallback
);

wondermpos://public/payment?action=PreAuth&referenceID=5debf769-49d7-4c9b-b6f4-8a9d90e1a874&customerOrderID=123&currency=HKD&amount=100.00&callback={encodedCallback}

Response Params

Variable	Type	Required	Description
status	String	Y	Response status: Success / Failed
errorCode	String	Y
errorMessage	String	Y
customerOrderID	String	N	The order ID of the customer's transaction
currency	String	N	Example: HKD / USD / RMB
amount	String	N	Sale amount
paymentMethod	String	N	Payment method
paymentEntryType	String	N	Payment entry types, Example: contactless
rrn	String	N	Receiver Reference Number
brn	String	N	Bindo Reference Number
transactionType	String	N	Transaction type: Sale / PreAuth / Void / Refund
transactionTime	Datetime	N	Transaction Time
creditCard	Object	N
creditCard.panPrefix6Digits	String	Y	First 6 digits of the credit card number
creditCard.panLast4Digits	String	Y	Last 4 digits of the credit card number
creditCard.panHash	String	Y	SHA512
creditCard.panToken	String	Y

---

1.3 Void

• Action: Void

Request Params

Variable	Type	Required	Description
action	enum	Y	Actions: Sale, Void, Refund, ...
pwd	String	Y	Void password. It is currently the Store ID
orgReferenceID	String	Y	The reference ID that was carried during the transaction made at that time.
print	enum	N	YES/NO: To define whether the transaction is printed or not. YES means to print, and NO means not to print. default is YES
callback	String	N	When Softpos finishes processing a void, use this Deep Link to pass the response parameters. This parameter requires the address to be encoded (URLEncoder)

Example:

String callback = "merchantpos://public/payment/result";

String encodedCallback = URLEncoder.encode(callback, "UTF-8");

Uri uri = Uri.parse(
  "wondermpos://public/payment?action=Void&...&callback=" + encodedCallback
);

wondermpos://public/payment?action=Void&pwd=123456&orgReferenceID=5debf769-49d7-4c9b-b6f4-8a9d90e1a874&callback={encodedCallback}

Response Params

Variable	Type	Required	Description
status	String	Y	Response status: Success / Failed
errorCode	String	Y
errorMessage	String	Y

---

1.4 Refund

• Action: Refund

Request Params

Variable	Type	Required	Description
action	enum	Y	Actions: Sale, Void, Refund, ...
pwd	String	Y	Void password. It is currently the Store ID
referenceID	String	Y	Reference ID: Every time a transaction request is initiated, it is crucial to ensure the uniqueness of this ID. Failure to do so will render any subsequent operations on the transaction invalid.
orgReferenceID	String	Y	The reference ID that was carried during the transaction made at that time.
currency	String	Y	Example: HKD / USD / RMB
amount	String	Y	Refund amount
print	enum	N	YES/NO: To define whether the transaction is printed or not. YES means to print, and NO means not to print. default is YES
callback	String	N	When Softpos finishes processing a refund, use this Deep Link to pass the response parameters. This parameter requires the address to be encoded (URLEncoder)

Example:

String callback = "merchantpos://public/payment/result";

String encodedCallback = URLEncoder.encode(callback, "UTF-8");

Uri uri = Uri.parse(
  "wondermpos://public/payment?action=Refund&...&callback=" + encodedCallback
);

wondermpos://public/payment?action=Refund&pwd=123456&referenceID=5debf769-49d7-4c9b-b6f4-8a9d90e1a874&orgReferenceID=4b02c099-4dc9-4b30-bd2c-27bf3223df6b&currency=HKD&amount=100.00&callback={encodedCallback}

Response Params

Variable	Type	Required	Description
status	String	Y	Response status: Success / Failed
errorCode	String	Y
errorMessage	String	Y

---

1.5 Query Transaction Status

• Action: TransactionStatus

Request Params

Variable	Type	Required	Description
action	enum	Y	Actions: Sale, Void, Refund, ...
pwd	String	Y	Void password. It is currently the Store ID
targetReferenceID	String	Y	The reference ID that was carried during the transaction made at that time.
callback	String	N	When Softpos finishes processing a refund, use this Deep Link to pass the response parameters. This parameter requires the address to be encoded (URLEncoder)

Example:

String callback = "merchantpos://public/payment/result";

String encodedCallback = URLEncoder.encode(callback, "UTF-8");

Uri uri = Uri.parse(
  "wondermpos://public/payment?action=TransactionStatus&...&callback=" + encodedCallback
);

wondermpos://public/payment?action=TransactionStatus&pwd=123456&targetReferenceID=4b02c099-4dc9-4b30-bd2c-27bf3223df6b&callback={encodedCallback}

Response Params

This interface supports querying transactions related to Sale, Void, Refund, etc.
The response results can be referred to the relevant interfaces.

---