Note |
---|
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
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 currently pending transactions for 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. |
Output Parameters
Name | Tag | Format | Usage |
---|---|---|---|
Cyclic Function Results |
|
| Container for the results |
Cyclic Pending Transactions Occurrence |
|
| Container for the data of one pending transaction |
Transaction ID |
|
| Transaction ID of the transaction with pending completion |
AcquirerNumber |
|
Ex : [01], [03] AcquirerNumber, as defined in the configuration. | AcquirerNumber of the transaction with pending completion |
Exemple Output TLV Tree
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 due now for the given acquirer(s). This can include Completions to send and Reconciliations to do.
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. |
Output Parameters
Name | Tag | Format | Usage | |||||
---|---|---|---|---|---|---|---|---|
Cyclic Function Results |
|
| Container for the results | |||||
Cyclic Pending Action Occurrence |
| DO | Container for the data of one pending reconciliation | |||||
Cyclic Pending Action Type |
|
| Define action do be done | |||||
Cyclic Pending Action ID |
|
Ex : [01], [03] AcquirerNumber, as defined in the configuration. | Acquirer number of the reconciliation to be performed | |||||
Cyclic Pending Transactions Occurrence |
|
| Container for the data of one pending transaction | |||||
Transaction ID |
|
| Transaction ID of the transaction with pending completion | |||||
AcquirerNumber |
|
Ex : [01], [03] AcquirerNumber, as defined in the configuration. | AcquirerNumber of the transaction with pending completion |
Exemple Output TLV Tree
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 a 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 : | 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 | |||||
---|---|---|---|---|---|---|---|---|
External Message |
|
| Message to send | |||||
Reference Data |
|
Ex : | Echo of the reference sent in the parameters | |||||
Status |
|
| Status of the message creation | |||||
Host Identification | ||||||||
Exemple Output TLV Tree
Code Block | ||
---|---|---|
| ||
- DF9F14 : "</xml>...."
- DF37 : "TRX001"
- DF9F34 : 00 |
Anchor | ||||
---|---|---|---|---|
|
doParseCompletionResponse
Use to parse a received 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 |
Output parameters
Name | Tag | Format | Usage | |||||
---|---|---|---|---|---|---|---|---|
Status |
|
| 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
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. |
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 closed reconciliation | |||||
Cyclic Action Status |
|
| Result of the closing of the period |
Exemple Output TLV Tree
Code Block | ||
---|---|---|
| ||
- FFBF3C
- FF01
- DF01 : 00
- DF02 : 03
- DF03 : 01
- FF01
- DF01 : 01
- DF02 : 03
- DF03 : 02 |
Anchor | ||||
---|---|---|---|---|
|
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 |
---|---|---|---|
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 | |||||
Reconciliation ID |
|
Value between 1 and 999999 | 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 Totals Reservations |
|
| 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 |
Exemple Output TLV Tree
Code Block | ||
---|---|---|
| ||
- FFBF3C
- FF01
- DF01 : 01
- DF02 : 00
- DF03 : 01
- DF06 : 5
- FF01:
- FF05
- FF9F26
- DF9F25 : 42
- D5 : 00 00 00 04 20 00
- FF9F27
- DF9F25 : 1
- D5 : 00 00 00 00 10 00
- FF9F28
- DF9F25 : 3
- D5 : 00 00 00 00 13 37
- FF9F29
- DF9F25 : 1
- D5 : 00 00 00 00 10 00
- FF9F2A
- DF9F25 : 6
- D5 : 00 00 00 66 00 00
- FF9F2B
- DF9F25 : 1
- D5 : 00 80 00 00 00 00
- FF9F2C
- DF9F25 : 42
- D5 : 00 00 00 04 20 00
- FF9F2D
- DF9F25 : 1
- D5 : 00 00 00 00 10 00
- 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
]
]
]
]
] |