Bank Transfer

Transfers may return a pending status if the payment network does not respond within the timeout window. The transaction is retried automatically and a webhook is dispatched when the final status is known.

List supported banks

GET /transfer/banks Returns all banks currently supported for outward transfers, sorted alphabetically by name.

Request

string

required

Bearer token.

Response

boolean

true on success.

array

Array of bank objects.

Show Bank object

string

Bank sort code. Use this value as sortCode in transfer requests.

string

Human-readable bank name.

Examples

curl "https://api.tagpay.ng/v1/transfer/banks" \
  -H "Authorization: Bearer <token>"

const response = await fetch("https://api.tagpay.ng/v1/transfer/banks", {
  headers: { Authorization: "Bearer <token>" },
});
const { banks } = await response.json();

Response

{
  "status": true,
  "banks": [
    { "code": "000014", "name": "ACCESS BANK" },
    { "code": "000005", "name": "ACCESS BANK (DIAMOND)" },
    { "code": "000010", "name": "ECOBANK" },
    { "code": "000016", "name": "FIRST BANK OF NIGERIA" },
    { "code": "000013", "name": "GUARANTY TRUST BANK" },
    { "code": "101", "name": "PROVIDUS BANK" },
    { "code": "000022", "name": "STERLING BANK" },
    { "code": "000018", "name": "UNION BANK" },
    { "code": "000004", "name": "UNITED BANK FOR AFRICA" },
    { "code": "000017", "name": "WEMA BANK" },
    { "code": "000015", "name": "ZENITH BANK" }
  ]
}

Resolve account details

GET /transfer/account/details Performs a name enquiry (account lookup) to verify a beneficiary account before sending a transfer. You must call this endpoint and confirm the returned accountName before initiating a bank transfer via NIP — the NIP route requires the session ID from this lookup.

Always display the resolved accountName to the user and request confirmation before submitting the transfer. Transfers sent to an incorrect account cannot be recalled automatically.

Request

string

required

Bearer token.

string

required

The beneficiary’s bank account number.

string

required

The beneficiary’s bank sort code. Obtain valid sort codes from GET /transfer/banks.

Response

boolean

true on success.

object

Show account properties

string

The registered name on the beneficiary account.

string

The account number as returned by the bank.

string

The sort code you provided.

Examples

curl "https://api.tagpay.ng/v1/transfer/account/details?accountNumber=0123456789&sortCode=000013" \
  -H "Authorization: Bearer <token>"

const params = new URLSearchParams({
  accountNumber: "0123456789",
  sortCode: "000013",
});

const response = await fetch(
  `https://api.tagpay.ng/v1/transfer/account/details?${params}`,
  { headers: { Authorization: "Bearer <token>" } }
);
const data = await response.json();

Response

{
  "status": true,
  "account": {
    "accountName": "OKONKWO AMAKA",
    "accountNumber": "0123456789",
    "bankCode": "000013"
  }
}

Send a bank transfer

POST /transfer/bank Sends funds from your merchant settlement wallet to any Nigerian bank account. Charges, VAT, and optional stamp duty are deducted from your wallet on top of the transfer amount. The transfer goes through immediately when called via API key. Requests made through the web dashboard enter a maker-checker approval queue and do not transfer funds until approved.

Request

string

required

Bearer token. Requires MANAGE_TRANSFER permission.

number

required

Transfer amount in kobo. Must be greater than 0.

string

required

Destination bank sort code. Obtain valid codes from GET /transfer/banks.

string

required

Destination account number.

string

required

Beneficiary name as resolved by GET /transfer/account/details. Required for NIP transfers.

string

Transfer narration/description visible to the beneficiary.

object

Arbitrary key-value data attached to the transaction. Returned in webhook payloads.

Response

boolean

true when the request was accepted. Note: status: true with transfer.status: "pending" means the transfer is being retried in the background.

string

Status message.

object

Transfer result object.

Show transfer properties

number

Transfer amount in kobo.

string

Internal transaction reference.

string

Reference returned by the payment network (NIP or Providus).

number

Transfer fee in kobo.

number

VAT on the transfer fee, in kobo.

number

Total amount deducted from your merchant wallet (amount + charges + VAT).

string

"success", "pending", or "failed".

string

NIP session ID for this transaction.

string

Encoded destination in the format accountNumber/sortCode.

string

Human-readable description of the transfer.

number

Stamp duty amount charged (if applicable, for NIP transfers above the threshold).

Examples

curl -X POST https://api.tagpay.ng/v1/transfer/bank \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000000,
    "sortCode": "000013",
    "accountNumber": "0123456789",
    "accountName": "OKONKWO AMAKA",
    "narration": "Salary payment May 2024"
  }'

const response = await fetch("https://api.tagpay.ng/v1/transfer/bank", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 5000000,
    sortCode: "000013",
    accountNumber: "0123456789",
    accountName: "OKONKWO AMAKA",
    narration: "Salary payment May 2024",
  }),
});

const data = await response.json();

Response (success)

{
  "status": true,
  "message": "Transaction successfully completed.",
  "transfer": {
    "amount": 5000000,
    "reference": "TXN-20240501-ABC123DEF456",
    "transactionReference": "NIP-20240501-XYZ789",
    "charges": 5000,
    "vat": 375,
    "total": 5005375,
    "status": "success",
    "sessionId": "SES-20240501-001",
    "destination": "0123456789/000013",
    "description": "Transfer of NGN50,000.00 to OKONKWO AMAKA (0123456789/Guaranty Trust Bank)"
  }
}

Response (pending)

{
  "status": true,
  "message": "Transaction is processing in the background.",
  "transfer": {
    "amount": 5000000,
    "reference": "TXN-20240501-ABC123DEF456",
    "transactionReference": "TXN-20240501-ABC123DEF456",
    "charges": 5000,
    "vat": 375,
    "total": 5005375,
    "status": "pending",
    "sessionId": "SES-20240501-001",
    "destination": "0123456789/000013",
    "description": "Transfer of NGN50,000.00 to OKONKWO AMAKA (0123456789/Guaranty Trust Bank)"
  }
}

Customer-initiated bank transfer

POST /transfer/bank/customer Sends a bank transfer where the funds are debited from a specific customer’s wallet rather than from your merchant settlement wallet. The customer’s tier limits, daily limits, and minimum balance rules apply.

Request

string

required

Bearer token. Requires MANAGE_TRANSFER permission.

string

required

UUID of the customer whose wallet will be debited.

number

required

Transfer amount in kobo. Must be greater than 0.

string

required

Destination bank sort code.

string

required

Destination account number.

string

required

Beneficiary name as returned by account lookup.

string

Transfer narration.

string

Your unique reference for this transaction. If omitted, one is auto-generated.

object

Arbitrary metadata attached to the transaction.

Response

Same structure as POST /transfer/bank. The transfer object is returned with the same fields.

Examples

curl -X POST https://api.tagpay.ng/v1/transfer/bank/customer \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
    "amount": 2000000,
    "sortCode": "000016",
    "accountNumber": "3012345678",
    "accountName": "CHIDI EZE",
    "narration": "Rent payment",
    "reference": "REF-CUST-TXN-20240501-001"
  }'

Response

{
  "status": true,
  "message": "Transaction successfully completed.",
  "transfer": {
    "amount": 2000000,
    "reference": "REF-CUST-TXN-20240501-001",
    "transactionReference": "NIP-20240501-CUST-001",
    "charges": 5000,
    "vat": 375,
    "total": 2005375,
    "customerId": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
    "status": "success",
    "sessionID": "SES-CUST-20240501-001",
    "destination": "3012345678/000016",
    "description": "Transfer of NGN20,000.00 to CHIDI EZE (3012345678/First Bank of Nigeria)"
  }
}

Error responses

HTTP Status	Description
`400`	Insufficient available balance
`400`	Beneficiary account details could not be resolved — call `GET /transfer/account/details` first
`400`	Invalid or unsupported sort code
`400`	Daily transaction limit exceeded
`400`	Merchant wallet is inactive
`400`	Transaction failed — funds reversed to source wallet
`401`	Missing or invalid authentication token
`403`	NIP transfers not enabled on this account

400 Failed (funds reversed)

{
  "status": false,
  "message": "Transaction failed. Kindly verify the transaction details before trying again.",
  "transfer": {
    "amount": 5000000,
    "status": "failed",
    ...
  }
}

400 Account Lookup Required

{
  "status": false,
  "message": "Please verify beneficiary account details."
}

Wallets

Transfers

Transactions

Webhooks

List supported banks

Request

Response

Examples

Resolve account details

Request

Response

Examples

Send a bank transfer

Request

Response

Examples

Customer-initiated bank transfer

Request

Response

Examples

Error responses

​List supported banks

​Request

​Response

​Examples

​Resolve account details

​Request

​Response

​Examples

​Send a bank transfer

​Request

​Response

​Examples

​Customer-initiated bank transfer

​Request

​Response

​Examples

​Error responses

List supported banks

Request

Response

Examples

Resolve account details

Request

Response

Examples

Send a bank transfer

Request

Response

Examples

Customer-initiated bank transfer

Request

Response

Examples

Error responses