These API are only available starting API V1.2

Description

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.

Functions all have the same signature: byte[] fn(byte[] tlvConfigData, byte[] tlvRequestData)

Both arguments and return type are raw tlv trees.

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

The tlvConfigData is documented here : Arkos Configuration

Overview


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

doGetPendingTransactions

This function is used to get currently pending transactions for the provided acquirer(s).

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

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

Name	Tag	Format	Usage
Cyclic Function Results	`FFBF3C`	`DO`	Container for the results
Cyclic Pending Transactions Occurrence	`FFBF3C.FF02`	`DO`	Container for the data of one pending transaction
Transaction ID	`FFBF3C.FF02. DF01`	`ASCII; var`	Transaction ID of the transaction with pending completion
AcquirerNumber	`FFBF3C.FF02. DF1B`	`n; 2` Ex : [01], [03] AcquirerNumber, as defined in the configuration.	AcquirerNumber of the transaction with pending completion

Exemple Output TLV Tree

- FFBF3C
  - FF02
      - DF01 : "TRX001"
      - DF1B : 01
  - FF02
      - DF01 : "TRX002"
      - DF1B : 01
  - FF02
      - DF01 : "TRX003"
      - DF1B : 02

doGetCylicActions

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

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

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

Name	Tag	Format	Usage
Cyclic Function Results	`FFBF3C`	`DO`	Container for the results
Cyclic Pending Action Occurrence	`FFBF3C.FF01`	DO	Container for the data of one pending reconciliation
Cyclic Pending Action Type	`FFBF3C.FF01. DF01`	`01`: Acquirer Reconciliation	Define action do be done
Cyclic Pending Action ID	`FFBF3C.FF01. DF03`	`n; 2` Ex : [01], [03] AcquirerNumber, as defined in the configuration.	Acquirer number of the reconciliation to be performed
Cyclic Pending Transactions Occurrence	`FFBF3C.FF02`	`DO`	Container for the data of one pending transaction
Transaction ID	`FFBF3C.FF02. DF01`	`ASCII; var`	Transaction ID of the transaction with pending completion
AcquirerNumber	`FFBF3C.FF02. DF1B`	`n; 2` Ex : [01], [03] AcquirerNumber, as defined in the configuration.	AcquirerNumber of the transaction with pending completion

Exemple Output TLV Tree

- FFBF3C
  - FF02
      - DF01 : "TRX001"
      - DF1B : 01
  - FF02
      - DF01 : "TRX002"
      - DF1B : 01
  - FF02
      - DF01 : "TRX003"
      - DF1B : 02

  - FF01
      - DF01 : 01
      - DF03 : 01
      
  - FF01
      - DF01 : 01
      - DF03 : 02

doPrepareCompletionMessage

Use to prepare a Completion acquirer message that the application can then send at it’s leisure.

Data Parameters

Name	Tag	Format	Usage

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 : `TRX000001`	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

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`	`00`: STATUS_OK `01`: STATUS_NOK	Status of the message creation
Host Identification

Exemple Output TLV Tree

- DF9F14 : "</xml>...."
- DF37 : "TRX001"
- DF9F34 : 00

doParseCompletionResponse

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

Data Parameters

Name	Tag	Format	Usage

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`	`00`: STATUS_OK `01`: STATUS_NOK `19`: STATUS_UNABLE_TO_GO_ONLINE	Status of the transmission
External Message	`DF9F14`	`ASCII, var`	Message Received

Output parameters

Name	Tag	Format	Usage

Name

Tag

Format

Usage

Status

DF9F34

00: STATUS_OK

01: STATUS_NOK

19: STATUS_UNABLE_TO_GO_ONLINE

Status of the message parsing.

If a response was received, you will received OK/NOK according to the parsing.

Else it will be an echo.

Exemple Output TLV Tree

doCloseBatch

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

Data Parameters

Name	Tag	Format	Usage

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

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`	`00`: Close Business Day	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 Action Status	`FFBF3C.FF01. DF02`		Result of the closing of the period

Exemple Output TLV Tree

doReconciliation

This function is used to execute 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

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

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`		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
Reconciliation ID	`FFBF3C.FF01. DF06`	`i32` Value between 1 and 999999	Reconciliation Period Identification assigned by the POI
Cyclic Action Status	`FFBF3C.FF01. DF02`		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 Totals Reservations	`FFBF3C.FF01. FF05.FF01.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

Exemple Output TLV Tree

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

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

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`		Status of the message creation

Exemple Output TLV Tree

doDiagnostic

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

Data Parameters

Name	Tag	Format	Usage

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

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`		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`		Result of the diagnostic

Example Output TLV Tree

doGetTotals

Retrieves every transaction from the lot without executing a reconciliation.

Data Parameters

Name	Tag	Format	Usage

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

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`		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

Amadis Developer's Guide

Amadis

Cyclic functions

Description

Overview

API Functions Definition

doGetPendingTransactions

Data Parameters

Output Parameters

Exemple Output TLV Tree

doGetCylicActions

Output Parameters

Exemple Output TLV Tree

Data Parameters

Exemple Output TLV Tree

Data Parameters

Exemple Output TLV Tree

doCloseBatch

Data Parameters

Output Parameters

Exemple Output TLV Tree

doReconciliation

Data Parameters

Output Parameters

Exemple Output TLV Tree

Data Parameters

Exemple Output TLV Tree

doDiagnostic

Data Parameters

Output Parameters

Example Output TLV Tree

doGetTotals

Data Parameters

Output Parameters

Example Output TLV Tree