Create a Post endpoint on your application using the path /debit, we will send a request to this endpoint whenever a debit is to be done on the wallet. This debit can be for any kind, of goods & services, withdrawal, etc.

📘

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 debitTrue
amountLongThe amount to be debited is minor. i.eTrue
transactionReferenceStringThe reference that can be used to retrieve any transactionTrue
macStringThe hash included in every request is used to make sure the request is from the actual source it should be 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 in which they occur, generating an HMAC using the shared private key, and getting the hex string of the result.

transactionReference, requestId rrn stan walletId 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 in 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 debit transactions are provided for three specific scenarios. It's essential to highlight that the only variation among these scenarios is the response code. If there are other situations not covered in the sample requests, you can refer to the response code table to determine the appropriate response code to use. This ensures that you have guidance on response codes for all potential scenarios, even if not explicitly mentioned in the provided sample requests.

Successful

Request

{
    "requestId": "1",
    "walletId": "1234567894",
    "amount": 100,
    "transactionReference": "11123456789",
    "originalTransactionReference": "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": "1",
  "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"
}

Response

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

Insufficient funds

Request

{
  "requestId": "1",
  "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"
}

Response

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