The fintech API processor is a web service that is responsible for communicating with the various fintechs. This service holds configurations as to how to reach the several fintech institutions, these configurations have information as to the different APIs the fintechs have exposed for the sake of transaction processing. At the moment, the APIs include; debit(Single and Dual messaging), enquiry and reversal.
This document will discuss the fintech API processor in the following headings:
- 1.0 Authentication/Security
- 2.0 Transaction Flow
- 3.0 Transaction Type
- 4.0 Response Codes
- 5.0 Transaction Reference Number
- 6.0 Transaction Amount
- 7.0 Terminal Type
- 8.0 AdditionalFields
- 9.0 Validating the created endpoints
1.0 Authentication/Security
As part of the configurations, a unique private key is also decided on by ISW and the fintech. This unique private key is a very important part of this transaction because it will be used to generate a message authentication code (MAC) for every transaction sent to/from the fintech, this MAC is a hash of some parameters in the transaction and the parameters used differ by the transaction type (more details on this in the API specification section). This principle is used to sign every request and response that will be sent and both the fintech and ISW will compulsorily validate that this MAC is valid before honoring any transaction. If in any case this MAC is not valid, the transaction should be treated as not authentic and a response returned accordingly). The MAC is sent as part of the parameters for all the requests and responses, the fintech will validate this MAC by generating the same MAC on their end using the shared private key and the parameters used in generating this MAC for the said transaction type. Once this MAC matches the MAC that came with the transaction, the transaction should be treated as authentic.
The type of MAC used here is a hash-based message authentication code (HMAC). HMAC uses secure hash algorithm(SHA) internally to achieve what it does, this means we will need to select an implementation of this. As such, this project uses the SHA-512 implementation of HMAC (HmacSHA512). This means every request and response is signed by generating a MAC with the shared private key and parameters using HMAC (HmacSHA512 implementation). After the MAC is generated the hex string of the generated MAC should be the value used in the requests/responses.
To validate that you are on track while generating the MAC, you can use an online HMAC generation tool e.g https://www.freeformatter.com/hmac-generator.html and be sure to select SHA512
2.0 Transaction Flow
The transaction flow entails the processes that has been put in place to ensure the integrity of transactions. A request is only seen as complete when a response is received for that request. When no response is received for these requests, it could mean a lot of things; it could be that the request was honored but the response was not received, it could equally be that the request did not arrive at all. However, when this happens, for requests like the debit, enquiry or place lien a reversal will be initiated. But when a response is not received for a reversal or a debit lien, the request will be repeated severally until a response is received. It will be good to note here that the reversal request for the place lien will be sent as a debit lien request with an amount of 0.
Therefore a transaction request (debit, enquiry and place lien requests) will only be sent once for a particular transaction, if no response is received a reversal request for that particular transaction will be sent afterwards. For a reversal or debit lien request, if no response is received, the reversal or debit lien request will continue to be sent till a valid response is received. This means the fintech need to properly handle several reversals/debit lien and make sure to only honor one of same reversal/debit lien request sent severally.
3.0 Transaction Type
The transaction type determines how the transaction should be treated. At the moment, we will only be treating 5 transaction types; DEBIT, ENQUIRY, REVERSALS, PLACE LIEN and DEBIT LIEN.
The fiintechs are expected to implement and expose endpoints for these transaction types.
DEBIT: the debit endpoint will be called whenever a debit is to be done on the wallet. This debit can be of any kind, goods & services, withdrawal etc.
ENQUIRY: the enquiry endpoint will be called whenever an inquiry is to be done on the account. It can be balance enquiry, name enquiry etc
REVERSAL: the reversal endpoint is called whenever a debit that has occurred on the wallet needs to be undone.
PLACE LIEN: the place lien endpoint will be called for the authorization requests of a dual messaging. It should place a lien on the wallet for a particular amount.
DEBIT LIEN: the debit lien endpoint will be called for the completion of the dual messaging. It should debit the lien that has been place.
4.0 Response Codes
The response code is the value that particularly determines the status of the transaction. Since there should always be a response for every request, this response should have a way of telling what the status of the transaction is, this is what the response code does. The response code for this project is limited to the response codes listed below. If any response code is received and is not within the listed response codes, the transaction response is treated as an invalid transaction response regardless of what the status might have been on the fintech. If this happens and the response was for a debit request, a reversal will be sent for that transaction. If the response was for a reversal request, another reversal request will be sent.
The valid response codes are as follows:
| Status | Response Code |
|---|---|
| Successful | 00 |
| Do not honor | 05 |
| Error | 06 |
| Invalid transaction | 12 |
| Invalid amount | 13 |
| Unable to locate record | 25 |
| Function not supported | 40 |
| Lost card, pick-up | 41 |
| Account closed | 45 |
| Not sufficient funds | 51 |
| Exceeds withdrawal limit | 61 |
| Exceeds withdrawal frequency | 65 |
| Not reachable/Issuer or switch inoperative | 91 |
| Duplicate transaction | 94 |
5.0 Transaction Reference Number
The transaction reference is a unique string used to identify every transaction. Every transaction, regardless of the transaction type will have a unique transaction reference. A reversal request will however, have the transaction reference of the original transaction it’s trying to reverse. This original reference number is found only in reversal requests.
The several repeats of the reversal request, will all have a transaction reference which will be same as the first reversal request. This means that when a reversal request for a particular transaction is sent several times, they will all have the same transaction reference.
6.0 Transaction Amount
This is the amount that is sent both in the request and/or in the response. For the purpose of this project the transaction amount will always be in minor. This means that for every request that will be sent and for every response that will be received, the transaction amount is always expected to be in minor.
e.g 100 naira in minor should be 10000. This also applies to transactionFee sent when present
7.0 Terminal Type
The terminal type is a 2 digit character that defines the terminal the transaction originated from. The below table shows what the different values identify.
| Terminal Type | Terminal |
|---|---|
| 00 | Administrative terminal |
| 01 | POS terminal |
| 02 | ATM |
| 03 | Home terminal |
| 04 | Electronic Cash Register (ECR) |
| 05 | Dial terminal |
| 06 | Travellers check machine |
| 07 | Fuel machine |
| 08 | Scrip machine |
| 09 | Coupon machine |
| 10 | Ticket machine |
| 11 | Point-of-Banking terminal |
| 12 | Teller |
| 13 | Franchise teller |
| 14 | Personal banking |
| 15 | Public utility |
| 16 | Vending |
| 17 | Self-service |
| 18 | Authorization |
| 19 | Payment |
| 20 | VRU |
| 21 | Smart phone |
| 22 | Interactive television |
| 23 | Personal digital assistant |
| 24 | Screen phone |
| 25 | Business banking |
| 90 | E-commerce – No encryption; no authentication |
| 91 | E-commerce – SET/3D-Secure encryption; cardholder certificate not used (non-authenticated) |
| 92 | E-commerce – SET/3D-Secure encryption; cardholder certificate used (authenticated) |
| 93 | E-commerce – SET encryption, chip cryptogram used; cardholder certificate not used |
| 94 | E-commerce – SET encryption, chip cryptogram used; cardholder certificate used |
| 95 | E-commerce – Channel encryption (SSL); cardholder certificate not used (non-authenticated) |
| 96 | E-commerce – Channel encryption (SSL); chip cryptogram used, cardholder certificate not used |
8.0 AdditionalFields
Given the needs of each Fintech varies, we have added a feature that allows a fintech to add any number of fields (from the list of allowed fields) to their payload. The additional fields will be sent in an extra field (additionalFields) as key values pair for any configured field provided the field is present in the request ISO message.
| Iso Field | json field name | Iso Field | Json field name | Iso Field | Json Field name | ||
|---|---|---|---|---|---|---|---|
| 3 | processingCode | 57 | authLifeCycle | 127.7 | checkData | ||
| 5 | amountSettle | 66 | settlementCode | 127.8 | retentionData | ||
| 7 | transmissionDateAndTime | 67 | extendedPaymentCode | 127.9 | additionalNodeData | ||
| 9 | conversionRate | 68 | receivingInstCountryCode | 127.12 | terminalOwner | ||
| 12 | timeLocal | 69 | settlementInstCountryCode | 127.13 | posGeographicData | ||
| 13 | dateLocal | 86 | amountCredit | 127.14 | sponsorBank | ||
| 15 | dateSettle | 87 | amountCreditReversal | 127.15 | addressVerificationData | ||
| 16 | dateConverted | 88 | amountDebit | 127.16 | addressVerificationResult | ||
| 17 | draftCapture | 89 | amountDebitReversal | 127.17 | cardholderInfo | ||
| 18 | merchantType | 90 | originalDataElements | 127.19 | bankDetails | ||
| 19 | acquiringCountryCode | 91 | fileUpdateCode | 127.20 | authorizerSettlementDate | ||
| 20 | panExtendedCountryCode | 92 | fileSecurityCode | 127.21 | recordId | ||
| 21 | forwardingInstitutionCode | 93 | responseIndicator | 127.23 | payeeNameAndAddress | ||
| 22 | posEntryMode | 94 | serviceIndicator | 127.24 | payeeReference | ||
| 24 | networkId | 95 | replacementAmounts | 127.26 | originalNode | ||
| 25 | posConditionCode | 97 | amountNetSettle | 127.27 | cardVerificationResult | ||
| 26 | pinCaptureCode | 98 | payee | 127.29 | secure3DData | ||
| 27 | authIdRespLength | 99 | settleInstIdCode | 127.30 | secure3DResult | ||
| 29 | settlementFee | 100 | receivingInstIdCode | 127.31 | issuerNetworkId | ||
| 32 | acquiringInstitutionIdCode | 102 | fromAccount | 127.32 | ucafData | ||
| 33 | forwardingInstitutionIdCode | 103 | toAccount | 127.33 | extendedTranType | ||
| 34 | panExtended | 104 | transactionDescription | ||||
| 40 | serviceRestrictionCode | 118 | paymentNumber | ||||
| 46 | additionalDataIso | 119 | paymentNumberReversal | ||||
| 47 | additionalDataNational | 123 | posDataCode | ||||
| 48 | additionalData | 127.3 | routingInfo | ||||
| 50 | currencyCodeSettlement | 127.4 | posData | ||||
| 54 | additionalAmounts | 127.5 | serviceStationData | ||||
| 56 | messageReasonCode | 127.6 | authProfile |
9.0 Validating the created endpoints
In a bid to make the endpoint validation easier, a postman test collection has been created to permit an automated test and validation of several test cases, you can import this collection from here (https://www.getpostman.com/collections/265e1007c3ad614f060f). Run this collection against the host where the app is deployed and be sure the tests in this collection pass.
Note: The variable for this collection is configured within the collection. So be sure the check the variables within this collection to supply the necessary details.
For the test private key, any random key can be used while the development is ongoing, but the test private key will be shared once the development, validated and the created endpoints shared with the support engineer in ISW (be sure to update the app with this new private key).
It will be important to note that the path of the endpoints to be created should exactly match the path as specified below in the api specification section.