App Integration

Our App Integration option allows your own Android app on the same payment device to initiate requests that are actioned appropriately within the Android Trust Payments app.

Getting started

This resource is designed for developers looking to seamlessly incorporate our SmartPOS functionality alongside their own Android applications. By leveraging Android's Intents and Broadcasts system, we've created a flexible way to handle various actions.

Before we continue, there are two main types of communication to be aware of:

Events - Triggered by the Kinetic Pay subsystem.
API Calls - Initiated by your application to perform specific actions.

Overview

Set up broadcast receivers - Create broadcast receivers in your application to handle the various intents used for transactions and status updates.
Implement transaction initiation - Use the com.kineticsmart.intent.PAYMENT_START_TRANSACTION action to start new transactions.
Handle transaction status updates - Listen for the transaction_status_changed action to receive real-time updates on transaction progress.
Process completed transactions - Use the com.kineticsmart.intent.PAYMENT_ENGINE_READY action to retrieve details of completed transactions.
Implement receipt printing - Use the com.kineticsmart.intent.PAYMENT_ENGINE_READY action with specific parameters to print merchant and customer receipts.
Error handling - Implement proper error handling for cases such as invalid transaction types or other potential issues.

API calls reference

Sale

Initiates a new sale transaction.

Intent startSale = new Intent("com.kineticsmart.intent.PAYMENT_START_TRANSACTION");
startSale.putExtra("amount", "100");
startSale.putExtra("id", UUID.randomUUID().toString());
startSale.putExtra("transactionType", "sale");
sendBroadcast(startSale);

Refund

Initiates a new refund transaction.

Intent startRefund = new Intent("com.kineticsmart.intent.PAYMENT_START_TRANSACTION");
startRefund.putExtra("amount", "100");
startRefund.putExtra("id", UUID.randomUUID().toString());
startRefund.putExtra("transactionType", "refund");
sendBroadcast(startRefund);

Reconcile

Initiates a new reconciliation (end-of-day) transaction.

Intent startReconcile = new Intent("com.kineticsmart.intent.PAYMENT_START_TRANSACTION");
startReconcile.putExtra("transactionType", "reconcile");
sendBroadcast(startReconcile);

Print

Prints a receipt for the last transaction.

Intent printReceipt = new Intent("com.kineticsmart.intent.PAYMENT_ENGINE_READY");
printReceipt.putExtra("transactionType", "print");
printReceipt.putExtra("printRequest", "transaction.last.print_merchant_receipt");
sendBroadcast(printReceipt);

Field Reference

Event fields

Field	Format	Type	Description
transaction_status	String	Refund, Sale	Status of the transaction.

API call fields

Field	Format	Supported transaction types	Description
amount	Integer	Refund, Sale	The full amount for the transaction in main units (e.g. £20 would be submitted as "2000").
id	String (UUID)	Refund, Sale	Unique identifier for the API call.
printRequest	String	Print	Specifies the type of receipt to be printed in the Print request. Supported receipt types are: transaction.last.print_merchant_receipt - Merchant copy transaction.last.print_cardholder_receipt - Customer copy
reference_txn_id	String	Sale	UUID of previously approved Preauth or Adjustment transaction, required when processing subsequent Adjustment or Completion transaction subtypes.
subType	String	Sale	(Optional) Submit one of the following supported values: preauth - Processes a pre-auth for the amount submitted, adjustment - adjusts to the amount previously approved via Preauth or Adjustment transaction request. A preauth can be adjusted up or down in amount via this method completion - Completes a pending pre-auth. Amount can be lesser than or equal to the last Preauth or Adjustment amount. If the amount has to be increased, an adjustment transaction must precede the completion request.
transactionType	Alphanumeric	All	The type of request being submitted. Supported requests are: print reconcile refund sale

Implementation guide

Listening for Events

To receive transaction status updates:

public void onReceive(Context context, Intent intent) {
  if (intent.getAction().equals("transaction_status_changed")) {
    String status = intent.getStringExtra("transaction_status");
    // Process the status update
  }
}

Making API calls

Example of initiating a sale transaction:

String txnUUID = UUID.randomUUID().toString();
Intent startSale = new Intent("com.kineticsmart.intent.PAYMENT_START_TRANSACTION");
startSale.putExtra("amount", "100");
startSale.putExtra("id", txnUUID);
startSale.putExtra("transactionType", "sale");
sendBroadcast(startSale);

Handling responses

To handle completed transactions:

public void onReceive(Context context, Intent intent) {
  if (intent.getAction().equals("com.kineticsmart.intent.PAYMENT_ENGINE_READ")) {
    String transactionDetails = intent.getStringExtra("transaction_status");
    // Process the completed transaction details
  }
}

Troubleshooting

Common issues

Transaction not starting - Ensure you're using the correct Intent action and extras.
No status updates received - Check if you've registered your BroadcastReceiver correctly.
Print job not executing - Verify the printer status and connection.

Further reading on this topic