...
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
Overview
Retrieves a list of currently due actions, according to standard rules | |
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 | |
Prepare a Completion message for a given uncompleted transaction | |
Process the result of an external transmission attempt of a Completion | |
Execute a reconciliation exchange with the given acquirer(s) | |
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 | |
Retrieves the available transaction data for the given Transaction Reference. The amount of information available depends on the context and state of the transaction | |
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
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 |
|
| 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 |
AcquirerNumber |
|
Ex : [01], [03] AcquirerNumber, as defined in the configuration. | List of wanted acquirer numbers. |
...
Code Block | ||
---|---|---|
| ||
- FFBF3C - FF02 - DF01 : "TRX001" - DF1B : 01 - FF02 - DF01 : "TRX002" - DF1B : 01 - FF02 - DF01 : "TRX003" - DF1B : 02 |
Anchor | ||||
---|---|---|---|---|
|
doGetCylicActions
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
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 |
|
| 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 |
AcquirerNumber |
|
Ex : [01], [03] AcquirerNumber, as defined in the configuration. | List of wanted acquirer numbers. |
...
Code Block | ||
---|---|---|
| ||
- 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 |
Anchor | ||||
---|---|---|---|---|
|
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 |
|
| 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 |
Reference Data |
|
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. |
...
Name | Tag | Format | Usage | |||||
---|---|---|---|---|---|---|---|---|
External Message |
|
| Message to send | |||||
Reference Data |
|
Ex : | Echo of the reference sent in the parameters | |||||
Status |
|
| Status of the message creation | |||||
Host Identification | ||||||||
...
Code Block | ||
---|---|---|
| ||
- DF9F14 : "</xml>...." - DF37 : "TRX001" - DF9F34 : 00 |
Anchor | ||||
---|---|---|---|---|
|
doParseCompletionResponse
Use to parse a received completion Completion response and process the transaction accordingly.
Data Parameters
Name | Tag | Format | Usage | |||||
---|---|---|---|---|---|---|---|---|
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 | |||||
Reference Data |
|
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 |
|
| Status of the transmission | |||||
External Message |
|
| Message Received |
...
Code Block | ||
---|---|---|
| ||
- DF9F34 : 00 |
Anchor | ||||
---|---|---|---|---|
|
doCloseBatch
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 |
|
| 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 |
AcquirerNumber |
|
Ex : [01], [03] AcquirerNumber, as defined in the configuration. | List of wanted acquirer numbers. |
...
Code Block | ||
---|---|---|
| ||
- FFBF3C - FF01 - DF01 : 00 - DF02 : 03 - DF03 : 01 - FF01 - DF01 : 01 - DF02 : 03 - DF03 : 02 |
Anchor | ||||
---|---|---|---|---|
|
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 |
|
| 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 |
AcquirerNumber |
|
Ex : [01], [03] AcquirerNumber, as defined in the configuration. | List of wanted acquirer numbers. |
Output Parameters
Note |
---|
The output of doReconciliation is split in two top level subtrees. |
Name | Tag | Format | Usage | |||||
---|---|---|---|---|---|---|---|---|
Updated Configuration |
|
| Container for Updated Configuration. This should be used as the new active configuration. | |||||
Cyclic Function Results |
|
| Container for the results | |||||
Cyclic Action Occurrence |
|
| Container for the data of one reconciliation result | |||||
Cyclic Action Type |
|
| Define action that was done | |||||
Cyclic Action ID |
|
Ex : [01], [03] AcquirerNumber, as defined in the configuration. | Acquirer number of the closed reconciliation | |||||
Cyclic Action StatusReconciliation ID |
| Expand | | title | Reconciliation Period Identification assigned by the POI | |||
Cyclic Action Status |
|
| Result of the reconciliation | |||||
Reconciliation Totals |
|
| Container for totals | |||||
Reconciliation Total Group |
|
| 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 |
|
| Number of transaction for that category | |||||
Total Amount |
|
| Total amount for that category | |||||
Reconcilation Totals Debit |
|
| Container for debit totals | |||||
Reconcilation Totals Debit Reverse |
|
| Container for debit reverse totals | |||||
Reconcilation Totals Credit |
|
| Container for credit totals | |||||
Reconcilation Totals Credit Reverse |
|
| Container for credit reverse totals | |||||
Reconcilation Totals Declined |
|
| Container for declined totals | |||||
Reconcilation Totals Failed |
|
| Container for failed totals | |||||
Reconcilation Acquirer Totals DebitReservations |
|
| Container for Pre-Auths and Update Pre-Auths totals | |||||
Reconcilation Acquirer Totals Debit |
|
| Container for debit totals from acquirer’s response | |||||
Reconcilation Acqurier Totals Debit Reverse |
|
| Container for debit reverse totals from acquirer’s response | |||||
Reconcilation Acquirer Totals Credit |
|
| Container for credit totals from acquirer’s response | |||||
Reconcilation Acquirer Totals Credit Reverse |
|
| Container for credit reverse totals from acquirer’s response | |||||
Reconcilation Acquirer Totals Declined |
|
| Container for declined totals from acquirer’s response | |||||
Reconcilation Acquirer Totals Failed |
|
| Container for failed totals from acquirer’s response |
...
Code Block | ||
---|---|---|
| ||
- 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 : 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 DF9F25 :00 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 |
doGetTrxInfo
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 | ||
---|---|---|
| ||
|
...
Status of the message creation
Exemple Output TLV Tree
Code Block | ||
---|---|---|
| ||
- FFC107 : {...}
- DF37 : "TRX001"
- DF9F34 : 00 |
doDiagnostic
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 | ||
---|---|---|
| ||
|
...
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 | ||
---|---|---|
| ||
|
...
Result of the diagnostic
Exemple Output TLV Tree
Code Block | ||
---|---|---|
| ||
- 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
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 |
|
| 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 |
Reference Data |
|
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 |
|
| Persisted data for this transaction | |||||
Reference Data |
|
| Echo of the reference sent in the parameters | |||||
Status |
|
| Status of the message creation | |||||
Exemple Output TLV Tree
Code Block | ||
---|---|---|
| ||
- FFC107 : {...}
- DF37 : "TRX001"
- DF9F34 : 00 |
Anchor | ||||
---|---|---|---|---|
|
doDiagnostic
This function is used to execute a Diagnostic exchange for the specified acquirer(s)
Data Parameters
Name | Tag | Format | Usage |
---|---|---|---|
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 |
AcquirerNumber |
|
Ex : [01], [03] AcquirerNumber, as defined in the configuration. | List of wanted acquirer numbers. |
Output Parameters
Name | Tag | Format | Usage | |||||
---|---|---|---|---|---|---|---|---|
Cyclic Function Results |
|
| Container for the results | |||||
Cyclic Action Occurrence |
| DO | Container for the data of one result | |||||
Cyclic Action Type |
|
| Define action that was done | |||||
Cyclic Action ID |
|
Ex : [01], [03] AcquirerNumber, as defined in the configuration. | Acquirer number of the diagnostic result | |||||
Cyclic Action Status |
|
| Result of the diagnostic |
Example Output TLV Tree
Code Block | ||
---|---|---|
| ||
- FFBF3C
- FF01
- DF01 : 00
- DF02 : 03
- DF03 : 01
- FF01
- DF01 : 01
- DF02 : 03
- DF03 : 02 |
Anchor | ||||
---|---|---|---|---|
|
doGetTotals
Retrieves every transaction from the lot without executing a reconciliation.
Data Parameters
Name | Tag | Format | Usage |
---|---|---|---|
AcquirerNumber |
|
Ex : [01], [03] AcquirerNumber, as defined in the configuration. | List of wanted acquirer numbers. |
Output Parameters
Name | Tag | Format | Usage | |||||
---|---|---|---|---|---|---|---|---|
Cyclic Function Results |
|
| Container for the results | |||||
Cyclic Action Occurrence |
| DO | Container for the data of one result | |||||
Cyclic Action Type |
|
| Define action that was done | |||||
Reconciliation Totals |
|
| Container for totals | |||||
Reconciliation Total Group |
|
| 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 |
|
| Number of transaction for that category | |||||
Total Amount |
|
| Total amount for that category | |||||
Reconcilation Totals Debit |
|
| Container for debit totals | |||||
Reconcilation Totals Debit Reverse |
|
| Container for debit reverse totals | |||||
Reconcilation Totals Credit |
|
| Container for credit totals | |||||
Reconcilation Totals Credit Reverse |
|
| Container for credit reverse totals | |||||
Reconcilation Totals Declined |
|
| Container for declined totals | |||||
Reconcilation Totals Failed |
|
| Container for failed totals | |||||
Reconcilation Totals Reservations |
|
| Container for Pre-Auths and Update Pre-Auths totals |
Example Output TLV Tree
Code Block | ||
---|---|---|
| ||
[ 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] |