Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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

Code Block
breakoutModefull-width
// 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

CE

u8; 1

Expand
titlePossible Values

FF: None

07

01: Payment

06

02: Refund

05

03: Cancellation
04: Preauth

03

05: Update Preauth

02

06: Payment Completion

01

07: Cash Advance

00

08: Deferred Payment

08

09: Deferred Payment Completion

12

10: Voice Authorisation

09

11: Cardholder Detection

10

12: Card Validity Check

11

13: No Show

14: Original Credit

15: Quasicash

Identification of the payment service requested

Transaction Amount

D5

BCD; 12
fixed exponent (2)

Amount of the transaction

Authorised Amount

9F02

BCD; 12
fixed exponent (2)

Transaction Amount Before Adjustment

DFFF47

BCD; 12
fixed exponent (2)

Transaction Time

9F21

BCD; 6
HMS, two nibbles per element
Ex: [0x16, 0x17, 0x27] (16:17:27)

Time at which the current action is performed

Transaction Date

9A

BCD; 6
YMD, two nibbles per element
Ex: [0x20, 0x08, 0x16] (2020-aug-16)

Date at which the current action is performed

Local Time Zone

DF9F3F

i8; 2
Hour and minute offset, one byte each
Ex: [-5, 0]

Local Timezone in which the current action is performed

Selected Language

CD

ASCII; 2
Ex: "en"

Optional - General

Name

Tag

Format

Usage

Transaction Channel

0xDFBF60

u8; 1

Expand
titlePossible Values

00: None
01: Mail
02: Telephone
03: eCommerce
04: Television Payment
05: Secured Electronic Commerce
06: Mobile Payment
07: Mobile POS

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

D2

u8; 1

Expand
titlePossible Values

99: None
00: Approved
01: Declined
02: Aborted
03: Voice Authorisation
04: Payment Part Only
05: Partially Approved

Identification of final transaction result

Authorised Amount

9F02

BCD; 12
fixed exponent (2)

Final Authorised Amount

Transaction Reference

ASCII; var
Ex: "010009287351.00000030"

Unique transaction reference. Used to identify a transaction in subsequent transactions

Ex: For cancellation or completion

PAN Masked Merchant

0xDFFF49

ACII; var

Transaction PAN, masked according to configuration for merchant receipt

PAN Masked Cardholder

0xDFFF48

ASCII; var

Transaction PAN, masked according to configuration for cardholder receipt

Payment Brand

0xDF32

ASCII; var
Ex : “VISA”

Identified Payment Brand

Selected Technology

D0

u8; 1

Expand
titlePossible Values

00: None
01: EMV Chip
02: Magstripe
03: Manual Entry
04: Non EMV Chip
05: Fallback
06: Contactless Card

Selected technology for current transaction.

Application Preferred Name

0xC0

ASCII; var
Ex : “VISA Desjardins”

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

89

ASCII; 6

Value generated by the authorisation authority for an approved
transaction. Also known as a Approval Code

Present for EMV Transaction

Name

Tag

Format

Usage

Application AID

0x9F06

u8; 5-16

Final Application AID selected to do the EMV transation

TVR

0x95

u8; 5

Terminval Verification Results

TSI

0x9F06

u8; 2

Transaction Status Information

CVM Result

0x9F34

u8; 3

Result of the cardholder verification method