1. Verify by TransferId

You can make a GET request to the VerifyTransferAPI /api/v1/transfers/verify/{transferId} endpoint using the transfer ID to check the status of your transfer.

Verb	URL
GET	{{baseUrl}}/api/v1/transfers/verify/{transferId}

Sample Request to verify transfer:

curl --request GET \
     --url https://api.sandbox.getanchor.co/api/v1/transfers/verify/169529343584418-anc_trsf \
     --header 'accept: application/json' \
     --header 'x-anchor-key: <API Key>'

{
  "data": {
    "id": "169529343584418-anc_trsf",
    "type": "NIP_TRANSFER",
    "attributes": {
      "createdAt": "2023-09-21T10:50:36",
      "reference": "trxnrtynhgs",
      "reason": "Test Transfer",
      "amount": 5000,
      "currency": "NGN",
      "status": "COMPLETED"
    },
    "relationships": {
      "counterParty": {
        "data": {
          "id": "16942577770351-anc_cp",
          "type": "CounterParty"
        }
      },
      "account": {
        "data": {
          "id": "16922123768364-anc_acc",
          "type": "DepositAccount"
        }
      },
      "customer": {
        "data": {
          "id": "16922123736510-anc_bus_cst",
          "type": "BusinessCustomer"
        }
      }
    }
  }
}

2. Verify by Reference

Get status of a transfer using your customerReference. This is especially useful after a network timeout or unclear response, to confirm whether the transfer was received by Anchor before retrying. This helps prevent duplicate transactions.

Verb	URL
GET	{{baseUr}/api/v1/transfers/by-reference/:customer-reference

curl --location 'https://api.getanchor.co/api/v1/transfers/by-reference/trxnrtynhgs' \ 
--header 'accept: application/json' \ 
--header 'x-anchor-key: <API Key>'

{
  "data": {
    "id": "169529343584418-anc_trsf",
    "type": "NIP_TRANSFER",
    "attributes": {
      "createdAt": "2023-09-21T10:50:36",
      "reference": "trxnrtynhgs",
      "reason": "Test Transfer",
      "amount": 5000,
      "currency": "NGN",
      "status": "COMPLETED"
    },
    "relationships": {
      "counterParty": {
        "data": {
          "id": "16942577770351-anc_cp",
          "type": "CounterParty"
        }
      },
      "account": {
        "data": {
          "id": "16922123768364-anc_acc",
          "type": "DepositAccount"
        }
      },
      "customer": {
        "data": {
          "id": "16922123736510-anc_bus_cst",
          "type": "BusinessCustomer"
        }
      }
    }
  }
}

Transfer States

Transfers have the following states:

State	Description
`pending`	Pending represents the initial status of a transfer as soon as it is initiated. It serves as a temporary state that typically updates to "Successful" within seconds, or in certain instances, it may update to "Failed.”
`completed`	Completed indicates that a transfer was successful without any issues. The majority of transfers achieve this status within seconds.
`failed`	A transfer marked as "Failed" signifies that it has not been completed due to various factors. Possible reasons include issues with the recipient's account, recipient's bank account not reachable or errors during the transfer process.
`reversed`	This indicates the status of a transfer that was initially successful but had to be reversed and returned to the sending account balance. due to its inability to be processed in the recipient's bank account.

When a transfer is in pending state, you can call the verify transfer endpoint, if we have sent the request to the provider for processing, this endpoint will query the provider for the status and update the transfer with that status. If the transfer hasn't been sent, it will return as pending.

📘
When you initiate a transfer, it may take a few seconds or minutes to complete processing. For this reason, we strongly recommend listening to webhook events to receive real-time status updates.

Transfer Failure Reasons

Reason	Description	Solution / Recommendation
`ACCOUNT_FROZEN`	Transaction initiated from an account that is frozen on Anchor.	Unfreeze the account, then retry or use another active account.
`ACCOUNT_NAME_MISMATCH`	The provider (not Anchor) rejected the transfer because the beneficiary name does not match what the bank expects.	Re-validate account name or update counterparty then retry.
`BENEFICIARY_BANK _NOT_AVAILABLE`	Beneficiary bank is unavailable (downtime or connectivity timeout).	Retry failed transfer.
`INSUFFICIENT_BALANCE`	The originating account balance is less than the transaction amount.	Fund the originating account so balance covers the transaction (and fees), then retry.
`INSUFFICIENT_BALANCE _IN_MASTER_ACCOUNT`	Master account balance cannot cover configured transaction fees.	Fund the master account, then retry.
`INVALID_ACCOUNT`	Beneficiary account is invalid, cannot receive the amount, or is dormant.	Request the recipient to confirm account details/status with their bank, then retry
`TRANSFER_LIMIT_EXCEEDED`	The transaction exceeds the source account’s per-transaction or daily transfer limit.	Send to different account, reduce the amount or wait for the limit to reset.
`PROVIDER_ERROR`	The transfer failed at the provider level (e.g beneficiary bank timeout, NIBSS timeout).	Retry the transfer at a later time. If it keeps failing, contact Anchor support.

Transfer related Webhook Events

Below are transfer related webhook events:

Webhook Event	Description
nip.transfer.initiated	Generated when Nip Transfer is initiated.
nip.transfer.successful	Generated when Nip Transfer is successful.
nip.transfer.failed	Generated when Nip Transfer fails.
book.transfer.initiated	This event is generated when a Book Transfer is initiated.
book.transfer.successful	Generated when Book Transfer is successful.
book.transfer.failed	This is generated when a Book Transfer fails.