Debit Lien

Create a Post endpoint on your application with the path /lien/debit. This endpoint is crucial for completing dual messaging, specifically for debiting the wallet when a lien is in place. It would be good to note that the amount in the debit lien request can differ from the amount placed on the lien.

This means that there are 3 main cases here and each of these cases is handled differently as explained below ;

  1. Where the debit lien amount is equal to the amount placed on the lien: When the debit lien amount is equal to the amount placed on a lien, then the amount is just debited.
  2. Where the debit lien amount is greater than the amount placed on the lien: In this case, the customer’s total balance (balance + amount placed on the lien) is computed and if this total balance is greater than or equal to the debit lien amount, then the amount is debited and a success response code is returned. But if this total balance is less than the debit lien amount, then an insufficient fund response is returned.
  3. Where the debit lien amount is lesser than the amount placed on the lien: In this case, the debit lien amount is just debited from the placed lien, and the remaining lien amount is returned to the customer’s balance. A special case of this can be when the debit lien amount is 0, this is also very possible and is how the placed lien is reverted. In the case of a 0 amount, the placed lien is removed and the placed lien amount is added back to the customer’s balance.

📘

Make sure to read the following information since you'll probably encounter it in this section

Request

AttributeTypeDescriptionRequired
requestIdStringA unique ID for every request sent across. Very necessary for the macTrue
walletIdStringThe wallet ID of the wallet to debit lien onTrue
amountLongThe actual amount to be debited. The amount can also be 0, in which case the lien is removed and no value is debited.True
transactionReferenceStringThe reference that can be used to retrieve the transaction. The transaction reference is the same as the transaction reference of the request that places the lien.True
macStringThe hash included in every request is used to make sure the request is from the actual source and has not been tampered withTrue
transactionDateTimeLocalDateTimeThis is the date and time the transaction occurredFalse
terminalIdStringThis is an identifier for the terminal the transaction came fromTrue
terminalTypeStringA 2-digit string that defines the type of terminal.True
merchantIdStringThe merchant that accepted the cardTrue
acquiringInstitutionIdStringAn ID to identify the institution that acquired the transactionFalse
currencyCodeStringA code that identifies the currency the transaction was done onTrue
cardAcceptorNameLocationStringThe name and location of the card acceptorTrue
rrnStringThis is the Retrieval Ref NumberTrue
stanStringThis is the System Trace Audit NumberTrue
transactionFeeLongThe transaction fee in minorTrue
additionalFieldsMapAny other Iso field needed by a fintechFalse

Request Mac

The request Mac is generated by concatenating the following attributes in the order which they occur, generating an HMAC using the shared private key, and getting the hex string of the result.

transactionReference, requestId, walletId, rrn, stan, amount, currencyCode

Response attributes

AttributeTypeDescriptionRequired
requestIdStringThe request Id that came with the request.True
responseCodeStringThe code that signifies the status of the operation.True
amountLongThe amount that came with the request.True
transactionReferenceStringThe reference that came with the requestTrue
macStringThe hash included in every response is used to make sure the request is from the actual source it should be and has not been tampered withTrue

Response Mac

The response Mac is generated by concatenating the following attributes in the order which they occur, generating an HMAC using the shared private key, and getting the hex string of the result.

transactionReference, requestId, responseCode

Sample requests

The sample requests for the debit only cover 3 scenarios. It should be noted that the difference between one response and another is just the response code. The response code table in section 4.0 can be used to know the response code that can be used for other scenarios that might not be covered in the sample requests.

Successful

Request

{
    "requestId": "1fds5d6f7g8hijokmojih6f5d",
    "walletId": "1234567894",
    "amount": 100,
    "transactionReference": "11123456789",
    "mac": "hexdigest",
    "transactionDateTime": "2020-05-15T13:32:09",
    "terminalId": "3IWPDVNA",
    "terminalType": "21",
    "merchantId": "WEBPAYDIRECTVNA",
    "acquiringInstitutionId": "428051043",
    "currencyCode": "566",
    "cardAcceptorNameLocation": "MATRIX ENERGY LIMITE   LA
    "rrn" : "000111000111",
    "stan" : "000018",
    "additionalFields=
        {
            "processingCode":"000000",
            "merchantType":"8850"
} }

Response

{
    "amount": 100,
    "responseCode": "00",
    "transactionReference": "11123456789",
    "requestId": "1",
    "mac": "hexdigest"
}

Invalid mac

Request

{
    "requestId": "1fds5d6f7g8hijokmojih6f5d",
    "walletId": "1234567894",
    "amount": 1000,
    "transactionReference": "11123456789",
    "mac": "hexdigest",
    "transactionDateTime": "2020-05-15T13:32:09",
    "terminalId": "3IWPDVNA",
    "terminalType": "21",
    "merchantId": "WEBPAYDIRECTVNA",
    "acquiringInstitutionId": "428051043",
    "currencyCode": "566",
    "cardAcceptorNameLocation": "MATRIX ENERGY LIMITE   LA LANG",
    "rrn" : "000111000111",
    "stan" : "000018",
    "additionalFields=
        {
            "processingCode":"000000",
            "merchantType":"8850"
} }

Response

{
  "amount": 1000,
  "responseCode": "12",
  "transactionReference": "11123456789",
  "requestId": "1",
  "mac": "hexdigest"
}

Insufficient funds

Request

{
    "requestId": "1fds5d6f7g8hijokmojih6f5d",
    "walletId": "1234567894",
    "amount": 1000,
    "transactionReference": "11123456789",
    "mac": "hexdigest",
    "transactionDateTime": "2020-05-15T13:32:09",
    "terminalId": "3IWPDVNA",
    "terminalType": "21",
    "merchantId": "WEBPAYDIRECTVNA",
    "acquiringInstitutionId": "428051043",
    "currencyCode": "566",
    "cardAcceptorNameLocation": "MATRIX ENERGY LIMITE   LA LANG",
    "rrn" : "000111000111",
    "stan" : "000018",
    "additionalFields=
        {
            "processingCode":"000000",
            "merchantType":"8850"
} }

Response

{
    "amount": 1000,
    "responseCode": "51",
    "transactionReference": "11123456789",
    "requestId": "1",
    "mac": "hexdigest"
}