post
https://api.sandbox.safehavenmfb.com/transfers/status
Please provide either the sessionId or the paymentReference.
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
How to read this response
- The top-level
statusCodeis200whenever the transfer record is found, even if the transfer failed. Usedata.statusanddata.isReversedto decide the outcome. Do not usestatusCodefor this.responseCodeandmessagerepeat the NIBSS response stored on the transfer.- If an outbound NIBSS transfer is still in progress, this call may first check its status with NIBSS. The returned status can therefore change between calls.
Request
POST https://api.sandbox.safehavenmfb.com/transfers/status
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer {access_token}. This is the OAuth2 client credentials access token, as on the other endpoints. |
ClientID | Yes | Your client ID, as on the other endpoints. |
Body parameters
Send one of the following fields.
| Field | Type | Description |
|---|---|---|
sessionId | string | NIBSS session ID of the transfer. |
paymentReference | string | Your own reference for the transfer. |
{
"sessionId": "090286241112103045123456789012"
}
{
"paymentReference": "PAY-REF-0001"
}
Response fields
| Field | Type | Description |
|---|---|---|
statusCode | number | 200 when the transfer record is found, even if the transfer failed. 400 when no record is found. |
responseCode | string | NIBSS response code stored on the transfer. |
message | string | NIBSS response message stored on the transfer. |
data._id | string | ID of the transfer record. |
data.client | string | Client ID. Returned as an ID, not a full object. |
data.account | string | Account ID. Returned as an ID, not a full object. |
data.type | string | Transfer type, for example Outwards. |
data.sessionId | string | NIBSS session ID of the transfer. |
data.nameEnquiryReference | string | Name enquiry reference for the transfer. |
data.paymentReference | string | Your own reference for the transfer. |
data.status | string | Outcome of the transfer. See Status values below. |
data.isReversed | boolean | true only when funds were returned to the sender. On Failed transfers this is false or missing. |
data.reversalReference | string or null | Reference of the reversal. This can be null even on reversed transfers. Match the reversal credit to the transfer using the original sessionId. |
data.creditAccountName | string | Beneficiary account name. |
data.creditAccountNumber | string | Beneficiary account number. |
data.debitAccountName | string | Sender account name. |
data.debitAccountNumber | string | Sender account number. |
data.narration | string | Transfer narration. |
data.amount | number | Transfer amount. |
data.fees | number | Fees charged on the transfer. |
data.vat | number | VAT charged on the transfer. |
data.stampDuty | number | Stamp duty charged on the transfer. |
data.responseCode | string | NIBSS response code. |
data.responseMessage | string | NIBSS response message. |
data.createdAt | string | Time the transfer was created (ISO 8601). |
data.updatedAt | string | Time the transfer was last updated (ISO 8601). |
Other fields on the transfer record are shown in the response examples below.
Status values
data.status | Meaning |
|---|---|
Created | Transfer accepted. The final result is not yet known. |
Processing | Still being confirmed with NIBSS. |
Completed | Transfer successful. |
Failed | Transfer failed and the customer's account was not debited, so no reversal is needed. isReversed is false or missing. |
Reversed | The customer's account was debited, the transfer then failed, and the amount plus fees, VAT and stamp duty was credited back. isReversed is true. |
Response codes
responseCode can be any NIBSS code. Common failure codes:
| Code | Message |
|---|---|
51 | No sufficient funds |
61 | Transfer limit Exceeded |
91 | Beneficiary Bank not available |
96 | System malfunction |
97 | Timeout waiting for response from destination |
Handling failed vs reversed transfers
Failed: no refund is needed. The customer was never debited.Reversed: the funds are already back in the customer's account. Use the originalsessionIdto match the reversal credit, becausereversalReferencemay benull.Created/Processing: the result is not final yet. The status can change on a later call.- Do not retry a transfer with the same
paymentReference.
Response examples
Failed transfer
{
"statusCode": 200,
"responseCode": "91",
"message": "Beneficiary Bank not available",
"data": {
"_id": "6731f2a9c4e1b2a7d8f01234",
"client": "64f0c1a2b3c4d5e6f7a8b9c0",
"account": "64f0c1a2b3c4d5e6f7a8b9c1",
"type": "Outwards",
"sessionId": "090286241112103045123456789012",
"nameEnquiryReference": "090286241112103012987654321098",
"paymentReference": "PAY-REF-0001",
"isReversed": false,
"provider": "NIBSS",
"providerChannel": "TRANSFER",
"providerChannelCode": "IBS",
"destinationInstitutionCode": "000013",
"creditAccountName": "JOHN DOE",
"creditAccountNumber": "0000000000",
"creditBankVerificationNumber": "22200000000",
"creditKYCLevel": "3",
"debitAccountName": "ACME LTD",
"debitAccountNumber": "0000000000",
"debitBankVerificationNumber": "22200000000",
"debitKYCLevel": "3",
"transactionLocation": "9.0932,7.4429",
"narration": "Invoice 1023",
"amount": 50000,
"fees": 10,
"vat": 0.75,
"stampDuty": 50,
"responseCode": "91",
"responseMessage": "Beneficiary Bank not available",
"status": "Failed",
"queued": false,
"limitExceeded": false,
"isDeleted": false,
"createdAt": "2026-11-12T10:30:45.123Z",
"updatedAt": "2026-11-12T10:31:20.456Z"
}
}
Reversed transfer
{
"statusCode": 200,
"responseCode": "96",
"message": "System malfunction",
"data": {
"_id": "6731f2a9c4e1b2a7d8f05678",
"client": "64f0c1a2b3c4d5e6f7a8b9c0",
"account": "64f0c1a2b3c4d5e6f7a8b9c1",
"type": "Outwards",
"sessionId": "090286241112104512123456789099",
"nameEnquiryReference": "090286241112104455987654321011",
"paymentReference": "PAY-REF-0002",
"isReversed": true,
"reversalReference": null,
"provider": "NIBSS",
"providerChannel": "TRANSFER",
"providerChannelCode": "IBS",
"destinationInstitutionCode": "000013",
"creditAccountName": "JOHN DOE",
"creditAccountNumber": "0000000000",
"debitAccountName": "ACME LTD",
"debitAccountNumber": "0000000000",
"narration": "Invoice 1024",
"amount": 50000,
"fees": 10,
"vat": 0.75,
"stampDuty": 50,
"responseCode": "96",
"responseMessage": "System malfunction",
"status": "Reversed",
"queued": false,
"limitExceeded": false,
"isDeleted": false,
"createdAt": "2026-11-12T10:45:12.000Z",
"updatedAt": "2026-11-12T10:52:03.000Z"
}
}
Transfer not found / no sessionId or paymentReference sent
{
"statusCode": 400,
"responseCode": "25",
"message": "Unable to locate record"
}
The final result is in data.status, not in the top-level statusCode: a failed or reversed transfer still returns "statusCode": 200. data.responseCode and data.responseMessage give the NIBSS reason.
data.status | Meaning | Money |
|---|---|---|
Completed | Successful. | Debited. |
Created / Processing | Not final yet. Check again later. | On hold. |
Failed | Failed. | Sender was not debited. |
Reversed | Failed after debit. isReversed is true. | Amount and fees credited back. |