Setting Up Your VTU Wallet: Payment Gateways Explained

Customers cannot buy anything until their wallet has money in it, so wallet funding is the part of your VTU site that has to work every single time. This guide explains the funding options on the platform, where to set them up, how each one credits the wallet, which details to save so that automatic crediting works, and how to test before you go live.

Where to set it up

Open VTU Admin, then Customers & Payments, then Payment Gateways. Each gateway has an on and off switch, a Test / sandbox mode checkbox and boxes for its credentials, and the screen shows the webhook address for that gateway. A gateway you have not set up yet starts with test mode ticked. Paste your keys, turn the gateway on and save. Keep sandbox mode on while you are testing, and switch it off only when you are ready for real money. Gateways settle straight to your own account, because you are connecting your own gateway account.

The funding options at a glance

• Paystack (hosted checkout): Public Key and Secret Key.
• Flutterwave (hosted checkout): Public Key and Secret Key. It handles card and bank payments in several currencies, including NGN, GHS, KES, XOF, XAF and USD, which makes it the better fit if you serve customers outside Nigeria.
• Monnify (dedicated account number): API Key, Secret Key and Contract Code.
• PaymentPoint (dedicated account number): API Key, API Secret, Business ID and the bank codes you want. It needs the customer's BVN or NIN.
• Billstack (dedicated account number): an API token and the bank to use, with 9PSB the default. It does not need a BVN or NIN.
• PocketFi (dedicated account number): API token, Webhook Secret Key, Business ID and a bank. A BVN or NIN is only needed if you choose PalmPay as the bank.
• Xpiria Biz (default): needs no keys of your own. It uses a shared platform account and works with or without BVN or NIN. A platform fee applies, so check the details in your dashboard and the Settlement section before you rely on it.
• Manual bank transfer: customers transfer to your own account and upload proof, and you approve it. See accepting manual bank transfers.

A note on PalmPay. PalmPay appears in the list, but at the time of writing the platform rejects PalmPay's payment notifications on purpose. PalmPay's callback cannot yet be verified as genuine, and accepting an unverified one would let anyone fake a credit. In practice that means money sent to a PalmPay account on your site will not credit the wallet automatically. Until that changes, use one of the other gateways above, or Manual.

Two ways customers fund

1. Hosted checkout (Paystack and Flutterwave). The customer enters an amount and is sent to the gateway's payment page, which opens in a new tab. When they pay, the gateway tells your site and the wallet is credited. The funding screen on your site also checks every few seconds for roughly two and a half minutes, so the balance usually updates without the customer refreshing. For Flutterwave, the platform never trusts the notification on its own: it asks Flutterwave whether that payment really happened and credits the amount Flutterwave reports.
2. A dedicated account number (Monnify, PaymentPoint, Billstack, PocketFi, Xpiria Biz). The customer gets their own account number, transfers any amount to it from their bank app, and the wallet is credited automatically when the gateway notifies your site. Monnify and PaymentPoint only collect naira, so a customer whose balance is in another currency is told this method only supports NGN and asked to pay by card instead.

Webhooks: the part people forget

For automatic crediting, each gateway has to know where to send its payment notifications. The Payment Gateways screen shows a webhook address for each gateway, in this form: your site's address, then /api/vtu/, then your project ID, then /webhook/ and the gateway's name. Copy it into the gateway's own dashboard, in its webhook or callback settings. If you skip this, customers will pay and the wallet will not update, and you will get angry messages. Always confirm the webhook is saved before you go live.

Save the secret key too. For Paystack, Monnify, PaymentPoint, Billstack and PocketFi, each notification carries a signature that the platform checks against the secret you saved. If that secret is blank, or the signature does not match, the notification is rejected, so a gateway with a missing secret key will never credit anyone automatically. That is deliberate: it stops someone posting a fake "payment received" message to your address. Flutterwave is the exception, because the platform double-checks with Flutterwave itself instead.

Charging a fee for funding

You can add a funding charge under Settings, then Wallet Funding Charge, either as a flat amount or a percentage. The charge is taken from the amount credited, so the customer receives slightly less than they paid. Funding that you approve by hand, such as manual bank transfers, is credited in full without the charge. The minimum funding amount is ₦100.

A test checklist before launch

• Turn on sandbox mode for the gateway and make a small test funding.
• Confirm the wallet balance rises and a funding record appears in your admin dashboard.
• Check the webhook address is saved in the gateway's dashboard, and the secret key is saved here.
• Switch off sandbox mode, then fund a small real amount from your own account.
• Check that the funding charge, if you use one, is taken as you expect.
• Try funding from a phone, on mobile data, the way your customers will.
• Keep your gateway keys private. If you think they were exposed, change them in the gateway's dashboard and paste the new ones here.

Common problems

• The customer paid, but the wallet did not move. Check the webhook is saved in the gateway's dashboard, the gateway is switched on here, and its secret key is saved. For a hosted checkout, ask the customer to keep the funding page open for a couple of minutes.
• The account number does not appear. The gateway may need the customer's details first, such as a BVN or NIN, so check the requirements for that gateway.
• Test payments show up as real. Check whether sandbox mode is on or off for that gateway.
• A foreign-currency customer cannot use Monnify or PaymentPoint. That is expected, because they only collect naira. Offer card payment through Paystack or Flutterwave.
• Someone sent money to a PalmPay account. It will not credit automatically for now. Credit the wallet by hand with a wallet adjustment (see managing customers and wallets), and only after you have confirmed the money arrived in your PalmPay account.

Further reading

After funding works, connect a provider in connecting a vending API, and read how to handle disputes in failed transactions and wallet refunds. If you are choosing between Paystack and Flutterwave for your own business payments, our Paystack API tutorial and Flutterwave API tutorial explain the technical side.