...

Cylic functions have been split into multiple operations in order to allow fine tuning of the expected behaviour and to allow transmission of completions on a separate thread if required.

Each functions Functions all have the same signature: byte[] functionNamefn(byte[] tlvConfigData, byte[] tlvRequestData)

All byte[] are binary TLV TreeBoth arguments and return type are raw tlv trees.

The expected tlvRequestData tree and the return TLV tree will be is documented here for each function.

The tlvConfigData is documented here : Arkos Configuration

...


doGetCyclicActions	Retrieves a list of currently due actions, according to standard rules This includes due Reconciliations, and pending Completions
doGetPendingTransactions	Retrieves a list of currently uncompleted transactions, ignoring retry rules. This is intended for “last tries”, or retrieving a list of problematic transactions before a closeBatch operation
doPrepareCompletionMessage	Prepare a Completion message for a given uncompleted transaction
doParseCompletionResponse	Process the result of an external transmission attempt of a Completion
doReconciliation	Execute a reconciliation exchange with the given acquirer(s)
doCloseBatch	Closes the batch for the given acquirer(s). This operation is destructive - in most cases, it is recommended to try to transmit Pending transactions first, and log, save or print the remaining uncompleted transactions
doGetTrxInfo	Retrieves the available transaction data for the given Transaction Reference. The amount of information available depends on the context and state of the transaction
doDiagnostic	Executes a Diagnostic exchange with the given acquirer(s)
doGetTotals	Retrieves every transaction from the lot without executing a reconciliation.

API Functions Definition

Anchor

	doGetPendingTransactions
	doGetPendingTransactions

...

This function is used to get the currently pending transactions for which the completion is still required to be sent.

Data Parameters

...

Name

...

Tag

...

Format

...

the provided acquirer(s).

Info
This does not take any completion-related configuration fields into consideration directly. This means for example that uncompleted transactions that ran out of retry attempts will still be returned by this call. This is intended.

Data Parameters

Name	Tag	Format	Usage
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
AcquirerNumber	`DF1B`	`n; 2` Ex : [01], [03] AcquirerNumber, as defined in the configuration.	List of wanted acquirer numbers.

...

This function is used to get all tasks that are scheduled nowdue now for the given acquirer(s). This can include completions Completions to send and reconciliation Reconciliations to do.

...

Name

...

Tag

...

Format

...

Usage

...

Info
This does take into account completion-related configuration fields to determine what Actions are required. For example, transactions that have exhausted their Retry count will not generated a Completion Action.

Name	Tag	Format	Usage
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
AcquirerNumber	`DF1B`	`n; 2` Ex : [01], [03] AcquirerNumber, as defined in the configuration.	List of wanted acquirer numbers.

...

doPrepareCompletionMessage

Use to prepare acquirer messsage to send for completion with the required host acquirer informationa Completion acquirer message that the application can then send at it’s leisure.

Data Parameters

Name	Tag	Format	Usage
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
Reference Data	`DF37`	`ASCII; var` Ex : [01], [03] `TRX000001`	Reference of the transaction to produce the completion message. Previously sent in the Transaction ID response of either doGetCylicActions or doGetPendingTransactions function return.

...

Name

Tag

Format

Usage

External Message

DF9F14

ASCII, var

Message to send

Reference Data

DF37

ASCII, ; var

Ex : TRX000001

Echo of the reference sent in the parameters

Status

DF9F34

Expand

title	Possible Values

00: STATUS_OK

01: STATUS_NOK

Status of the message creation

Host Identification

...

doParseCompletionResponse

Use to parse a received completion Completion response and process the transaction accordingly.

Data Parameters

Name

Tag

Format

Usage

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

Reference Data

DF37

ASCII; var

Ex : [01], [03]

Reference of the transaction to produce the completion message.

Previously sent in the Transaction ID response of either doGetCylicActions or doGetPendingTransactions or doPrepareCompletionMessage function return

Status

DF9F34

Expand

title	Possible Values

00: STATUS_OK

01: STATUS_NOK

19: STATUS_UNABLE_TO_GO_ONLINE

Status of the transmission

External Message

DF9F14

ASCII, var

Message Received

...

This function is used to close the current acquirer reconciliation period. It deletes all transaction from specified acquirers.

Warning
This action is destructive and final. Any necessary precaution should be taken prior to calling this method to ensure no transaction data is lost by mistake.

Data Parameters

Name	Tag	Format	Usage
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
AcquirerNumber	`DF1B`	`n; 2` Ex : [01], [03] AcquirerNumber, as defined in the configuration.	List of wanted acquirer numbers.

...

Anchor
doReconciliation
doReconciliation

doReconciliation

This function is used to send the reconciliation message for each specified acquirerexecute a Reconciliation exchange with the given acquirer(s). This is a blocking function that will return after trying to do each required Reconciliation action(s).

Data Parameters

Name	Tag	Format	Usage
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
AcquirerNumber	`DF1B`	`n; 2` Ex : [01], [03] AcquirerNumber, as defined in the configuration.	List of wanted acquirer numbers.

...

Name

Tag

Format

Usage

Updated Configuration

FF02

DO

Container for Updated Configuration. This should be used as the new active configuration.

Cyclic Function Results

FFBF3C

DO

Container for the results

Cyclic Action Occurrence

FFBF3C.FF01

DO

Container for the data of one reconciliation result

Cyclic Action Type

FFBF3C.FF01. DF01

Expand

title	Possible Values

01: Acquirer Reconciliation

Define action that was done

Cyclic Action ID

FFBF3C.FF01. DF03

n; 2

Ex : [01], [03]

AcquirerNumber, as defined in the configuration.

Acquirer number of the closed reconciliation

Cyclic Reconciliation ID

FFBF3C.FF01. DF06

i32

Value between 1 and 999999

Reconciliation Period Identification assigned by the POI

Cyclic Action Status

FFBF3C.FF01. DF02

Expand

title	Possible Values

00: Approved

01: Declined

02: Unable to connect

04: Error

Result of the reconciliation

Reconciliation Totals

FFBF3C.FF01. FF05

DO

Container for totals

Reconciliation Total Group

FFBF3C.FF01. FF05.FF01

DO

Container for totals, includes a total for all schemes, and totals by schemes

For all subsequent totals, all will contain the following two tags

Totals Count

DF9F25

i32

Number of transaction for that category

Total Amount

D5

BCD, 6

Total amount for that category

Reconcilation Totals Debit

FFBF3C.FF01. FF05.FF01. FF9F26

DO

Container for debit totals

Reconcilation Totals Debit Reverse

FFBF3C.FF01. FF05.FF01.FF9F27

DO

Container for debit reverse totals

Reconcilation Totals Credit

FFBF3C.FF01. FF05.FF01.FF9F28

DO

Container for credit totals

Reconcilation Totals Credit Reverse

FFBF3C.FF01. FF05.FF01.FF9F29

DO

Container for credit reverse totals

Reconcilation Totals Declined

FFBF3C.FF01. FF05.FF01.FF9F2A

DO

Container for declined totals

Reconcilation Totals Failed

FFBF3C.FF01. FF05.FF01.FF9F2B

DO

Container for failed totals

Reconcilation Acquirer Totals DebitReservations

FFBF3C.FF01. FF05. FF9F2CFF01.FF9F24

DO

Container for Pre-Auths and Update Pre-Auths totals

Reconcilation Acquirer Totals Debit

FFBF3C.FF01. FF05.FF01.FF9F2C

DO

Container for debit totals from acquirer’s response

Reconcilation Acqurier Totals Debit Reverse

FFBF3C.FF01. FF05.FF01.FF9F2D

DO

Container for debit reverse totals from acquirer’s response

Reconcilation Acquirer Totals Credit

FFBF3C.FF01. FF05.FF01.FF9F2E

DO

Container for credit totals from acquirer’s response

Reconcilation Acquirer Totals Credit Reverse

FFBF3C.FF01. FF05.FF01.FF9F2F

DO

Container for credit reverse totals from acquirer’s response

Reconcilation Acquirer Totals Declined

FFBF3C.FF01. FF05.FF01.FF9F30

DO

Container for declined totals from acquirer’s response

Reconcilation Acquirer Totals Failed

FFBF3C.FF01. FF05.FF01.FF9F31

DO

Container for failed totals from acquirer’s response

...

Code Block

breakoutMode	full-width

- FFBF3C
  - FF01
      - DF01 : 01
      - DF02 : 00
      - DF03 : 01      
   - FF05  - DF06 : 5
 - FF9F26    - FF01:
   - DF9F25 : 42  - FF05
     - D5 : 00 00 00 04 20- 00FF9F26
      - FF9F27         - DF9F25 : 142
        - D5      - D5 : 00 00 00 0004 1020 00
      - FF9F28     - FF9F27
  - DF9F25 : 3         - D5DF9F25 : 001
00 00 00 13 37       - FF9F29  - D5 : 00 00 00 00 -10 DF9F2500
: 1         - D5 :- 00FF9F28
00 00 00 10 00       - FF9F2A  - DF9F25 : 3
   - DF9F25 : 6         - D5 : 00 00 00 66 00 0013 37
     - FF9F2B      - FF9F29
 -  DF9F25 : 1         - D5DF9F25 : 001
80 00 00 00 00       - FF9F2C  - D5 : 00 00 00 00 -10 DF9F2500
: 42         - D5 :- 00 00FF9F2A
00 04 20 00       - FF9F2D   - DF9F25 : 6
  - DF9F25 : 1         - D5 : 00 00 00 66 00 10 00
      - FF9F2E     - FF9F2B
  - DF9F25 : 3         - D5DF9F25 : 001
00 00 00 13 37       - FF9F2F  - D5 : 00 80 00 00 -00 DF9F2500
: 1         - D5 :- 00FF9F2C
00 00 00 10 00       - FF9F30  - DF9F25 : 42
   - DF9F25 : 6         - D5 : 00 00 00 04 6620 00
   00         - FF9F31FF9F2D
              - DF9F25 : 1
              - D5 : 00 8000 00 00 10 00 00

AnchordoGetTrxInfodoGetTrxInfodoGetTrxInfo

Use to get transaction information. This can be used to reprint a transaction or to print list of pending transactions.

Data Parameters

...

Name

...

Tag

...

Format

...

Usage

...

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

...

Reference Data

...

DF37

...

ASCII; var

Ex : [01], [03]

...

Reference of the transaction to produce the completion message.

Previously sent in the Transaction ID response of either doGetCylicActions or doGetPendingTransactions function return.

Output parameters

...

Name

...

Tag

...

Format

...

Usage

...

Transaction Context

...

FFC107

...

ASCII, var

...

Persisted data for this transaction

...

Reference Data

...

DF37

...

ASCII, var

...

Echo of the reference sent in the parameters

...

Status

...

DF9F34

...

Expand

title	Possible Values

00: STATUS_OK

01: STATUS_NOK

...

Status of the message creation

Exemple Output TLV Tree

Code Block

breakoutMode	full-width

- FFC107 : {...}
- DF37 : "TRX001"
- DF9F34 : 00

...

This function is used to trigger a diagnostic request for the specified acquirer

Data Parameters

...

Name

...

Tag

...

Format

...

Usage

...

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

...

AcquirerNumber

...

DF1B

...

n; 2

Ex : [01], [03]

AcquirerNumber, as defined in the configuration.

...

List of wanted acquirer numbers.

Output Parameters

...

Name

...

Tag

...

Format

...

Usage

...

Cyclic Function Results

...

FFBF3C

...

DO

...

Container for the results

...

Cyclic Action Occurrence

...

FFBF3C.FF01

...

DO

...

Container for the data of one result

...

Cyclic Action Type

...

FFBF3C.FF01. DF01

...

Expand

title	Possible Values

04: Diagnostic

...

Define action that was done

...

Cyclic Action ID

...

FFBF3C.FF01. DF03

...

n; 2

Ex : [01], [03]

AcquirerNumber, as defined in the configuration.

...

Acquirer number of the diagnostic result

...

Cyclic Action Status

...

FFBF3C.FF01. DF02

...

Expand

title	Possible Values

02: Unable to connect

03: Done

04: Error

...

Result of the diagnostic

Exemple Output TLV Tree

Code Block

breakoutMode	full-width

- FFBF3C
  - FF01
      - DF01 : 00
      - DF02 : 03
      - DF03 : 01
            - FF9F2E
              - DF9F25 : 3
              - D5 : 00 00 00 00 13 37
            - FF9F2F
              - DF9F25 : 1
              - D5 : 00 00 00 00 10 00
            - FF9F30
              - DF9F25 : 6
              - D5 : 00 00 00 66 00 00
            - FF9F31
              - DF9F25 : 1
              - D5 : 00 80 00 00 00 00

Anchor

	doGetTrxInfo
	doGetTrxInfo

doGetTrxInfo

Use to retrieve transactional data from a previous Transaction. The amount of data available may change depending on the transaction state.

Data Parameters

Name	Tag	Format	Usage
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
Reference Data	`DF37`	`ASCII; var` Ex : [01], [03]	Reference of the transaction to produce the completion message. Previously sent in the Transaction ID response of either doGetCylicActions or doGetPendingTransactions function return.

Output parameters

Name

Tag

Format

Usage

Transaction Context

FFC107

ASCII, var

Persisted data for this transaction

Reference Data

DF37

ASCII, var

Echo of the reference sent in the parameters

Status

DF9F34

Expand

title	Possible Values

00: STATUS_OK

01: STATUS_NOK

Status of the message creation

Exemple Output TLV Tree

Code Block

breakoutMode	full-width

- FFC107 : {...}
- DF37 : "TRX001"
- DF9F34 : 00

Anchor
doDiagnostic
doDiagnostic

doDiagnostic

This function is used to execute a Diagnostic exchange for the specified acquirer(s)

Data Parameters

Name	Tag	Format	Usage
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
AcquirerNumber	`DF1B`	`n; 2` Ex : [01], [03] AcquirerNumber, as defined in the configuration.	List of wanted acquirer numbers.

Output Parameters

Name

Tag

Format

Usage

Cyclic Function Results

FFBF3C

DO

Container for the results

Cyclic Action Occurrence

FFBF3C.FF01

DO

Container for the data of one result

Cyclic Action Type

FFBF3C.FF01. DF01

Expand

title	Possible Values

04: Diagnostic

Define action that was done

Cyclic Action ID

FFBF3C.FF01. DF03

n; 2

Ex : [01], [03]

AcquirerNumber, as defined in the configuration.

Acquirer number of the diagnostic result

Cyclic Action Status

FFBF3C.FF01. DF02

Expand

title	Possible Values

02: Unable to connect

03: Done

04: Error

Result of the diagnostic

Example Output TLV Tree

Code Block

breakoutMode	full-width

- FFBF3C
  - FF01
      - DF01 : 00
      - DF02 : 03
      - DF03 : 01
      
  - FF01
      - DF01 : 01
      - DF02 : 03
      - DF03 : 02

Anchor

	doGetTotals
	doGetTotals

doGetTotals

Retrieves every transaction from the lot without executing a reconciliation.

Data Parameters

Name

Tag

Format

Usage

AcquirerNumber

DF1B

n; 2

Ex : [01], [03]

AcquirerNumber, as defined in the configuration.

List of wanted acquirer numbers.

Output Parameters

Name

Tag

Format

Usage

Cyclic Function Results

FFBF3C

DO

Container for the results

Cyclic Action Occurrence

FFBF3C.FF01

DO

Container for the data of one result

Cyclic Action Type

FFBF3C.FF01. DF01

Expand

title	Possible Values

05: Get Totals

Define action that was done

Reconciliation Totals

FFBF3C.FF01. FF05

DO

Container for totals

Reconciliation Total Group

FFBF3C.FF01. FF05.FF01

DO

Container for totals, includes a total for all schemes, and totals by schemes

For all subsequent totals, all will contain the following two tags

Totals Count

DF9F25

i32

Number of transaction for that category

Total Amount

D5

BCD, 6

Total amount for that category

Reconcilation Totals Debit

FFBF3C.FF01. FF05.FF01. FF9F26

DO

Container for debit totals

Reconcilation Totals Debit Reverse

FFBF3C.FF01. FF05.FF01.FF9F27

DO

Container for debit reverse totals

Reconcilation Totals Credit

FFBF3C.FF01. FF05.FF01.FF9F28

DO

Container for credit totals

Reconcilation Totals Credit Reverse

FFBF3C.FF01. FF05.FF01.FF9F29

DO

Container for credit reverse totals

Reconcilation Totals Declined

FFBF3C.FF01. FF05.FF01.FF9F2A

DO

Container for declined totals

Reconcilation Totals Failed

FFBF3C.FF01. FF05.FF01.FF9F2B

DO

Container for failed totals

Reconcilation Totals Reservations

FFBF3C.FF01. FF05.FF01.FF9F24

DO

Container for Pre-Auths and Update Pre-Auths totals

Example Output TLV Tree

Code Block

breakoutMode	full-width

    [ 0xFFBF3C: 
        [ 0xFF01: 
            [ 0xDF01: 01
            , 0xFF05: 
                  [ 0xFF01: 
                    [ 0xFF9F26: 
                      [ 0xDF9F25: 00000002
                      , 0xD5: 000000001100
                      ]
                  , 0xFF9F27: 
                      [ 0xDF9F25: 00000000
                      , 0xD5: 000000000000
                      ]
                  , 0xFF9F28: 
                      [ 0xDF9F25: 00000000
                      , 0xD5: 000000000000
                      ]
                  , 0xFF9F29: 
                      [ 0xDF9F25: 00000000
                      , 0xD5: 000000000000
                      ]
                  , 0xFF9F2A: 
                      [ 0xDF9F25: 00000000
                      , 0xD5: 000000000000
                      ]
                  , 0xFF9F2B: 
                      [ 0xDF9F25: 00000000
                      , 0xD5: 000000000000
                      ]
                  , 0xFF9F24: 
                      [ 0xDF9F25: 00000000
                      , 0xD5: 000000000000
                      ]
                  ]
         - FF01      ] - DF01
: 01       - DF02 : 03 ]
     - DF03 : 02]

Versions Compared

Old Version 14

New Version Current

Key

API Functions Definition

Data Parameters

Data Parameters

Data Parameters

Data Parameters

Data Parameters

Anchor
doReconciliation
doReconciliation

doReconciliation

Data Parameters

Data Parameters

Exemple Output TLV Tree

Data Parameters

Output Parameters

Exemple Output TLV Tree

Data Parameters

Exemple Output TLV Tree

Anchor
doDiagnostic
doDiagnostic

doDiagnostic

Data Parameters

Output Parameters

Example Output TLV Tree

doGetTotals

Data Parameters

Output Parameters

Example Output TLV Tree

Page Comparison

Versions Compared

Old Version 14

New Version Current

Key

API Functions Definition

Data Parameters

Data Parameters

Data Parameters

Data Parameters

Data Parameters

AnchordoReconciliationdoReconciliationdoReconciliation

Data Parameters

Data Parameters

Exemple Output TLV Tree

Data Parameters

Output Parameters

Exemple Output TLV Tree

Data Parameters

Exemple Output TLV Tree

AnchordoDiagnosticdoDiagnosticdoDiagnostic

Data Parameters

Output Parameters

Example Output TLV Tree

doGetTotals

Data Parameters

Output Parameters

Example Output TLV Tree

Anchor
doReconciliation
doReconciliation

doReconciliation

Anchor
doDiagnostic
doDiagnostic

doDiagnostic