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/banksReturns all banks currently supported for outward transfers, sorted alphabetically by name.
Request Response Array of bank objects. Bank sort code. Use this value as sortCode in transfer requests.
Human-readable bank name.
Examples curl "https://api.tagpay.ng/v1/transfer/banks" \ -H "Authorization: Bearer <token>"
{ "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/detailsPerforms 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 The beneficiary’s bank account number.
The beneficiary’s bank sort code. Obtain valid sort codes from GET /transfer/banks.
Response The registered name on the beneficiary account.
The account number as returned by the bank.
The sort code you provided.
Examples curl "https://api.tagpay.ng/v1/transfer/account/details?accountNumber=0123456789&sortCode=000013" \ -H "Authorization: Bearer <token>"
{ "status" : true , "account" : { "accountName" : "OKONKWO AMAKA" , "accountNumber" : "0123456789" , "bankCode" : "000013" } }
Send a bank transfer POST /transfer/bankSends 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 Bearer token. Requires MANAGE_TRANSFER permission.
Transfer amount in kobo. Must be greater than 0.
Destination bank sort code. Obtain valid codes from GET /transfer/banks.
Destination account number.
Beneficiary name as resolved by GET /transfer/account/details. Required for NIP transfers.
Transfer narration/description visible to the beneficiary.
Arbitrary key-value data attached to the transaction. Returned in webhook payloads.
Response true when the request was accepted. Note: status: true with transfer.status: "pending" means the transfer is being retried in the background.
Transfer result object. Internal transaction reference.
Reference returned by the payment network (NIP or Providus).
VAT on the transfer fee, in kobo.
Total amount deducted from your merchant wallet (amount + charges + VAT).
"success", "pending", or "failed".
NIP session ID for this transaction.
Encoded destination in the format accountNumber/sortCode.
Human-readable description of the transfer.
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" }'
{ "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)" } }
{ "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/customerSends 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 Bearer token. Requires MANAGE_TRANSFER permission.
UUID of the customer whose wallet will be debited.
Transfer amount in kobo. Must be greater than 0.
Destination bank sort code.
Destination account number.
Beneficiary name as returned by account lookup.
Your unique reference for this transaction. If omitted, one is auto-generated.
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" }'
{ "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 400Insufficient available balance 400Beneficiary account details could not be resolved — call GET /transfer/account/details first 400Invalid or unsupported sort code 400Daily transaction limit exceeded 400Merchant wallet is inactive 400Transaction failed — funds reversed to source wallet 401Missing or invalid authentication token 403NIP 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." }
