Transactions - Credit, Debit & Transfer Funds

Manage customer wallet transactions seamlessly through the Monieswitch dashboard. This guide covers crediting, debiting, and transferring funds between wallets.

Credit Wallet

Add funds from your merchant account to any customer wallet instantly. This feature is accessible through the “Credit Account” option in the Action dropdown menu when viewing a wallet. How Credit Operations Work: When you credit a customer wallet, funds are instantly transferred from your merchant account balance to the customer’s available balance. This operation is commonly used for:

Customer refunds
Bonus or incentive payments
Cashback rewards
Manual wallet top-ups
Promotional credits

Transaction Process:

Navigate to the wallet you want to credit from the wallet list
Click the “Action” dropdown button in the top-right corner
Select “Credit Account” from the menu options
Enter the amount in Naira (not kobo)
Add a narration describing the transaction purpose
Enter your merchant transaction PIN for authorization
Review details and click “Credit Wallet” to complete

Requirements:

Sufficient balance in your merchant account
Valid transaction PIN
Transaction narration/description
Active wallet status

Instant Processing: Credit operations are processed instantly with zero fees. The customer’s balance updates in real-time, and they receive an instant notification if enabled.

API Integration Example

Credit wallets programmatically:

Credit Wallet

curl --location 'https://nini.monieswitch.com/wallet/credit' \
  --header 'Authorization: Bearer {{merchantAPIKey}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 5000,
    "pin": "1234",
    "narration": "Wallet top-up",
    "walletId": "53341293-eb2f-4510-8ebc-bad35ad2bd72",
    "metadata": {
      "reference": "TOP-UP-001"
    }
  }'

Note: Amount is in kobo when using the API (5000 = ₦50.00).See the API Reference for complete documentation.

Debit Wallet

Withdraw funds from a customer wallet to your merchant account. Access this through the “Debit Account” option in the Action menu. Common Use Cases:

Processing service payments
Collecting subscription fees
Charging for products or services
Automated recurring billing
Payment collection

How Debit Operations Work: The system performs several automatic checks before processing a debit:

Verifies customer has sufficient available balance
Ensures transaction doesn’t exceed customer’s daily tier limit
Confirms wallet is active (not frozen or disabled)
Validates amount is within allowed limits

Transaction Process:

Open the wallet you want to debit from the wallet list
Click the “Action” dropdown menu
Choose “Debit Account” from the options
Enter the debit amount in Naira
Provide a clear narration explaining the charge
Enter your transaction PIN for security
Confirm and process the debit transaction

Transaction Will Fail If:

Customer has insufficient balance in their wallet
Customer’s daily transaction limit has been exceeded
Wallet is frozen, disabled, or inactive
Invalid or incorrect transaction PIN entered
Amount exceeds tier maximum balance rules

API Integration Example

Debit wallets via API:

Debit Wallet

curl --location 'https://nini.monieswitch.com/wallet/debit' \
  --header 'Authorization: Bearer {{merchantAPIKey}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 2000,
    "pin": "1234",
    "narration": "Service charge",
    "walletId": "53341293-eb2f-4510-8ebc-bad35ad2bd72",
    "metadata": {
      "invoice": "INV-2024-001"
    }
  }'

Note: Amount is in kobo when using the API.See the API Reference for details and response format.

Wallet-to-Wallet Transfer

Enable instant fund transfers between customer wallets with zero transaction fees. Access this through “Wallet to Wallet” in the Action menu. Transfer Benefits:

✅ Zero transaction fees (completely free)
✅ Instant settlement (real-time processing)
✅ No bank charges or third-party fees
✅ 24/7 availability (no banking hours restrictions)
✅ Real-time notifications to both parties

How Transfers Work: Wallet-to-wallet transfers allow your customers to send money to each other instantly within your platform. This is ideal for peer-to-peer payments, splitting bills, or internal fund movements. Transfer Process:

Navigate to the source wallet (sender) from your wallet list
Click “Action” → “Wallet to Wallet”
Enter or search for the destination wallet ID or account number
Specify the transfer amount in Naira
Add a narration describing the transfer purpose
Enter your transaction PIN for authorization
Review the transfer details carefully
Confirm to complete the instant transfer

Transfer Limits: All wallet-to-wallet transfers are subject to the sender’s tier limits. For example: - Tier 1 wallets can send up to ₦50,000 per day - Tier 2 wallets can send up to ₦200,000 per day - Tier 3 wallets can send up to ₦5,000,000 per day

API Integration Example

Process wallet transfers via API:

Wallet-to-Wallet Transfer

curl --location 'https://nini.monieswitch.com/wallet/transfer' \
  --header 'Authorization: Bearer {{merchantAPIKey}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 10000,
    "pin": "1234",
    "narration": "Payment for services",
    "metadata": {"reference": "PAY-001"},
    "toWalletId": "eb8b935f-188e-40f5-b27a-6d8f1ba408f1",
    "fromWalletId": "0ed45265-c7bc-44c4-9669-c521415c2958"
  }'

Both sender and receiver get instant notifications upon successful transfer.See the API Reference for complete documentation.

Bank Transfer

Send funds from customer wallets to any Nigerian bank account instantly. Access this feature via “Bank Transfer” in the Action menu. What is Bank Transfer? Bank transfer allows you to send money from a customer’s wallet to any bank account in Nigeria using the Nigeria Inter-Bank Settlement System (NIBSS) Instant Payment (NIP) platform. This enables real-time transfers to over 20+ Nigerian financial institutions. Key Features:

Wide Coverage: Send to any Nigerian bank (Access, GTBank, UBA, First Bank, Zenith, Kuda, and 20+ others)
Fast Processing: Transfers complete within 1-5 minutes
24/7 Availability: Process transfers anytime, including weekends and holidays
Account Verification: Automatic recipient name lookup before transfer
Real-time Status: Instant confirmation and notifications

Transfer Details:

Processing Time: 1-5 minutes (typically under 2 minutes)
Transaction Fee: ₦10 - ₦25 per transaction (depends on amount)
Availability: 24/7 with instant settlement
Daily Limits: Subject to customer’s wallet tier limits
Supported Banks: All Nigerian commercial banks and microfinance institutions

How Bank Transfers Work

Step-by-Step Process:

Navigate to the customer wallet from your wallet list that will send the funds
Click the “Action” dropdown menu and select “Bank Transfer”
Select the destination bank from the dropdown list of all Nigerian banks
Input the recipient’s 10-digit account number (system auto-verifies)
Confirm that the automatically retrieved account name matches the intended recipient
Specify the transfer amount in Naira (fees will be calculated automatically)
Provide a description or reference for the transaction and proceed
Check all transfer details including fees before proceeding
Enter your transaction PIN to authorize and process the transfer
Receive instant confirmation with transaction reference number

Account Name Verification

Automatic Verification Process: When you enter a recipient’s account number, the system automatically:

Sends a verification request to the recipient’s bank
Retrieves the official account holder name from the bank
Displays the name for you to confirm
Prevents transfer if name verification fails

Security Feature: This automatic account name verification prevents sending money to the wrong account. Always verify the displayed name matches your intended recipient before proceeding.

What to Do If Name Doesn’t Match:

Double-check the account number for typos
Confirm the correct bank was selected
Verify account details with the recipient
Do NOT proceed if the name is incorrect

Transfer Fees & Charges

Fee Structure:

Transaction Amount	Fee
₦1 - ₦5,000	₦10
₦5,001 - ₦50,000	₦25
Above ₦50,000	₦50

Important Notes:

Fees are automatically calculated and displayed before confirmation
The total debit includes both transfer amount and fee
Fees are deducted from the sender’s wallet balance
No hidden charges or additional costs
VAT is included in the displayed fee

Example:

Transfer Amount: ₦10,000
Transaction Fee: ₦25
Total Debit: ₦10,025

The recipient receives the exact amount you specify. Fees are paid by the sender and don’t reduce the amount the recipient receives.

Transfer Limits

Bank transfers are subject to the sender’s wallet tier limits: Daily Transaction Limits:

Tier 1 Wallet: Maximum ₦50,000 per day
Tier 2 Wallet: Maximum ₦200,000 per day
Tier 3 Wallet: Maximum ₦5,000,000 per day

Per Transaction Limits:

Minimum: ₦100 per transaction
Maximum: ₦5,000,000 per transaction (Tier 3 only)

If you need to send amounts exceeding your tier limit, consider upgrading the wallet tier.

Transaction Status

Possible Transfer States: SUCCESS: Transfer completed successfully. Funds have been credited to the recipient’s bank account. You’ll receive a transaction reference number for tracking. PENDING: Transfer is being processed by the banking network. This typically resolves within 1-5 minutes. Check back shortly for final status. FAILED: Transfer could not be completed. Common reasons include:

Insufficient wallet balance
Invalid or closed recipient account
Recipient bank temporarily unavailable
Daily limit exceeded
Technical issues with banking network

If a transfer fails, the amount is immediately reversed to the sender’s wallet.

Common Issues & Solutions

Transfer Pending Too Long

Issue: Transfer shows as “Pending” for more than 10 minutesSolutions:

Wait up to 30 minutes for banking network processing
Check if recipient bank is experiencing downtime
Contact support with transaction reference if pending after 1 hour
Amount will auto-reverse if not settled within 24 hours

Account Name Not Showing

Issue: Account verification fails or name doesn’t displaySolutions:

Verify you selected the correct bank
Confirm account number is exactly 10 digits
Check if recipient bank is online (may be under maintenance)
Try again after a few minutes
Contact recipient to verify their account details

Transfer Failed After Confirmation

Issue: Transfer fails after you authorized itSolutions:

Check your wallet has sufficient balance (amount + fee)
Verify you haven’t exceeded daily tier limit
Confirm recipient account is active and not restricted
Ensure wallet is not frozen or disabled
Check transaction history for error details

Wrong Account Debited

Issue: Money sent to wrong accountSolutions:

Contact the recipient immediately to request return
Contact support with transaction reference for investigation
Note: Transfers cannot be reversed automatically
Always verify account name before confirming transfer
Keep transaction reference for dispute resolution

Best Practices

Before Transfer

Always Verify:

Account number is correct
Bank selection matches recipient
Account name matches intended person
Sufficient balance (amount + fee)
Not exceeding daily limits

During Transfer

Security Checks: - Review all details carefully - Verify transaction fee amount - Keep your PIN confidential - Confirm narration is appropriate - Double-check total debit amount

After Transfer

Record Keeping: - Save transaction reference number - Screenshot confirmation for records - Notify recipient of transfer - Monitor status until confirmed - Keep records for reconciliation

Troubleshooting

If Issues Occur:

Note exact error message
Save transaction reference
Check wallet transaction history
Contact recipient to confirm
Reach out to support if needed

Transaction Receipts

After a successful bank transfer, you’ll receive: Digital Receipt Contains:

Transaction reference number
Date and time of transaction
Sender details (wallet account)
Recipient details (bank account)
Transfer amount
Transaction fee
Total amount debited
Transaction status
Narration/description

How to Access Receipts:

Navigate to the wallet’s transaction history
Find the specific bank transfer transaction
Click on the transaction row to view details
Click “Download Receipt” or “Print” option
Choose PDF or print format

Receipts can be shared with customers or used for accounting and reconciliation purposes.

What’s Next?

Tier System

Learn about tier requirements and limits

Wallet controls

Manage wallet status: freeze, unfreeze, upgrade tier

Start building

Learn how to manage, distribute and integrate your payment application with our API and SDKs.

Tutorials and guides

Learn how to work with Monieswitch and your favorite language or framework.

Monieswitch SDKs

Build seamless integrations with our official SDKs.

Get Started

Setup Monieswitch

Products

Guide and How-to

Support and resources

Transactions - Credit, Debit & Transfer Funds

Credit Wallet

Debit Wallet

Wallet-to-Wallet Transfer

Bank Transfer

How Bank Transfers Work

Account Name Verification

Transfer Fees & Charges

Transfer Limits

Transaction Status

Common Issues & Solutions

Best Practices

Before Transfer

During Transfer

After Transfer

Troubleshooting

Transaction Receipts

What’s Next?

Tier System

Wallet controls

Start building

Tutorials and guides

Monieswitch SDKs

Get Started

Setup Monieswitch

Products

Guide and How-to

Support and resources

​Credit Wallet

​Debit Wallet

​Wallet-to-Wallet Transfer

​Bank Transfer

​How Bank Transfers Work

​Account Name Verification

​Transfer Fees & Charges

​Transfer Limits

​Transaction Status

​Common Issues & Solutions

​Best Practices

Before Transfer

During Transfer

After Transfer

Troubleshooting

​Transaction Receipts

​What’s Next?

Tier System

Wallet controls

​Start building

Tutorials and guides

Monieswitch SDKs

Credit Wallet

Debit Wallet

Wallet-to-Wallet Transfer

Bank Transfer

How Bank Transfers Work

Account Name Verification

Transfer Fees & Charges

Transfer Limits

Transaction Status

Common Issues & Solutions

Best Practices

Transaction Receipts

What’s Next?

Start building