Context

This developer guide provides a detailed technical overview of integrating an Android POS application with the AXS payment app (PayCube Lite).

Device Requirement

Android 10+ (API level 29+/ Q/ Quince Tart).

Support Google Play Services (GMS).

For production app, it is required to be installed from Google Play Store.

The device must be able to receive security updates and has recent security patch level.

Supports of hardware backed key attestation.

Supports of NFC for Cards Payment.

Supports of light sensor.

Device must not be rooted.

Device must pass Android compatibility test.

Device bootloader must be locked.

The application must not be built in a way that allows extraction of native libraries from APKs during installation.

No hooking framework (e.g. Frida, Xposed) shall be installed on the device or bundled with the app.

Mechanism

This integration uses the Android App-to-App mechanism. The POS application initiates a transaction by sending an Intent with specific data elements to the payment app. The payment app then takes control of the screen to process the transaction (e.g., card tapping). Once complete, control is returned to the POS application with the results.

Package & Class Constants

Declare these constants once in your integration code:

AndroidManifest - Package Visibility (Android 11+)

Android 11 (API 30) restricts cross-package visibility. Add the following <queries> block to your AndroidManifest.xml so your app can detect and bind to PayCube Lite:

<queries>
    <package android:name="com.axs.paycube.lite" />
</queries>

Checksum Algorithm

Every request must include a checksum field according to requirements below:

Collect the recognised parameter keys for the given transType that are present in your request (exclude the checksum key itself).

Sort those keys lexically (A→Z).

Concatenate the corresponding string values in that order (no separator).

MD5-hash the UTF-8 bytes of the concatenated string.

Format the hash as a lowercase hex string — that is your checksum.

transType	Keys included in checksum (sorted lexically)
SALE	amount, currencyCode, merchantRemarks (if present), posReference, scheme, transType
VOID	posReference, transType
QUERY	posReference, transType
INIT	activationCode, transType

INFO

Only keys that are present in the bundle/message are included. If an optional key is absent, it is skipped rather than treated as an empty string.

Activity Intent

Launch PayCube Lite's MainActivity for UI-driven payment flows. Your app receives the result via onActivityResult / ActivityResultLauncher.
This is applicable to SALE payment flow only.

Step 1: Verify PayCube Lite is Installed

Step 2: Declare ActivityResultLauncher

INFO

Both success and error responses are returned as RESULT_OK with a JSON string in the result extra. Check the status field in the JSON to determine the outcome — a status of "ERROR" indicates a failure.

SALE

Request parameters:

Parameters	Example	Remarks
transType	SALE	To trigger AXS payment app for payment
scheme	CARD	Options of schemes: CARD,QR,ALIPAY,WECHAT,PAYNOW
amount	10	Amount in cent. Example: 10 = $0.10
currencyCode	SGD	ISO 4217 currency codes
posReference	12345	POS' unique identifier for the transaction
merchantRemarks	Merchant Ref-1	POS' merchant reference for the transaction Present only for CARD payment.
checksum	9e107d9d372bb682…	MD5 checksum value

Sample Request Data

INFO

Checksum walk through:

with merchantRemarks:

Keys (sorted): amount, currencyCode, merchantRemarks, posReference, scheme, transType

Concatenated: 2550SGDTable 5ORD-20260701-001CARDSALE

without merchantRemarks:

Keys (sorted): amount, currencyCode, posReference, scheme, transType

Concatenated: 2550SGDORD-20260701-001CARDSALE

Sample Codes

Response Parameters

Parameters	Example	Remarks
transType	SALE	Echo from request
transactionId	12345	For AXS PayCube Lite: Unique transaction ID returned from AXS payment gateway for each transaction For AXS PayCube Pro (Castle): Echo from request (posReference) Always use this value for future QUERY or VOID action
transactionReference	M67890	For AXS PayCube Lite: A unique reference ID for merchant to reconcile the record against Transaction Reference in AXS Merchant Portal For AXS PayCube Pro (Castle): Echo from request (posReference)
status	SUCCESS	Status of the transaction. SUCCESS, DECLINED, ERROR
errorCode		Optional, code is present only if the status is ERROR
errorHeader		Optional, header is present only if the status is ERROR
errorDescription	Connection timeout	Optional, description is present only if the status is ERROR
scheme	VISA	Payment scheme. Available values: VISA, MASTERCARD, UNIONPAY, AMEX, PAYNOW, WECHAT, ALIPAY
responseCode	00	Present only for CARD payment. Refer to gateway response code for more details
tid	10004657	Terminal ID
mid	100023987253	Unique Merchant ID assigned by AXS
approvalCode	831000	Gateway approval code. Present only for CARD payment.
transDateTime	YYYY-MM-DDTHH:mm:ssZ	Transaction timestamp ISO-8601 UTC
retrievalReferenceNumber	611204599707	Gateway RRN. Present only for CARD payment.
amount	10	Echo from request
currencyCode	SGD	Echo from request

Sample Response Data

Bound Service (IPC)

Bind to SoftPosBackgroundService and exchange structured messages via Android Messenger. Supports INIT, VOID, and QUERY without launching a UI.

Step 1: Bind to SoftPosBackgroundService

Use an explicit ComponentName targeting the service class directly. Do not rely on an intent-action filter.

Step 2: Send a Message

Standard Response Parameters

All the following functions in this section are having standard response parameters.

Parameters	Example	Remarks
transType	VOID	Type of the transaction for the record: INIT, VOID, QUERY
transactionId	12345	For AXS PayCube Lite: Unique transaction ID returned from AXS payment gateway for each transaction AXS PayCube Pro (Castle): Echo from request (posReference)
transactionReference	M67890	For AXS PayCube Lite: A unique reference ID for merchant to reconcile the record against Transaction Reference in AXS Merchant Portal For AXS PayCube Pro (Castle): Echo from request (posReference)
status	SUCCESS	Status of the transaction. SUCCESS, DECLINED, ERROR
errorCode		Optional, code is present only if the status is ERROR
errorHeader
errorDescription	Connection timeout	Optional, description is present only if the status is ERROR
scheme	VISA	Payment scheme. Available values: VISA, MASTERCARD, UNIONPAY, AMEX, PAYNOW, WECHAT, ALIPAY
responseCode	00	Present only for CARD payment. Refer to gateway response code for more details
tid	10004657	Terminal ID
mid	100023987253	Unique Merchant ID assigned by AXS
approvalCode	831000	Gateway approval code. Present only for CARD payment.
transDateTime	YYYY-MM-DDTHH:mm:ssZ	Date time in UTC ISO
retrievalReferenceNumber	611204599707	Gateway RRN. Present only for CARD payment.
amount	10	Echo from request
currencyCode	SGD	From the SALE record

INIT (Device Activation)

Request parameters:

Parameters	Example	Remarks
transType	INIT	To trigger AXS payment app for initialisation
activationCode	2345-5465-3245-2345	Unique activation code assigned to individual terminal
checksum	9e107d9d372bb6826bd81d3542a419d6	MD5 checksum value

Sample Code

Sample Response Data

VOID

Voids an existing approved transaction. The service looks up the transaction by posReference.

WARNING

Restriction: Void is only permitted on the same calendar day (SGT) as the original transaction.

Request Parameters

Parameters	Example	Remarks
transType	VOID	To trigger AXS payment app to void specific transaction
posReference	12345	POS' unique identifier for the transaction sent during SALE
checksum	9e107d9d372bb6826bd81d3542a419d6	MD5 checksum value

Sample Code

Sample Response Data

QUERY

Retrieves the current status of a transaction by its posReference. The response shape differs slightly between card and QR results.

Request parameters:

Parameters	Example	Remarks
transType	QUERY	To trigger AXS payment app for query specific transaction
posReference	12345	POS' unique identifier for the transaction sent during SALE / VOID
checksum	9e107d9d372bb6826bd81d3542a419d6	MD5 checksum value

Sample Code

Sample Response Data

Error Handling

Scenario	Handling
status = ERROR	To trigger a QUERY command using posReference send during SALE / VOID action.
connection timeout	To trigger a QUERY command using posReference send during SALE / VOID action.

Error Message

Error Code	Proposed Error Message	Remark/Scenario
40_000	Error Header: Initialization failed [40_000] Error Message: Please restart the app and try again.	InitSoftPosError
40_001	Error Header: Setup failed [40_001] Unable to complete setup. Please try again or contact support team.	SetupSoftPosError
40_002	Error Header: No configuration found [40_002] Error Message: Default configuration is missing. Please verify your setup.	NoDefaultConfig
41_001	Error Header: Payment result could not be processed [41_001] Error Message: Please try the transaction again.	ParsingActivityResultFailed
41_002	Error Header: Unable to retrieve payment profile [41_002] Error Message: Please check your connection and try again.	ProfileNotFound
42_001	Error Header: Card Detection timed out [42_001] Error Message: Please retry and ensure the card is held steady.	AbortedCardDetectionTimeout
42_002	Error Header: Transaction Aborted [42_002] Error Message: Transaction was cancelled manually.	AbortedManually - User press 'back' button / User press home button
42_003	Error Header: Unable to read Card. Retry limit exceeded. [42_003] Error Message: Please retry or use another payment method.	AbortedCardReadRetryCountExceeded
43_001	Error Header: Connection timed out [43_001] Error Message: Unable to reach the server. Please check your network.	ConnectionTimeout
43_002	Error Header: Request Failed [43_002] Error Message: There was an issue with the request. Please check your details and try again.	NetworkClientSideError
43_003	Error Header: Service Unavailable [49_003] Error Message: We're having trouble processing your request right now. Please try again shortly.	NetworkServerSideError
49_000	Error Header: Unexpected Error [49_000] Error Message: We received an unexpected response while processing your request. Please retry or contact support.	ResultNull
49_001	Error Header: Service Issue [49_001] Error Message: We couldn't complete the request due to a temporary system issue. Please try again.	OtherSourceError - Trigger logout from admin portal / expired
49_002	Error Header: Unexpected Error [49_002] Error Message: An error occurred while processing your request. Please try again.	OtherSourceException


FE1001	Error Header: Amount Exceeds Limit [FE1001] Error Message: The transaction amount exceeds the maximum allowed limit. Please enter a lower amount.	Transaction amount exceeds the permitted limit
FE1002	Error Header: Transaction Type Required [FE1002] Error Message: A transaction type is required to proceed.	transType field is absent or empty in the intent payload
FE1003	Error Header: Unsupported Transaction Type - {transType} [FE1003] Error Message: The transaction type is not recognized. Please use a supported transaction type.	transType value is not one of the recognised values. Recognised values: Sale, Void, Query
FE1004	Error Header: Missing Required Fields - {keys} [FE1004] Error Message: Required transaction details are missing. Please ensure required fields such as amount, currency, or transaction type are provided.	One or more mandatory fields missing from the intent payload. e.g. keys: amount, currency, transType
FE1005	Error Header: Request Validation Failed [FE1005] Error Message: The transaction request could not be validated. Please verify the request and try again.	MD5 checksum in payload does not match computed value
FE1006	Error Header: Transaction Not Authorized - {transType} [FE1006] Error Message: The requested transaction type is not authorised. Please contact service provider for assistance.	Merchant is not authorised for the given transaction type. Recognised values: Sale, Void, Query
FE1007	Error Header: Payment Method Not Recognized - {scheme} [FE1007] Error Message: The selected payment method is not recognised. Please try another payment method.	Payment scheme is not recognised. e.g. scheme: Visa, Mastercard, PayNow
FE1008	Error Header: Unable to Complete Transaction [FE1008] Error Message: An unexpected issue occurred during transaction processing. Please try again.	Unexpected exception during transaction execution. e.g. error: NullPointerException, IllegalArgumentException
FE1009	Error Header: Transaction Cancelled [FE1009] Error Message: The transaction was cancelled before completion.	QR manually cancel
FE1010	Error Header: QR Code Expired [FE1010] Error Message: The QR Code is no longer valid. Please generate a new QR code and try again.	QR expired


AN1001	Error Header: Invalid Request [AN1001] Error Message: No transaction details were received. Please try again.	Null request bundle received in SoftPosBackgroundService - (When android receive nothing)
AN1002	Error Header: Service Under Maintenance [AN1002] Error Message: The service is currently unavailable due to scheduled maintenance. Please try again later.	App is in maintenance mode
AN1003	Error Header: App Update Required [AN1003] Error Message: Your app version ({current}) is below the minimum required version ({minimum}). Please update the app to continue.	e.g. current: 1.0.0, minimum: 1.2.0 → "App version 1.0.0 is below the minimum required version 1.2.0. Please update the app."
AN1004	Error Header: Request Validation Failed [AN1004] Error Message: The transaction request could not be validated. Please verify the request and try again.	MD5 checksum in the request does not match computed value
AN1005	Error Header: Unsupported Transaction Type - {transType} [AN1005] Error Message: The transaction type is not recognized. Please use a supported transaction type.	transType value is not recognised. Recognised values: INIT, SALE, VOID, QUERY, CAPTURE
AN1006	Error Header: Missing Activation Code [AN1006] Error Message: The activation request is missing the required activation code. Please verify the request and try again.	activationCode field missing from INIT request
AN1007	Error Header: Activation Already Completed [AN1007] Error Message: This device has already been activated. Initialization is not required.	INIT attempted on an already-activated device
AN1008	Error Header: Request Failed [AN1008] Error Message: {API_MESSAGE}	Message comes from the API response. e.g. msg: "Invalid merchant credentials", "Merchant not found", "Server timeout"
AN1009	Error Header: Device Error [AN1009] Error Message: {SDK_MESSAGE}	Message comes from the SoftPOS SDK. e.g. msg: "SDK licence expired", "Hardware not supported"
AN1010	Error Header: Setup Failed [AN1010] Error Message: {SETUP_ERROR_MESSAGE}	Message comes from the setup step that failed. e.g. msg: "Failed to register device", "Configuration missing"
AN1011	Error Header: POS Reference Required [AN1011] Error Message: A POS reference is required to process the void transaction.	posReference field missing from VOID request
AN1012	Error Header: Activation Required [AN1012] Error Message: Device activation is required before performing this operation.	VOID attempted before device is activated
AN1013	Error Header: Amount Exceeds Limit [AN1013] Error Message: The transaction amount exceeds the permitted limit. Please enter a lower amount.	Request more than the amount
AN1014	Error Header: Unable to Void Transaction [AN1014] Error Message: Void is only available for same-day transactions	VOID attempted on a non-same-day transaction
AN1015	Error Header: Void Failed [AN1015] Error Message: {VOID_API_MESSAGE}	Message comes from the VOID API response. e.g. msg: "Transaction already voided", "Original transaction not found"
AN1016	Error Header:POS Reference Required [AN1016]Error Message:A POS reference is required to perform this operation.	posReference field missing from QUERY request
AN1017	Error Header: Activation Required [AN1017] Error Message: Device activation is required before performing this operation.	QUERY attempted before device is activated
AN1018	Error Header: Transaction Not Found [AN1018] Error Message: The transaction could not be found. Please verify the transaction details and try again.	QUERY returned no matching transaction for the given posReference
AN1024	Error Header: Transaction Failed [AN1024] Error Message: An unexpected error occurred while processing the transaction. Please try again.	Unexpected exception in headless transaction flow. e.g. msg: "NullPointerException: amount is null", "IllegalStateException"
AN1025	Error Header: Unexpected Error [AN1025] Error Message: We were unable to process your request. Please try again.	Fallback error for unhandled finishWithError cases

App-to-App Integration

Context#

Device Requirement#

Mechanism#

Package & Class Constants#

AndroidManifest - Package Visibility (Android 11+)#

Checksum Algorithm#

Activity Intent#

Step 1: Verify PayCube Lite is Installed#

Step 2: Declare ActivityResultLauncher#

SALE#

Request parameters:#

Response Parameters#

Bound Service (IPC)#

Step 1: Bind to SoftPosBackgroundService#

Step 2: Send a Message#

Standard Response Parameters#

INIT (Device Activation)#

Request parameters:#

VOID#

Request Parameters#

QUERY#

Request parameters:#

Error Handling#

Error Message#

Context

Device Requirement

Mechanism

Package & Class Constants

AndroidManifest - Package Visibility (Android 11+)

Checksum Algorithm

Activity Intent

Step 1: Verify PayCube Lite is Installed

Step 2: Declare ActivityResultLauncher

SALE

Request parameters:

Response Parameters

Bound Service (IPC)

Step 1: Bind to SoftPosBackgroundService

Step 2: Send a Message

Standard Response Parameters

INIT (Device Activation)

Request parameters:

VOID

Request Parameters

QUERY

Request parameters:

Error Handling

Error Message