Amadis
doPayment
- Frédéric Béland (Unlicensed)
- Arshad Saidoo (Unlicensed)
- Frédérick Caron (Unlicensed)
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.
Process and Responsibilities
doPayment is a blocking API call. Once requested, this service will run to completion.
Until a result is received, control should be fully ceded to the framework to ensure a valid processing of the operation. During this time, the framework may call any combination of Service callbacks to signal requested operations to the caller. Control should be given back as soon as possible to the framework in these cases - the system should still be considered under control from the framework.
This also applies to external operations like Cancellation operations - once a cancel has been signaled to Arkos, the system should still process any requested service and wait for a completion of the service call. This may include transmits, displays or more.
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");
//Optional, add transaction channel
paymentParams.AddEnum(ArkosTags.TransactionChannel,TransactionChannelID.Mpos);
// 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 |
|---|---|---|---|
Transaction Channel |
|
| This value will be present in nexo acquirer message if present.
Reference ISO20022_MDRPart2_CAPE_caaa_2016_2017_v1, section 2.4.2.2.1.5 TransactionChannel |
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 |