Reversal

Create a Post endpoint on your application using the path /reversal, we will send a request to this endpoint whenever a debit that has occurred on the wallet needs to be undone.

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

Auth and MAC Generation

Response Code

Additional Fields

Terminal Type

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 reverse an amount on	True
amount	Long	The amount to be reversed (in minor)	True
transactionReference	String	The transaction reference of this transaction	True
originalTransactionReference	String	The transaction reference of the transaction to reverse	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	False
terminalType	String	A 2-digit string that defines the type of terminal.	False
merchantId	String	The merchant that accepted the card	False
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	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, originalTransactionReference, 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
originalTransactionReference	String	The original transaction 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 the reversal 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 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": "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 LANG",
    "rrn" : "000111000111",
    "stan" : "000018",
    "additionalFields=
        {
            "processingCode":"000000",
            "merchantType":"8850"
} }

Response

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

Invalid mac

Request

{
    "requestId": "1",
    "walletId": "1234567894",
    "amount": 1000,
    "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": 1000,
    "responseCode": "12",
    "transactionReference": "11123456789",
    "originalTransactionReference": "11123456789",
    "requestId": "1",
    "mac": "hexdigest"
}

Original transaction not found

Request

{
    "requestId": "1",
    "walletId": "1234567894",
    "amount": 1000,
    "transactionReference": "11123456789",
    "originalTransactionReference": "11123456700",
    "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": 1000,
  "responseCode": "05",
  "transactionReference": "11123456789",
  "originalTransactionReference": "11123456700",
  "requestId": "1",
  "mac": "hexdigest"
}

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

Successful

Invalid mac

Original transaction not found

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