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.
paymentMethod	enum	N	Payment methods: -credit_card, -fps, -octopus. -consumer_presented_qr_code, -all, If the payment method is transmitted, it will directly redirect to the target page
restrictedPaymentMethods	Array	N	Payment Methods
currency	String	Y	Example: HKD / USD / RMB
amount	String	Y	Sale amount
remark	String	N	Remark
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	Y	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&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
referenceID	String	Y	The referenceID from the request body
currency	String	N	Example: HKD / USD / RMB
amount	String	N	Sale amount
paymentMethod	String	N	Payment method
paymentEntryType	String	N	Payment entries, Example: contactless
transactionUuid	String	N	Transaction UUID
allowVoid	Boolean	N	Allow Void: true / false true: Allows void false: Does not allow void
allowRefund	Boolean	N	Allow Refund: true / false true: Allows refund false: Does not allow refund
consumerCountryCode	String	N	Consumer country code
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.consumerIdentify	String	Y	Consumer identify, e.g. Card Number, Open ID, etc.

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.
paymentMethod	enum	N	Payment methods: -credit_card
currency	String	Y	Example: HKD / USD / RMB
amount	String	Y	Sale amount
remark	String	N	Remark
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	Y	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&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
referenceID	String	Y	The referenceID from the request body
currency	String	N	Example: HKD / USD / RMB
amount	String	N	Sale amount
paymentMethod	String	N	Payment method
paymentEntryType	String	N	Payment entries, Example: contactless
transactionUuid	String	N	Transaction UUID
allowVoid	Boolean	N	Allow Void: true / false true: Allows void false: Does not allow void
allowRefund	Boolean	N	Allow Refund: true / false true: Allows refund false: Does not allow refund
consumerCountryCode	String	N	Consumer country code
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.consumerIdentify	String	Y	Consumer identify, e.g. Card Number, Open ID, etc.

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	Y	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
referenceID	String	Y	The orgReferenceID from the request body

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	N	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	Y	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
referenceID	String	Y	The referenceID from the request body

1.5 Capture

Action: Capture

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	N	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	Y	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=Capture&...&callback=" + encodedCallback
);

wondermpos://public/payment?action=Capture&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
referenceID	String	Y	The referenceID from the request body

1.6 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	Y	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.

1.7 Print

Action: Print

Request Params

Variable	Type	Required	Description
action	enum	Y	Actions: Sale, Void, Refund, ...
targetReferenceID	String	Y	The reference ID that was carried during the original transaction.
callback	String	Y	Deep Link used to return the print result after processing. 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=Print&...&callback=" + encodedCallback
);

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

Response Params

Variable	Type	Required	Description
status	String	Y	Print result: Success / Failed

1.8 CustomPrint

Action: CustomPrint

This interface allows a third-party application to print custom content through Wonder mPOS.
The third party provides the print content through printUrl. Wonder mPOS retrieves and processes the content, then prints it using the device printer.

Request Params

Variable	Type	Required	Description
action	enum	Y	Action: `CustomPrint`
printUrl	String	Y	URI provided by the third-party application for retrieving the print content. This parameter must be URL-encoded.
callback	String	Y	Deep Link used to return the print result after processing. This parameter must be URL-encoded.

Example:

wondermpos://public/payment?action=CustomPrint&printUrl={encodedPrintUrl}&callback={encodedCallback}

Response Params

Variable	Type	Required	Description
status	String	Y	Print result: Success / Failed

Android Integration Note

Important: When printUrl is a local content:// URI provided through Android FileProvider, the calling application must grant Wonder mPOS read access to the URI.

The Intent must include:

Intent.FLAG_GRANT_READ_URI_PERMISSION

The URI permission should also be granted through ClipData / grantUriPermission as required by the Android implementation.

Without URI read permission, Wonder mPOS may receive the printUrl but will not be able to access the print content.

Android Example:

val deeplink = "wondermpos://public/payment" +
    "?action=CustomPrint" +
    "&printUrl=$encodedPrintUrl" +
    "&callback=$encodedCallback"

val intent = Intent(Intent.ACTION_VIEW, Uri.parse(deeplink)).apply {
    setPackage(WONDER_MPOS_PACKAGE)
    addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
    addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
    addFlags(Intent.FLAG_GRANT_PERSISTABLE_URI_PERMISSION)

    clipData = ClipData.newUri(contentResolver, "printUrl", printUri)
    type = "image/png"
}

grantUriPermission(
    WONDER_MPOS_PACKAGE,
    printUri,
    Intent.FLAG_GRANT_READ_URI_PERMISSION
)

startActivity(intent)

Notes

CustomPrint is an independent App-to-App action and is not part of Sale / Void / Refund.
The print content is provided by the third party through printUrl.
If printUrl uses an Android content:// URI, the calling application must grant Wonder mPOS URI read permission.
Supported print content formats and size limitations should follow the final implementation confirmed by Development.
For detailed printer hardware specifications, please contact the technical support team for assistance.

1. Interface Protocol​

1.1 Sale​

Request Params​

Example:​

Response Params​

1.2 PreAuth​

Request Params​

Example:​

Response Params​

1.3 Void​

Request Params​

Example:​

Response Params​

1.4 Refund​

Request Params​

Example:​

Response Params​

1.5 Capture​

Request Params​

Example:​

Response Params​

1.6 Query Transaction Status​

Request Params​

Example:​

Response Params​

1.7 Print​

Request Params​

Example:​

Response Params​

1.8 CustomPrint​

Request Params​

Example:​

Response Params​

Android Integration Note​

Android Example:​

Notes​

1. Interface Protocol

1.1 Sale

Request Params

Example:

Response Params

1.2 PreAuth

Request Params

Example:

Response Params

1.3 Void

Request Params

Example:

Response Params

1.4 Refund

Request Params

Example:

Response Params

1.5 Capture

Request Params

Example:

Response Params

1.6 Query Transaction Status

Request Params

Example:

Response Params

1.7 Print

Request Params

Example:

Response Params

1.8 CustomPrint

Request Params

Example:

Response Params

Android Integration Note

Android Example:

Notes