Transaction App to App Integration Guide
Integration with the Halo.Go/Halo.Link App for Transactions using Android Intents or Deeplinking.
1. Architecture
To initiate a transaction, we recommend that the customer app initiate a call between itself and the customer backend first for it to create an intent transaction request by calling the Halo backend using the transaction's details. This information is then stored in the Halo backend, allowing the Halo app to fetch it. Otherwise, if the customer wishes to reduce the number of endpoint calls, they can pass through all the transaction details in the intent call itself - this is not available with deeplinking. The process is as follows:
Approach 1: Merchant Id Configurable Transaction
Note: We recommend this approach as it allows the customer to store the Halo backend api key and merchant id in their backend instead of baking it into the customer app. This is also useful for customers that have multiple merchant accounts that can receive a transaction request.
Customer app creates a request to the customer backend to create an intent transaction through a call to the Halo backend.
The customer backend will send these consumer transaction details received from the customer app and config in the customer backend:
unique transaction reference
currency code
transaction amount
merchant id (retrieved from the Halo Merchant Portal)
timestamp
The Halo backend receives the request and stores the transaction data.
The Halo backend creates a consumer transaction ID along with a signed transaction token (JWT) and responds by sending these two items back to the customer backend.
The customer backend returns the consumer transaction ID and the transaction token (JWT) to the customer app.
The consumer transaction ID and transaction token (JWT) are sent through an intent call made to the Halo.Go/Halo.Link app.
The customer app waits for the Halo.Go/Halo.Link app to return control back to the customer app with a success or error code.
Once the consumer transaction ID and the JWT are received by the Halo.Go/Halo.Link app, the following takes place:
The app will validate the JWT and the consumer transaction ID.
The app will then request transaction details from the Halo backend using the consumer transaction ID as a reference and the JWT as auth.
The Halo backend will return the transaction details if the transaction has not expired and if the JWT is valid.
The app will then begin processing the payment by fetching transaction configs and initiating a card read.
After the consumer has successfully tapped their card on the device, the app will then display the transaction result to the user and return control back to the customer app that initiated the intent transaction with a success or error code.
Approach 2: Constant Merchant Id Transaction
Note: This approach is useful for customers that have a single merchant account that can receive a transaction request. This is only available for tap intent transactions, not TT3 and deeplinking as of yet.
Customer app makes a call to the customer backend to get an intent session token which will be used for all transactions.
Customer app checks if the session token has not expired and then creates an intent to the Halo.Go/Halo.Link app with the transaction details:
unique transaction reference
currency code
transaction amount
jwt session token
The customer app waits for the Halo.Go/Halo.Link app to return control back to the customer app with a success or error code.
Once the transaction details are received by the Halo.Go/Halo.Link app, the following takes place:
The app will validate the JWT session token and transaction details.
The app will then fetch transaction config if it has not been fetched before, and caches this config.
The app will initiate a card read and wait for the consumer to tap their card on the device to process the payment.
The app will then display the transaction result to the user and return control back to the customer app that initiated the intent transaction with a success or error code.
2. Android Intents API
Steps in this section:
Retrieve a
Transaction ID
and paymentJWT
from the Halo Backend.Retrieve an
Intent Session Token
from the Halo Backend.Send an Intent request to the Halo.Go/Halo.Link application.
1. Retrieve a Transaction ID and JWT from Halo Backend
Let’s take a closer look at the API request.
POST
https://kernelserver.{env}.haloplus.io/{version}/consumer/intentTransaction
The call to the Halo Dot Backend to initiate an Intent Transaction.
Path Parameters
version*
String
The backend version (optional)
env*
String
The backend environment [dev, qa, prod]
Headers
Content-Type*
String
Content Type of the Request: application/json
x-api-key*
String
The API Key retrieved from the Merchant Portal (JWT can be used instead)
Authorization*
String
The JWT retrieved from logging in. (API Key can be used instead)
Request Body
merchantId*
String
Merchant ID from Merchant Portal
paymentReference*
String
Reference of the transaction
amount*
String
Amount of the transaction (100.01)
timestamp*
String
ISO Standard Timestamp
currencyCode*
String
ISO Standard Currency Codes
2. Retrieve an Intent Session Token from the Halo Backend
Let’s take a closer look at the API request.
POST
https://authserver.{env}.haloplus.io/{version}/refresh/intentSessionToken
The call to the Halo backend to retrieve an Intent Session Token.
Path Parameters
version*
String
The backend version (optional)
env*
String
The backend environment [dev, qa, prod]
Headers
Content-Type*
String
Content Type of the Request: application/json
x-api-key*
String
The API Key retrieved from the Merchant Portal (JWT can be used instead)
Authorization*
String
The JWT retrieved from logging in. (API Key can be used instead)
Request Body
expiryMinutes
Number
Duration for which the intent session token should last before it expires. If not provided, the session token will expire after 1 hour/60 minutes. If specified please note the the min value is 60 minutes and the max value is 720 minutes.
3. Send an Intent Request to the Halo Dot Go
We provide a sample code to help you with the intent request function call. The code is available in the App to App submenu under the "Help Center" tab in the menu in your Halo.Go Portal.
Here are the key components of the code as a simple guide:
Set key Halo intent constants
Check if the Halo.Go/Halo.Link app is installed
Create a function that will call Halo.Go/Halo.Link through an intent
Handle the result of the intent call
3. Deeplinking
1. Retrieve a Transaction Deep Link from the Halo Backend
You will need a API Key
and Merchant ID
from the Merchant Portal for this API call. The response will contain a deep link that can be used to invoke the Halo.Go/Halo.Link app.
Let’s take a closer look at the API request.
POST
https://kernelserver.{env}.haloplus.io/{version}/consumer/qrCode
The call to the Halo backend to retrieve a deep link.
Path Parameters
version*
String
The backend version (optional)
env*
String
The backend environment [dev, qa, prod]
Headers
Content-Type*
String
Content Type of the Request: application/json
x-api-key*
String
The API Key retrieved from the Merchant Portal (JWT can be used instead)
Authorization*
String
The JWT retrieved from logging in. (API Key can be used instead)
Request Body
merchantId*
Integer
Merchant ID from Merchant Portal
paymentReference*
String
Reference of the transaction
amount*
String
Amount of the transaction (100.01)
timestamp*
String
ISO Standard Timestamp
currencyCode*
String
ISO Standard Currency Codes
isConsumerApp*
Boolean
Indicate if the call is for a Consumer App
image*
JSON
Set to true to generate a QR code - {"required": false}
2. Use the Generated URL to call the Halo Dot Go application
The generated link returned by the API call can then be used to invoke the Halo.Go/Halo.Link application and start process transactions.
4. Conclusion
That concludes the guide on integrating the Halo.Go/Halo.Link app into your payment flow. For any questions, please do not hesitate to reach out to the Halo Dot Team.
Last updated