API DOCUMENT
This document outlines the consumer facing endpoints for integrating payment and print functions. The operations are triggered via Android Intents. Sample code to trigger intents can be found at the bottom of this document. Additionally, all code samples are in Kotlin.
Responses are received on the Intent object. The three String Extra keys are status , statusMessage and data. Every successful operation (Activity.RESULT_OK) returns a status containing a valid Response Code as detailed in the RESPONSE CODES section.
N.B: For response code 03, 04, 05 and 06 the data field is empty. statusMessage always contains success or failure message of the operation.
N.B: The android terminals do not yet support Google Play Services. However, you'll still be able to use Firebase Crashyltics.
RESPONSE CODES
| Code | Message | Decription |
|---|---|---|
| 00 | SUCCESS | Message sent to host and transaction has been approved. |
| 02 | FAILED | Message sent to host but transaction has been declined. |
| 03 | CANCEL | User canceled transaction, Signal lost from host, or an invalid transaction was aborted by the payment application. |
| 04 | INVALID FORMAT | Invalid data format of message sent to payment application. |
| 05 | WRONG PARAMETER | Invalid parameter(S) passed as part of the data sent to payment application. |
| 06 | TIMEOUT | PIN entry timeout or card read timeout. |
INTENT SETTINGS(Nexgo terminals)
The current intent filter for an android app than want to be launched using the PAY button on the Nexgo terminal home screen.
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
<intent-filter>
<action android:name="android.intent.action.PAY_APP" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
OPERATIONS
KEY EXCHANGE (Optional)
Intent Name = com.globalaccelerex.keyexchange
This intent is used to do a key exchange without requiring a password. A successful key exchange will return Activity.RESULT_OK and a status of 00. A failed key exchange will return Activity.RESULT_OK and a status of 02.
Sample Key Exchange Intent Request
fun doKeyExchange() {
startActivityForResult(KEY_EXCHANGE_INTENT, KEY_EXCHANGE_REQUEST)
}
GET PARAMETERS
Intent Name = com.globalaccelerex.utility
When status is 00, the response is provided in the String Extra Field data on the Intent object. A failed operattion will return Activity.RESULT_OK and a status of 02.
It's recommended to parse this JSON data as a TreeMap. A TreeMap allows for case insensitivity on keys
val treeMap = TreeMap<String, String>(String.CASE_INSENSITIVE_ORDER)
Sample Get Parameters Intent Request
fun doGetParameters() {
val jsonString = "{ \"action\":\"PARAMETER\" }"
val intent = Intent(PARAMETER_INTENT)
intent.putExtra("requestData", jsonString)
startActivityForResult(intent, PARAMETER_REQUEST)
}
Get Parameters Sample Response Data
{
"Biller_ID": "GA000000001",
"MerchantID": "3169MB126086441",
"TerminalID": "3181BM43",
"serialNumber": "GA123400",
"PTSP": "Global Accelerex",
"FooterMessage": "THANKS FOR COMING",
"MerchantName": "Accelerex Inc.",
"MerchantAddress": "Ilupeju, Lagos, Nigeria",
"BankName": "RANDOM BANK",
"BankLogo": "https://aws.com/bank_logo.png",
"MerchantCategoryCode": "6010",
"baseAppVersion":"Rex MOCK-POS 1.0.0-230720",
"currency":"NGN"
}
TRANSACTION
Intent Name = com.globalaccelerex.transaction
This request requires some extra data(Request Data). The data is passed in the form of a Stringified JSON object. And is passed as a String Extra on the field requestData on the Intent object.
When status is 00 or 02, the response is provided in the String Extra Field data on the Intent object.
There are three transaction sets supported. For Balance, a value of 0.00 Naira should be sent. No debit occurs on the card inserted
Transaction Types
| Key | Description |
|---|---|
| PURCHASE | Normal purchase transaction |
| PURCHASEWITHCB | Purchase transaction with cashback |
| BALANCE | Check card balance |
| PREAUTH | Pre-authorization transaction |
| PREAUTHCOMPLETE | Pre-authorization completion transaction |
| REFUND | Refund transaction |
| CASHADVANCE | Cash advance transaction |
| REVERSAL | Reversal transaction for an unsettled transaction |
| #### Transaction Request Data |
| Name | Type | Description |
|---|---|---|
| transType | String | Transaction Type |
| amount | String | Transaction amount to two decimal places |
| String | Determine if receipt should be printed. ("true" or "false") | |
| cashBackAmount | String | Cash back amount for a PURCHASEWITHCB transaction type. It MUST be provided for PURCHASEWITHCB transaction type |
| rrn | String | Transaction retrieval reference number of a previous transaction. MUST be provided for PREAUTHCOMPLETE and REVERSAL transaction types |
| transactionReference | String | Custom transaction reference used for transaction reconciliation with the processor. |
This data is converted to a JSON object and then stringified.
Sample Request Data
{
"transType": "PURCHASE",
"amount": "2.00",
"print": "true",
"transactionReference": "1234567890ABCDEFJ"
}
{
"transType": "PURCHASEWITHCB",
"amount": "2.00",
"print": "true",
"cashBackAmount": "1.00",
"transactionReference": "1234567890ABCDEFJ"
}
{
"transType": "REVERSAL",
"amount": "2.00",
"print": "true",
"rrn": "201902271155",
"transactionReference": "1234567890ABCDEFJ"
}
Transaction Response Data
This endpoint returns a Stringified JSON object in the data key.
{
"aid": "A0000000031010",
"amount": "2.0",
"cashBackAmount": "1.00",
"appLabel": "VISA",
"authcode": "806424",
"cardExpireDate": "08/19",
"cardHolderName": "A/OLORUNTOBILOLA",
"datetime": "2019-02-27 11:52:59",
"maskedPan": "496009******3329",
"message": "Approved successfully",
"nuban": "0054365768",
"pinType": "Pin Verified",
"rrn": "201902271155",
"stan": "199535",
"statuscode": "00",
"terminalID": "3181BM43",
"transactionType": "PURCHASEWITHCB",
"merchantName": "Accelerex Inc.",
"merchantId": "3169MB126086441",
"merchantAddress": "Ilupeju, Lagos, Nigeria",
"merchantCategoryCode": "6010",
"bankName": "RANDOM BANK",
"bankLogo": "https://aws.com/bank_logo.png",
"ptsp": "Global Accelerex",
"ptspContact": "0700ACCELEREX",
"footerMessage": "Thanks for using our POS",
"deviceSerialNumber": "GA123400",
"baseAppVersion":"Rex MOCK-POS 1.0.0-230720",
"currency":"NGN"
}
The fields nuban and authcode are nullable fields.
- amount is sale amount.
- Not all Issuers return nuban for transactions.
- Some failed transactions don't have an Auth Code.
Sample Transaction Intent Request
fun doCardTransaction(amount: String) {
val jsonString =
"{ \"transType\": \"PURCHASE\", \"amount\":\"$amount\", \"print\":\"false\" }"
val intent = Intent(PURCHASE_INTENT)
intent.putExtra("requestData", jsonString)
startActivityForResult(intent, PURCHASE_REQUEST)
}
TRANSACTION HISTORY
Intent Name = com.globalaccelerex.reprint
This intent launches the transaction history screen where you can view all transactions carried out on the terminal. The screen requires a password from the user.
PRINTING
Intent Name = com.globalaccelerex.printer
This request requires some extra data(Request Data). The data is passed the form of a Stringified JSON object. And is passed as a String Extra on the field jsonData on the Intent object.
The Print data class provided makes use of Moshi to annotate the fields.
Sample Print Json Object
{
"Receipt": [{
"Bitmap": "filename",
"letterSpacing": 5,
"String": [{
"isMultiline": true,
"header": {
"text": "Merchant Name",
"align": "centre",
"size": "large",
"isBold": true
},
"body": {
"text": "Global Accelerex",
"alignment": "centre",
"size": "normal",
"isBold": false
}
},
{
"isMultiline": false,
"header": {
"text": "Reference Number",
"align": "left",
"size": "large",
"isBold": true
},
"body": {
"text": "123456789"
}
}
]
},
{
"Bitmap": "filename",
"letterSpacing": 5,
"String": [{
"isMultiline": true,
"header": {
"text": "Merchant Name",
"align": "centre",
"size": "large",
"isBold": true
},
"body": {
"text": "Allen Tobi",
"alignment": "centre",
"size": "normal",
"isBold": false
}
},
{
"isMultiline": false,
"header": {
"text": "Reference Number",
"align": "left",
"size": "large",
"isBold": true
},
"body": {
"text": "abcd1234"
}
}
]
}
]
}
Sample Print Kotlin Object
data class PrintObject(@Json(name = "Receipt") val printFields: List<PrintField>)
data class PrintField(
@Json(name = "Bitmap") val filename: String,
@Json(name = "letterSpacing") val letterSpacing: Int,
@Json(name = "String") val stringFields: List<StringField>
)
data class StringField(
@Json(name = "isMultiline") val isMultiline: Boolean,
@Json(name = "header") val header: TextField,
@Json(name = "body") val body: TextField
)
data class TextField(
@Json(name = "text") val text: String,
@Json(name = "align") val align: String?,
@Json(name = "size") val size: String?,
@Json(name = "isBold") val isBold: Boolean?
)
Sample Print Intent Request
fun print(jsonString: String) {
val intent = Intent(PRINTER_INTENT)
intent.putExtra("jsonData", jsonString)
startActivityForResult(intent, PRINT_REQUEST)
}
Field Description
| Name | Type | Description | Values |
|---|---|---|---|
| isMultiline | Boolean | Determine if header and body are printed on different lines | true/false |
| isBold | Boolean | Determine if to bolden TextField | true/false |
| align | String | Set alignment | center, left, right |
| size | String | Set text size | small, normal, large |
| Bitmap | String | Path to image file saved on disk |
Notes on Printing
- When the object TextField has an empty text field for both header and body the StringField is discarded. If an empty space is needed to save as a line break, specify a text field containing at least a space for the TextField header.
- When isMultiline is set to false on a StringField object, the fields align and isBold are ignored for the TextField body.
- If you need to print a single line. Set isMultiline to true and set the text field on the body TextField to an empty string.
SETTINGS
Intent Name = com.globalaccelerex.settings
This page allows you open a Settings GUI to allow a user carry out Key Exchange and Printing Parameters
Sample Settings Intent Request
fun launchSettings() {
startActivityForResult(Intent(SETTINGS_INTENT), SETTINGS_REQUEST)
}