Transfer Status

Please provide either the sessionId or the paymentReference.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

📘

How to read this response

  • The top-level statusCode is 200 whenever the transfer record is found, even if the transfer failed. Use data.status and data.isReversed to decide the outcome. Do not use statusCode for this.
  • responseCode and message repeat 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

HeaderRequiredDescription
AuthorizationYesBearer {access_token}. This is the OAuth2 client credentials access token, as on the other endpoints.
ClientIDYesYour client ID, as on the other endpoints.

Body parameters

Send one of the following fields.

FieldTypeDescription
sessionIdstringNIBSS session ID of the transfer.
paymentReferencestringYour own reference for the transfer.
{
  "sessionId": "090286241112103045123456789012"
}
{
  "paymentReference": "PAY-REF-0001"
}

Response fields

FieldTypeDescription
statusCodenumber200 when the transfer record is found, even if the transfer failed. 400 when no record is found.
responseCodestringNIBSS response code stored on the transfer.
messagestringNIBSS response message stored on the transfer.
data._idstringID of the transfer record.
data.clientstringClient ID. Returned as an ID, not a full object.
data.accountstringAccount ID. Returned as an ID, not a full object.
data.typestringTransfer type, for example Outwards.
data.sessionIdstringNIBSS session ID of the transfer.
data.nameEnquiryReferencestringName enquiry reference for the transfer.
data.paymentReferencestringYour own reference for the transfer.
data.statusstringOutcome of the transfer. See Status values below.
data.isReversedbooleantrue only when funds were returned to the sender. On Failed transfers this is false or missing.
data.reversalReferencestring or nullReference of the reversal. This can be null even on reversed transfers. Match the reversal credit to the transfer using the original sessionId.
data.creditAccountNamestringBeneficiary account name.
data.creditAccountNumberstringBeneficiary account number.
data.debitAccountNamestringSender account name.
data.debitAccountNumberstringSender account number.
data.narrationstringTransfer narration.
data.amountnumberTransfer amount.
data.feesnumberFees charged on the transfer.
data.vatnumberVAT charged on the transfer.
data.stampDutynumberStamp duty charged on the transfer.
data.responseCodestringNIBSS response code.
data.responseMessagestringNIBSS response message.
data.createdAtstringTime the transfer was created (ISO 8601).
data.updatedAtstringTime the transfer was last updated (ISO 8601).

Other fields on the transfer record are shown in the response examples below.

Status values

data.statusMeaning
CreatedTransfer accepted. The final result is not yet known.
ProcessingStill being confirmed with NIBSS.
CompletedTransfer successful.
FailedTransfer failed and the customer's account was not debited, so no reversal is needed. isReversed is false or missing.
ReversedThe 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:

CodeMessage
51No sufficient funds
61Transfer limit Exceeded
91Beneficiary Bank not available
96System malfunction
97Timeout 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 original sessionId to match the reversal credit, because reversalReference may be null.
  • 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.statusMeaningMoney
CompletedSuccessful.Debited.
Created / ProcessingNot final yet. Check again later.On hold.
FailedFailed.Sender was not debited.
ReversedFailed after debit. isReversed is true.Amount and fees credited back.
Body Params
string

Specifies the sessionId for the transaction. This parameter must be included when the paymentReference is not passed.

string

Specifies the paymentReference for the transaction. This parameter must be included when the sessionId is not passed.

Headers
string
required

Your ibs_client_id, returned by Exchange Client Credentials.

Responses

Language
Credentials
OAuth2
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json