|
| 1 | +# ga-android-pos-client |
| 2 | +<a href='https://bintray.com/globalaccelerex/globalaccelerex-android/ga-android-pos-client/_latestVersion'><img src='https://api.bintray.com/packages/globalaccelerex/globalaccelerex-android/ga-android-pos-client/images/download.svg'></a> |
| 3 | + |
| 4 | +This library has been designed for easy integration of Global Accelerex android POS services into third party android applications. |
| 5 | + |
| 6 | +# Requirements |
| 7 | + |
| 8 | +Any application making use of this library should run on Global Accelerex android POS devices or on an android device with Global Accelerex Mock base app installed on it. |
| 9 | + |
| 10 | +# Getting Started |
| 11 | + |
| 12 | +## Installation |
| 13 | +You do not need to clone this repository or download the files. Just add the following lines to your app's `build.gradle`: |
| 14 | + |
| 15 | +`implementation 'com.globalaccelerex.android:ga-android-pos-client:1.0.0'` |
| 16 | + |
| 17 | +## Setup |
| 18 | + |
| 19 | +After including the library in your application's `build.gradle`, create an instance of `GAClientLib` like this: |
| 20 | + |
| 21 | +```kotlin |
| 22 | +val supportLibrary = GAClientLib.Builder() |
| 23 | + .setCountryCode(Countries.NIGERIA) |
| 24 | + .build() |
| 25 | +``` |
| 26 | +N.B `Countries` should represent the country in which the pos device will be used. |
| 27 | + |
| 28 | +Now that you have an instance of the library in your project, it can be used to make all necessary and supported transactions. |
| 29 | + |
| 30 | +Suggestion: This initialization should be in singleton format because new initializations may carry different configurations. |
| 31 | + |
| 32 | +## Key Exchange |
| 33 | + |
| 34 | +```kotlin |
| 35 | +class MainActivity : AppCompatActivity() { |
| 36 | + |
| 37 | + val supportLibrary = GAClientLib.Builder() |
| 38 | + .setCountryCode(Countries.NIGERIA) |
| 39 | + .build() |
| 40 | + |
| 41 | + override fun onCreate(savedInstanceState: Bundle?) { |
| 42 | + super.onCreate(savedInstanceState) |
| 43 | + setContentView(R.layout.activity_main) |
| 44 | + |
| 45 | + supportLibrary.makeKeyExchangeRequest(callingComponent = this) // calling component should either be an Activity or a fragment |
| 46 | + } |
| 47 | +} |
| 48 | +``` |
| 49 | +Note that the function must be called from withing an Activity or a Fragment. |
| 50 | + |
| 51 | +## Parameters Request |
| 52 | +To get the details of the POS terminal being used, follow this example: |
| 53 | + |
| 54 | +```kotlin |
| 55 | +class MainActivity : AppCompatActivity() { |
| 56 | + |
| 57 | + val supportLibrary = GAClientLib.Builder() |
| 58 | + .setCountryCode(Countries.NIGERIA) |
| 59 | + .build() |
| 60 | + |
| 61 | + override fun onCreate(savedInstanceState: Bundle?) { |
| 62 | + super.onCreate(savedInstanceState) |
| 63 | + setContentView(R.layout.activity_main) |
| 64 | + |
| 65 | + supportLibrary.makeParametersRequest(callingComponent = this) // calling component should either be an Activity or a fragment |
| 66 | + } |
| 67 | + |
| 68 | + override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { |
| 69 | + super.onActivityResult(requestCode, resultCode, data) |
| 70 | + if (resultCode == Activity.RESULT_OK) { |
| 71 | + if (requestCode == GaResponseKeys.PARAMETERS_REQUEST_CODE) { |
| 72 | + val posInformation: PosInformation? = supportLibrary.getPosParametersResponse(data) |
| 73 | + } |
| 74 | + } |
| 75 | + } |
| 76 | +} |
| 77 | +``` |
| 78 | +When this request is made, the Pos details are returned as an object of `PosInformation` in the `onActivityResult` of your Activity or Fragment. |
| 79 | + |
| 80 | +# Usage |
| 81 | + |
| 82 | +### Sample Usage |
| 83 | + |
| 84 | + ```kotlin |
| 85 | +class MainActivity : AppCompatActivity() { |
| 86 | + |
| 87 | + val supportLibrary = GAClientLib.Builder() //Step 1 |
| 88 | + .setCountryCode(Countries.NIGERIA) |
| 89 | + .build() |
| 90 | + |
| 91 | + override fun onCreate(savedInstanceState: Bundle?) { |
| 92 | + super.onCreate(savedInstanceState) |
| 93 | + setContentView(R.layout.activity_main) |
| 94 | + |
| 95 | + //Assuming Key exchange and Parameters requests have been carried out. |
| 96 | + |
| 97 | + //Step 2 |
| 98 | + supportLibrary.makeCardPresentTransactionRequest( |
| 99 | + amount = 2.0, //step 2.1 |
| 100 | + transactionType = TransactionType.CP_PURCHASE, //step 2.2 |
| 101 | + customPrint = true, //step 2.3 |
| 102 | + callingComponent = this //step 2.4 |
| 103 | + ) |
| 104 | + } |
| 105 | + |
| 106 | + override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { |
| 107 | + super.onActivityResult(requestCode, resultCode, data) |
| 108 | + |
| 109 | + //Step 3 |
| 110 | + if (resultCode == Activity.RESULT_OK) { |
| 111 | + if (requestCode == GaResponseKeys.CARD_PURCHASE_REQUEST_CODE) { //step 3.1 |
| 112 | + val cardTransactionResponse: CardTransactionResponse? = supportLibrary.getCardTransactionResponse(data) //step 3.2 |
| 113 | + // Perform actions with the returned data |
| 114 | + } |
| 115 | + } |
| 116 | + } |
| 117 | +} |
| 118 | +``` |
| 119 | +### Step 1 (Setup) |
| 120 | +This step has been covered already in the Getting Started section |
| 121 | + |
| 122 | +### Step 2 (Initializing a transaction) |
| 123 | +Global accelerex POS may support different transactions such as Card Present Transactions (CP), Card Not Present Transactions (CNP) and Mobile Money Transactions (MM) depending on your location. Select a corresponding function to carry out your preferred transaction. |
| 124 | + |
| 125 | +### Step 2.1 (Setting the amount) |
| 126 | +Any amount entered should be in `Double` format. |
| 127 | + |
| 128 | +### Step 2.2 (Setting the transaction type) |
| 129 | +A wide variety of transactions types can be made with (CP, CNP AND MM) transactions. `TransactionType` contains an exhaustive list of possible transactions to choose from. |
| 130 | +Note: |
| 131 | +CP - Card Present |
| 132 | +CNP - Card Not Present |
| 133 | +MM - Mobile Money |
| 134 | + |
| 135 | +### Step 2.3 (Setting the print mode) |
| 136 | +After making a transaction, you can decide to design your own custom receipt format in which case `customPrint` is set to `true`, or use the default print format in which case `customPrint` is set to `false` |
| 137 | + |
| 138 | +### Step 2.4 (Setting the calling component) |
| 139 | +As stated earlier, these functions should be called from an `Activity` or a `Fragment`. |
| 140 | +The calling component set to `this` refers to the activity or fragment that the functions are called from. |
| 141 | + |
| 142 | +### Step 3 (Retrieving transaction response) |
| 143 | +After a transaction is called, the POS device takes over and performs all the neccesary procedures involved in carrying that transaction. When this is done, the transaction details are returned to your application. To retrieve this response, you'll have to listen for it in the activity or fragment's `onActivityResult`. |
| 144 | + |
| 145 | +### Step 3.1 (Listening for your transaction) |
| 146 | +For every `TransactionType` value, there is a corresponding `GAResponseKeys` key for it. To listen for the response details compare the requestCode to the matching transaction type. |
| 147 | + |
| 148 | +### Step 3.2 (Retrieving transaction response data) |
| 149 | +After listening for a particular transaction, you can get the response by calling a get function related to the transaction that was called from the client library. |
| 150 | + |
| 151 | + |
| 152 | + |
| 153 | +All transactions usually follow the same format. However you can take a look at the example project for more details. |
| 154 | + |
| 155 | + |
| 156 | +# Issues |
| 157 | +If you're experiencing technical difficulties or you have suggestions for the library, please raise an issue at: |
| 158 | +https://github.com/global-accelerex/ga-android-pos-client/issues |
| 159 | + |
| 160 | + |
| 161 | + |
| 162 | + |
| 163 | + |
| 164 | + |
| 165 | + |
| 166 | + |
| 167 | + |
| 168 | + |
| 169 | + |
| 170 | + |
| 171 | + |
| 172 | + |
| 173 | + |
| 174 | + |
| 175 | + |
| 176 | + |
| 177 | + |
| 178 | + |
| 179 | + |
| 180 | + |
0 commit comments