HomeAPI Reference
Guides
DashboardBlogTalk to Us

Bank Transfer (NIP Transfer)

Suggest Edits

Anchor provides you with the liberty to send money to bank accounts in Nigeria. To make a bank or NIP transfer, you need to create the recipient as a counterparty.

A counterparty is simply the person or entity you want to transfer money to. Think of it as a saved beneficiary. The recipient's bank account information needs to be created in your system before you can initiate a transfer to them.

You can make a bank transfer in two steps:

  1. Create a CounterParty
  2. Initiate Transfer to the CounterParty

Below is the process diagram to send money to an external bank from Anchor Today.

Bank (NIP) Transfer Flow

Bank (NIP) Transfer Flow

Bank transfer (a.k.a NIP_Transfer) refers to sending money to recipients in other banks.

💡

To send funds to recipients created within your organization free of charge, use the Book Transfer option.

To make a bank transfer, initiate a transfer from your source Anchor account to a counterparty. A counterparty is simply a recipient at the other bank.

👤

If a counterparty exists, make a GET request to the counterparty endpoint /api/v1/counterparties/{counterpartyId} to retrieve the counterparty details: Id and type of the recipient.

Create CounterParty

Create a counterparty when you want to make a bank transfer. However, If you have created this counterparty before, you don’t need to recreate this recipient when you want to make a transfer. Instead, you fetch the details of the counterparty previously created.

Steps to create a counterparty:

  • List banks
  • Verify the account details at the other bank
  • Create counterparty

Step 1: List Banks

Make a GET call to the List BankAPI endpoint to fetch the available banks. You need to know the bank you want to transfer to, you don't need to call it if you save bank code on your system already. You pull it once, but the issue with this approach is that new banks can be added by NIP network and your customer won't see it on their list.

VerbURL
GET{{baseUrl}}/api/v1/banks

Request Payload:

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

{
     "id": "16565854900648-anc_bk",
      "type": "Bank",
      "attributes": {
        "nipCode": "000014",
        "name": "ACCESS BANK"
      }
    },
    {
      "id": "165658549036023-anc_bk",
      "type": "Bank",
      "attributes": {
        "nipCode": "090131",
        "name": "ALLWORKERS MICROFINANCE BANK"
      }
    }
}

Step 2: Verify Account Details

You need to verify the account number and confirm that it’s valid. This is to ensure you don’t send money to the wrong or invalid recipient. You don't need to call this endpoint if you are super sure that the account details are correct (i.e name, account number and bank). However, calling this verify endpoint is for customer experience. If you attempt to create transfer with wrong details it will fail.

VerbGET
URL{{baseUrl}}/api/v1/payments/verify-account/{bankIdOrBankCode}/{accountNumber}

Sample Request Payload:

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

{
  "data": {
    "id": "0",
    "type": "AccountDetail",
    "attributes": {
      "bank": {
        "id": "16565854900648-anc_bk",
        "name": "ACCESS BANK",
        "nipCode": "000014"
      },
      "accountName": "Test Account",
      "accountNumber": "0000000010"
    }
  }
}

📘

You can also verify and create this counterparty with one request by passing verifyName as true as in the create counterparty request

Step 3: Create a CounterParty

With the verification completed, you can pass the customer’s bank details and the recipient type to the Create CounterPartyAPI endpoint. If a counterparty exists, and you try to recreate it, the previously created record/value will be returned.

VerbUrl
POST{{baseUrl}}/api/v1/counterparties

Sample Request to create a counterParty

curl --request POST \
     --url https://api.sandbox.getanchor.co/api/v1/counterparties \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-anchor-key: <API Key>' \
     --data '
{
  "data": {
    "type": "CounterParty",
    "attributes": {
      "bankCode": "000014",
      "accountName": "Ibrahim Adeyemi",
      "accountNumber": "8111111147",
      "verifyName": true
    }
  }
}'

{
    "data": {
        "id": "17012639752430-anc_cp",
        "type": "CounterParty",
        "attributes": {
            "createdAt": "2023-11-29T13:19:35.267546",
            "bank": {
                "id": "16565854900648-anc_bk",
                "name": "ACCESS BANK",
                "nipCode": "000014"
            },
            "accountName": "Ibrahim Adeyemi",
            "accountNumber": "8111111147",
            "updatedAt": "2023-11-29T13:19:35.267546",
            "status": "ACTIVE"
        }
    }
}

📘

You can also verify and create this counterparty with one request by passing verifyName as true as in the create counterparty request.

📘

With verifyName, we do a check with only the account number at the recipient bank and we will create a counterparty with the name that matched the account number at the other bank. So even if you pass a wrong name in the above request, In the response, we will return to you the correct name as it appears in the other bank.

Copy CounterParty Id and type of the Counterparty. Note down the counterparty Id and type as this will be used when initiating a transfer to this recipient. The Counterparty Id is of the format 16942577770351-anc_cp" and the type is CounterParty.

Initiate Transfer to CounterParty

VerbPOST
URL{{baseUrl}}/api/v1/transfers

To send money to a counterparty/recipient, you need to make a POST call to the Initiate TransferAPI endpoint /api/v1/transfers, passing the ID of the Counterparty created previously. Select the source Account (could be DepositAccount or SubAccount) you want to make the transfer from. 

📒

NIP transfer is Option 2 on the documentation

Sample NIP Transfer Request:

curl --location 'https://api.sandbox.getanchor.co/api/v1/transfers' \
--header 'Content-Type: application/json' \
--header 'x-anchor-key: <API Key>'
--data '{
    "data": {
        "type": "NIPTransfer",
        "attributes": {
            "amount": 10000,
            "currency": "NGN",
            "reason": "Sample NIP test transfer",
            "reference": "tthwubtvwt"
        },
        "relationships": {
            "account": {
                "data": {
                    "id": "166012843397415-anc_acc",
                    "type": "DepositAccount"
                }
            },
            "counterParty": {
                "data": {
                    "id": "16942577770351-anc_cp",
                    "type": "CounterParty"
                }
            }
        }
    }
}'

{
    "data": {
        "id": "16942554375340-anc_trsf",
        "type": "NIP_TRANSFER",
        "attributes": {
            "createdAt": "2023-09-09T10:30:37.579566",
            "reason": "Sample NIP test transfer",
            "amount": 10000,
            "currency": "NGN",
            "status": "PENDING"
        },
        "relationships": {
            "counterParty": {
                "data": {
                    "id": "16942577770351-anc_cp",
                    "type": "CounterParty"
                }
            },
            "account": {
                "data": {
                    "id": "166012843397415-anc_acc",
                    "type": "DepositAccount"
                }
            },
            "customer": {
                "data": {
                    "id": "16601284316669-anc_bus_cst",
                    "type": "BusinessCustomer"
                }
            }
        }
    }
}

If your request includes no errors, the response comes back with a pending status, while the transfer is being processed. Test transfers in sandbox always changes to COMPLETED  immediately, because there is no processing involved.

Verify Transfer

VerbURL
GET{{baseUrl}}/api/v1/transfers/verify/{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. 

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.

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",
      "reason": "Test Transfer",
      "amount": 1000,
      "currency": "NGN",
      "status": "COMPLETED"
    },
    "relationships": {
      "counterParty": {
        "data": {
          "id": "16942577770351-anc_cp",
          "type": "CounterParty"
        }
      },
      "account": {
        "data": {
          "id": "16922123768364-anc_acc",
          "type": "DepositAccount"
        }
      },
      "subAccount": {
        "data": {
          "id": "16922609921350-anc_subacc",
          "type": "SubAccount"
        }
      },
      "customer": {
        "data": {
          "id": "16922123736510-anc_bus_cst",
          "type": "BusinessCustomer"
        }
      }
    }
  }
}

Updated 4 months ago