Description
The doPayment
service is the standard way to request the beginning of a transaction from the Arkos framework. It has two parameters (both TLV strings), which together includes all the information required by the framework to process the request to it’s completion.
Arkos Configuration
The first parameter is the Arkos Configuration, which is a standardized generic configuration format containing context related parameters, including but not limited to:
Acquirer Configuration (based on the NexoFAST model)
Host Security information
In most cases, this is a mostly static piece of data, provided by a TMS module or system
Payment Parameters
The second parameter is the Payment Parameters in which the caller must include the information required by all transactions. This parameter can also be enhanced with additional specific information for various use cases - for example, the list of purchased items for Acquirer specific processing.
Standard usage
// Create the minimal parameter set TlvTree paymentParams = TlvTree.Empty(); paymentParams.AddBin(ArkosTags.SelectedService, new byte[] { 0x00 }); // Amounts are in BCD. In most cases, all 3 amounts should be the same value. paymentParams.AddBin(ArkosTags.TransactionAmount, new byte[] { 0x00, 0x00, 0x00, 0x00, 0x10, 0x00 }); paymentParams.AddBin(ArkosTags.AmountAuthorised, new byte[] { 0x00, 0x00, 0x00, 0x00, 0x10, 0x00 }); paymentParams.AddBin(ArkosTags.TransactionAmountBeforeAdjustment, new byte[] { 0x00, 0x00, 0x00, 0x00, 0x10, 0x00 }); // The system needs to provide the Date and Time of this transaction, and the local TimeZone Calendar cal = Calendar.getInstance(); int utcOffsetMinutes = cal.getTimeZone().getOffset(cal.getTimeInMillis()) / 1000 / 60; byte[] utcOffset = new byte[2]; utcOffset[0] = (byte) (utcOffsetMinutes / 60); utcOffset[1] = (byte) (utcOffsetMinutes % 60); paymentParams.AddEMVDate(ArkosTags.TransactionDate, cal.get(Calendar.YEAR) % 100, cal.get(Calendar.MONTH) + 1, cal.get(Calendar.DAY_OF_MONTH)); paymentParams.AddEMVTime(ArkosTags.TransactionTime, cal.get(Calendar.HOUR), cal.get(Calendar.MINUTE), cal.get(Calendar.SECOND)); paymentParams.AddBin(ArkosTags.LocalTimezone, utcOffset); paymentParams.AddAscii(ArkosTags.SelectedLanguage, "en"); // Call to the doPayment API, sending the Arkos configuration, and parameters as a byte Array PaymentResult result = arkos.doPayment(configuration, paymentParams.AsBytes()); // Use the payment result Log.d("payment", "Result: " + result.result);
Data Parameters
Required - General
Name | Tag | Format | Usage |
---|---|---|---|
Selected Service |
|
| Identification of the payment service requested |
Transaction Amount |
|
| Amount of the transaction |
Authorised Amount |
|
| |
Transaction Amount Before Adjustment |
|
| |
Transaction Time |
|
| Time at which the current action is performed |
Transaction Date |
|
| Date at which the current action is performed |
Local Time Zone |
|
| Local Timezone in which the current action is performed |
Selected Language |
|
|
Optional - General
Name | Tag | Format | Usage |
---|
Output Parameters
Always Present - General
Name | Tag | Format | Usage |
---|---|---|---|
Transaction Result |
|
| Identification of final transaction result |
Authorised Amount |
|
| Final Authorised Amount |
Transaction Reference |
| Unique transaction reference. Used to identify a transaction in subsequent transactions Ex: For cancellation or completion | |
PAN Masked Merchant |
|
| Transaction PAN, masked according to configuration for merchant receipt |
PAN Masked Cardholder |
|
| Transaction PAN, masked according to configuration for cardholder receipt |
Payment Brand |
|
| Identified Payment Brand |
Selected Technology |
|
| Selected technology for current transaction. |
Application Preferred Name |
|
| Application Preferred Name that the cardholder can identify (or the default scheme name if not present) |
Present for online approved transaction
Name | Tag | Format | Usage |
---|---|---|---|
Authorisation Code |
|
| Value generated by the authorisation authority for an approved |
Present for EMV Transaction
Name | Tag | Format | Usage |
---|---|---|---|
Application AID |
|
| Final Application AID selected to do the EMV transation |
TVR |
|
| Terminval Verification Results |
TSI |
|
| Transaction Status Information |
CVM Result |
|
| Result of the cardholder verification method |