Debit
Request - POST /debit
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
| Attribute | Type | Description | Required |
|---|---|---|---|
| requestId | String | A unique ID for every request sent across. Very necessary for the mac | True |
| walletId | String | The wallet ID of the wallet to debit | True |
| amount | Long | The amount to be debited is minor. i.e | True |
| transactionReference | String | The reference that can be used to retrieve any transaction | True |
| mac | String | The 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 with | True |
| transactionDateTime | LocalDateTime | This is the date and time the transaction occurred | False |
| terminalId | String | This is an identifier for the terminal the transaction came from | True |
| terminalType | String | A 2-digit string that defines the type of terminal. | True |
| merchantId | String | The merchant that accepted the card | True |
| acquiringInstitutionId | String | An ID to identify the institution that acquired the transaction | False |
| currencyCode | String | A code that identifies the currency the transaction was done on | True |
| cardAcceptorNameLocation | String | The name and location of the card acceptor | True |
| rrn | String | This is the Retrieval Ref Number | True |
| stan | String | This is the System Trace Audit Number | True |
| transactionFee | Long | The transaction fee in minor | True |
| additionalFields | Map | Any other Iso field needed by a fintech | False |
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
| Attribute | Type | Description | Required |
|---|---|---|---|
| requestId | String | The request Id that came with the request. | True |
| responseCode | String | The code that signifies the status of the operation. | True |
| amount | Long | The amount that came with the request. | True |
| transactionReference | String | The reference that came with the request | True |
| mac | String | The 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 with | True |
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"
}
Updated 28 days ago