Introduction to Generic Accounting Interface
In the payment landscape, payment processing is a complex process, where booking is just one of the steps. The Temenos Payments Hub (TPH) orchestrates the payment execution. The account status check, funds reservation and booking can take place at different stages of payment processing.
TPH uses the internal Temenos Transact Deposit Demand Account interface to check the account status, reserve funds and raise bookings in an embedded manner. However, when a bank implements a third party payment system, these APIs must be invoked from that system or an ESB, and possibly from other solutions implemented by the bank like online channels, cards interfaces, and so on.
Depending on their enterprise architecture, banks can have multiple systems or interfaces to invoke the APIs for:
- Checking if a transaction can be applied on an account (cover request).
- Reserving funds on an account (reservation request).
- Booking an entry or entries on an account (booking request).
Temenos Generic Accounting Interface (GAI), also known as OFS clearing, accepts cover, reservation and booking requests sent by other banks’ systems to Temenos Transact.
Depending on the type of processing, a synchronous and/or asynchronous response(s) is sent by the GAI. Then, this response is forwarded by the Enterprise Service Bus (ESB) back to the request source system to take a decision on the payment processing.
The request messages are received through queues in the Temenos OFS Clearing proprietary format. The formatting to the Temenos request format, from the Temenos response format and routing are done in ESB.
The GENERIC.ACCOUNTING.REQUEST application allows the user to manually reverse a transaction that is successfully posted through GAI. This creates a booking reversal request, which is processed using the GAI mechanism.
Product Configuration
The main processing rules related to Generic Accounting Interface (GAI) messages are described in the AC.ENTRY.PARAM application and cover the following:
- System ID associated with the bookings
- Message layout – the header and the data items provided in the message
- Entry and fields separator
- Default transaction codes
- Contra-related options
- Accounting mode for exceptions handling
- Additional validations
- Duplicate check rule
- Suspense details
- Fund Transfer (FT) transaction type used in suspense posting
- Response options
System ID
A record must be created in the EB.SYSTEM.ID application for the System id indicated in AC.ENTRY.PARAM, AC.INWARD.ENTRY.
This appears in the accounting entries raised by GAI (populated in the STMTAdd Detail Value field associated with the Add Detail Name PARENT.TXN.SYS.ID in STMT.ENTRY) and indicates that the entries have been generated through GAI.
Message Layout
The layout of the user-defined part of the message can have a header ( multiple types of header can be accepted, up to nine) and one or multiple entries.
Record Type
Defines the type of entry described in the HEAD – Header and DATA – entry type section.
In the CSMBATCH mode, the HEAD accepts and validates the header message. The header entry is stored in the AC.INWARD.ENTRY table.
In the CSM or CSMBULK mode, this is used to accept an external reference, which is associated with the request message and stored in the in the entries raised on the contra account. No header record is created in AC.INWARD.ENTRY for these type of messages.
Record Id
Describes the format of the header or entry marker (4N in the below example indicates that the entry marker is a four-digit string). If the value supplied as the entry marker does not match this format, the entry is ignored.
Data Item
Allows the bank to define the structure of the header and data sections of the message.
The following values are supported as header Data Item fields (Record Type=HEAD).
| Values in the Data Item field | Description |
|---|---|
| CONTROL TOTAL | Displays the total number of items in the request. If this is provided in the message, it is checked against the number of actual entries in the message. |
| SIGN | When the sign is not supplied in the request, the value in the header is used by default. |
| CURRENCY | When the currency is not supplied in the request, the value in the header is used by default. |
| LOCAL REF |
Supplied at the header level and stored in the AC.INWARD.ENTRY record, which stores the header of the CSMBATCH message.
|
| EXT.BATCH.REF |
The batch reference provided in the batch message (if any) is not only populated in the batch entry in AC.INWARD.ENTRY, but also in the individual ones.
For CSM and CSMBULK, this is populated in the accounting entries raised on the contra account and on the accounts specified in the request message; it will be stored in STMT.ENTRY/CATEG.ENTRY/RE.CONSOL.SPEC.ENTRY, in the ADD.DETAIL.VALUE field associated with the ADD.DETAIL.NAME field, which has the value “EXT.BATCH.REF”. |
The following values are supported as entry Data Item fields (Record Type=DATA).
| Values in the Data Item field | Description |
|---|---|
| ACCOUNT | Indicates a Temenos Transact account or an alternate account number. |
| PL CATEGORY | Indicates a PL category. Either the PL or account number must be supplied. |
| CURRENCY | Indicates the currency of the entry and must match the account, if supplied. The default is account currency or local for P&L entries. |
| VALUE DATE | Indicates the value date allocated to the entry. |
| AMOUNT | Amount of movement in the currency supplied. This must be present and unsigned. |
| AMOUNT.LCY | Unsigned local equivalent of amount. This is optional. |
| EXCH.RATE | Local to foreign exchange to be used. This is optional. |
| SIGN | Indicates the sign for entry amount. It can be +,-, DR, CR, D and C or the value in TXN.CODE is used to determine the sign. |
| TXN.CODE | Indicates the transaction code to be used for posting the entry. When sign is not supplied for entry amount, the DR or CR indicated in transaction code is used to derive the sign of the amount. |
| REVERSAL.MARKER | Indicates if the entry is a reversal of a previous entry (R – reversal, blank – normal entry). |
| THEIR.REF | The reference of the entry known to the account holder. |
| OUR.REF | The bank’s reference to the transaction. |
| TRANS.REFERENCE | The reference allocated to the transaction. If the bank has an external transaction reference allocated to the entry, it is passed here. Reversal request must send this reference to indicate this is a reversal request. |
| PRODUCT.CATEGORY | Indicates the product category for P&L entries. |
| ACCOUNT.OFFICER | Indicates the account officer for P&L entries. |
| CUSTOMER.ID | Indicates the CUSTOMER.ID for P&L entries. |
| DEPARTMENT | Indicates the DEPARTMENT code for P&L entries. |
| NARRATIVE | Indicates the entry narrative. If more than 35 characters, it is split into multiple entries each of 35 characters. |
| EXPOSURE.DATE | Indicates the exposure date for credit items. |
| LOCAL.REF |
Specifies a user-defined field that can be passed here and then passed into the accounting entries raised through direct accounting (AC and AA contracts).
The local references can be passed into the accounting entries raised on AD and AL through soft mapping. |
| ADD.DETAIL.REQUEST.SOURCE | Indicates the source that initiated the request. Is passed in the accounting entries raised for the entry (in the ADD.DETAIL.VALUE field associated with the ADD.DETAIL.NAME field, which has the value ”REQUEST.SOURCE”). |
| RESERVATION.KEY | Indicates the reservation key. In a reservation request, this is stored as the Alternate Reservation ID associated with the reservation. In a booking request, this indicates the funds reservation ID (AC.LOCKED.EVENTS), which must be released as part of the booking. |
| RESERVE.EXPIRY.DATE | Indicates the expiry date for the reservation request. |
| DUPLICATE.CHECK | Indicates the duplicate check criteria record that must be applied to detect the duplicates. |
| CONTRA.CATEG | Indicates the contra account to be used for the request message (ACCOUNT or ACCOUNT.CLASS are allowed) |
| EXTERNAL.TXN.INF |
Indicates the presence of extended transaction information.
The details are received as a string in OFS format and indicates the pairs of field names and field values in the EXTERNAL.SEPA.DETAILS application.
|
| CONTRA.TXN.CODE | Allows the bank to provide the transaction code that must be populated in the Contra Entry field. This is used only when Contra Entry is set to Entry. |
| INT.BOOK.REQ.ID |
Must be present when reversal requests are initiated through GENERIC.ACCOUNTING.REQUEST.
It is used to send the appropriate GENERIC.ACCOUNTING.REQUEST based on which the request message is generated (for example, if a reversal request is initiated).
|
| JOURNAL.ID | The unique identifier of the incremental authorisation |
| UPDATE.MODE | Indicates the type of update to be performed on the locked amount when the update reservation request is processed. The valid options are:
If the UPDATE.MODE is not ADD, SUBTRACT, SET or NULL, then the OFS Clearing message is rejected with a failed response of ’Invalid Update Mode’. |
| PARTIAL.BOOKING | Identifies if a reservation is flagged as a partial payment for booking. The allowed values are YES, NO or null. |
| AMOUNT.TOLERANCE | Indicates the percentage used in the best match functionality. This overrides the default specified in AC.ENTRY.PARAM. |
| REQUEST.CODE |
Used when the reservation requests are suspended and a record is created in the It is populated in the Request Code field in the Read Transaction Recycler User Guide for more information. The data item is optional, if not supplied in the reservation request, it is populated with a fixed value, ‘ReserveSuspense’. |
| REQUEST.TYPE.SUB.TYPE |
Used when the reservation requests are suspended and a record is created in It is populated in the Request Type Sub Type field in the Read Transaction Recycler User Guide for more information. The data item is optional. |
| CUT.OFF.DATE |
Used when the reservation requests are suspended and a record is created in It is populated in the Cut Off Date field in Read Transaction Recycler User Guide for more information. This data item is optional. |
| CUT.OFF.TIME |
Used when the reservation requests are suspended and a record is created in the It is populated in the Cut Off Time field in the Read Transaction Recycler User Guide for more information. This data item is optional. |
| ACCOUNTING.DATE | The accounting date supplied in the GAI request. Indicates that it is an adjustment entry to update the current and applicable open PC Period. |
| DEALER.DESK | Indicates the DEALER.DESK for the entry when the currency conversion is involved. |
Entry and Field Separators
The default entry delimiter is ‘_’ and the default field delimiter is ‘,’. In some markets or regions, these characters are included in the allowed character set and are used by customers when making payments. So, the banks must provide a different character than the default one.
The values can be specified in the Entry Delimiter and Field Delim fields in AC.ENTRY.PARAM. The characters used as delimiters are ` ! @ # $ % & * ( ) _ - + = [ ] { } ; < > / \ |
Default Transaction Codes
The Dr Txn Code and Cr Txn Code fields indicate the default transaction codes that are used if transaction code is not supplied in the request entry.
Contra-related Setup
This setup applies only to booking requests. The Contra Entry field refers to how Temenos Transact balances the entries provided in the request. The supported values are detailed in the following table.
| Values in the Contra Entry field | Description |
|---|---|
| ENTRY | The balancing entry is raised for each entry indicated in the request. |
| CURRENCY.NET | Balance by currency, netting debit and credit entries, irrespective of the value date. If the entries that are part of an online posting message are netting for each currency to zero, a balancing entry is not raised. |
| CURRENCY | Balance by currency and sign, irrespective of the value date. A consolidated entry is created for all debit/credit entries, per each currency. |
| CCY.VAL.NET | Balance by value date and currency, irrespective of sign netting debits and credits. If the entries that are part of an online posting message are netting to zero per currency and per value date, a balancing entry is not raised. |
| CURRENCY.VAL.NET | Balance by currency, sign and value date. A consolidated entry is created for all debit/ credit entries, per each currency, sign and value date. |
| LOCAL | To raise balancing entries in the local currency irrespective of request currency. Balancing happens by value date, processing date, accounting date, and netting the debit and credit entries irrespective of sign. |
| CCY.PROC.NET | To allow balancing using currency, processing date, and netting debit and credit entries irrespective of sign. |
When contra account or contra category is not supplied in the request and GAI determines that balancing entry(ies) must be raised, the contra account on which the balancing entry(ies) must be raised is determined based on the parameterisation in AC.ENTRY.PARAM. GAI determines the contra account from the Contra Acct Categ field (parameterisation using account class) or the Contra Currency and Contra Acc fields (the bank can define different contras per each currency) defined in AC.ENTRY.PARAM.
The transaction codes used in the balancing entry are determined from the Contra Dr Txn Code field or the Contra Cr Txn Code field in AC.ENTRY.PARAM, depending on the sign of the contra.
AC.ENTRY.PARAM. If this is not supplied, the Contra Dr Txn Code or Contra Cr Txn Code defined in AC.ENTRY.PARAM are used, as explained above.Accounting Modes, Exception Handling and Reporting
The accounting mode impacts the processing in case of exceptions.
| Accounting Mode | In case of Error During Processing | In case of Override During Processing | No Error or Override During Processing |
|---|---|---|---|
| SAO | Posted to suspense account | Posted to target account or PL | Posted to target account or PL |
| SSS | Posted to suspense account | Posted to suspense account | Posted to target account or PL |
| SNP | No posting - rejected (Read Note | No posting –- rejected | Posted to target account or PL |
- The accounting mode impacts the processing only after the entry has passed the technical validations.
- Account is not found – Even if the accounting mode is SNP, the entry is posted to suspense.
- The SNP mode is also known as ‘Book If Okay’ and SAO or SSS are referred as ‘Force booking’ modes.
As mentioned above, in case of errors for SAO or errors and overrides for SSS, the system posts the entry to the suspense account and not on the account indicated in the request. The suspense account to be used is determined from the Susp Class Cr or Susp Class Dr field in AC.ENTRY.PARAM. As an exception, a FT can also be raised where the transaction type is defined in the Ft Type field.
- In the SNP mode the entry processing stops when the first error/override is found.
- In SAO/SSS mode all overrides/errors will be reported.
Updating Report File
For CSM, CSMBULK and CSMBATCH, it is mandatory to be set as unique and implies that a record is created and stored for each entry in AC.INWARD.ENTRY.
Reply Options
The following type of responses are supported by GAI:
- Detail – Synchronous response, it returns the result and the type ID of the entry.
- Summary – Synchronous response, it returns the result only.
- ExtDetail – Asynchronous response through Integration Framework, it returns all the details available in the entry.
- ExtBatch – Asynchronous response through Integration Framework, it returns all the header details.
Contingent Accounts
In AC.ENTRY.PARAM, the Interface Type field is set to Internal.
Business Events
When the Emit Business Event field in MS.PARAMETER is set as ‘Yes’, the business events representing the state change are emitted.
The following business events are emitted for Generic Accounting Interface tables.
| Business Event | Description |
|---|---|
| settlementService.checkFunds.fundAvailable | Event for a cover request when sufficient funds are available in the account |
| settlementService.checkFunds.fundNotAvailable | Event for a cover request when sufficient funds are not available in the account |
| settlementService.creditRequest.accountCredited | Event for a book request when the account is credited successfully |
| settlementService.creditRequest.creditFailed | Event for a book request when credit transaction to an account fails |
| settlementService.creditRequest.creditSubmittedForRetry | Event for a book request when credit transaction to an account submitted for a retry |
| settlementService.creditRequest.creditSuspended | Event for a book request when credit transaction to an account gets suspended |
| settlementService.debitRequest.accountDebited | Event for a book request when the account is debited successfully |
| settlementService.debitRequest.debitFailed | Event for a book request when debit transaction to an account fails |
| settlementService.debitRequest.debitSubmittedForRetry | Event for a book request when debit transaction to an account submitted for a retry |
| settlementService.debitRequest.debitSuspended | Event for a book request when debit transaction to an account gets suspended |
| settlementService.reserveRequest.fundReserved | Event for a reserve request when the funds are reserved successfully |
| settlementService.reserveRequest.reserveFundFailed | Event for a reserve request when the funds reserve fails |
| settlementService.transactionRetry.fundRecovered | Event for a transaction retry when the funds are recovered successfully |
| settlementService.transactionRetry.fundReserved | Event for a transaction retry when the funds are reserved successfully |
Illustrating Model Parameters
This section covers the high-level specifications required for Generic Accounting Interface.
In this topic