Skip to main content

Overview

Monei allows you to save payment methods for faster, more convenient deposits. This guide covers adding, managing, and using saved payment methods. What you’ll learn:
  • Payment method types
  • Adding and verifying payment methods
  • Using saved methods for deposits
  • Managing and deleting payment methods
  • Security best practices

Payment Method Types

Monei supports multiple payment method types:

Virtual Account

Dedicated bank account for transfers

Debit/Credit Card

Save card for instant deposits

USSD

Quick deposits via USSD code

Get All Payment Methods

Retrieve all saved payment methods for a subwallet.
import MoneiSDK from 'monei-sdk';

const monei = new MoneiSDK({
  apiKey: process.env.MONEI_API_KEY,
});

// Get all payment methods for a subwallet
const paymentMethods = await monei.paymentMethods.getAll({
  subWalletId: 'subwallet_id_here'
});

paymentMethods.forEach(method => {
  console.log('Type:', method.type);
  console.log('Nickname:', method.nickname);
  console.log('Status:', method.status);
  console.log('Is Default:', method.isDefault);
  console.log('Last Used:', method.lastUsedAt);
  console.log('---');
});
Response:
{
  "statusCode": 200,
  "message": "Payment methods retrieved successfully",
  "data": [
    {
      "id": "pm_abc123",
      "type": "CARD",
      "status": "ACTIVE",
      "isDefault": true,
      "nickname": "My GTBank Card",
      "isEnabled": true,
      "lastUsedAt": "2024-02-10T10:30:00Z",
      "usageCount": 15,
      "capabilities": {
        "deposit": true,
        "withdrawal": false
      },
      "details": {
        "last4": "4242",
        "brand": "visa",
        "expiryMonth": "12",
        "expiryYear": "2025",
        "bank": "GTBank"
      },
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-02-10T10:30:00Z"
    }
  ]
}

Add Payment Method

Add Card

// Add a new card
const card = await monei.paymentMethods.create({
  type: 'CARD',
  subWalletId: 'subwallet_id_here',
  nickname: 'My GTBank Card',
  card: {
    cardNumber: '5531886652142950',
    cvv: '564',
    expiryMonth: '09',
    expiryYear: '32',
    cardHolderName: 'JOHN DOE'
  }
});

console.log('Card added:', card.id);
console.log('Nickname:', card.nickname);
console.log('Last 4 digits:', card.details.last4);
Card details are securely encrypted and stored. Only the last 4 digits are visible after adding.

Add USSD Method

// Add USSD payment method
const ussd = await monei.paymentMethods.create({
  type: 'USSD',
  subWalletId: 'subwallet_id_here',
  nickname: 'GTBank USSD',
  ussd: {
    bankCode: '058'
  }
});

console.log('USSD method added:', ussd.id);
console.log('Bank:', ussd.details.bankName);

Get Payment Method Details

Retrieve detailed information about a specific payment method.
// Get payment method by ID
const method = await monei.paymentMethods.get('pm_abc123');

console.log('ID:', method.id);
console.log('Type:', method.type);
console.log('Nickname:', method.nickname);
console.log('Status:', method.status);
console.log('Is Default:', method.isDefault);
console.log('Usage Count:', method.usageCount);
console.log('Last Used:', method.lastUsedAt);
console.log('Capabilities:', method.capabilities);
console.log('Details:', method.details);

Set Default Payment Method

Mark a payment method as default for faster deposits.
// Set as default
await monei.paymentMethods.setDefault('pm_abc123');

console.log('Payment method set as default');

// Verify
const method = await monei.paymentMethods.get('pm_abc123');
console.log('Is Default:', method.isDefault);
Only one payment method can be default at a time. Setting a new default automatically unsets the previous one.

Use Payment Method for Deposit

Deposit using a saved payment method.
// Deposit with saved payment method
const deposit = await monei.wallet.depositWithPaymentMethod({
  amount: 25000,
  paymentMethodId: 'pm_abc123',
  reference: 'DEP-' + Date.now(),
  currency: 'NGN',
  redirectUrl: 'https://yourapp.com/payment/success',
  narration: 'Wallet funding'
});

console.log('Deposit initiated:', deposit.reference);
console.log('Status:', deposit.status);

// Handle next action if required
if (deposit.nextAction) {
  console.log('Action required:', deposit.nextAction.type);
  
  if (deposit.nextAction.type === 'requires_otp') {
    // Prompt user for OTP
    const authorized = await monei.wallet.authorizeDeposit({
      type: 'otp',
      reference: deposit.reference,
      otp: '123456'
    });
  }
}
Benefits:
  • Faster deposits (no need to re-enter card details)
  • Secure storage
  • One-click payments
  • Automatic CVV verification

Delete Payment Method

Remove a saved payment method.
// Delete payment method
await monei.paymentMethods.delete('pm_abc123');

console.log('Payment method deleted successfully');
Deleting a payment method is permanent and cannot be undone. You’ll need to add it again if needed.

Payment Method Status

Payment methods can have different statuses:
StatusDescriptionCan Use?
ACTIVEReady to useYes
INACTIVETemporarily disabledNo
PENDING_VERIFICATIONAwaiting verificationNo
SUSPENDEDSuspended by systemNo

Payment Method Capabilities

Each payment method has specific capabilities:
Capabilities:
  • Deposit: ✓
  • Withdrawal: ✗
  • Recurring: ✓
Best For:
  • Regular deposits
  • Large amounts
  • Bank transfers

Security Features

How we protect your data:
  • End-to-end encryption
  • PCI DSS compliant
  • Tokenized card storage
  • No plaintext storage
  • Regular security audits
What we store:
  • Last 4 digits of card
  • Expiry date
  • Card brand
  • Token reference
What we DON’T store:
  • Full card number
  • CVV/PIN
  • Unencrypted data
Required for sensitive operations:
  • Adding payment method: API key
  • Using payment method: API key + OTP (if required)
  • Deleting payment method: API key
  • Updating default: API key
Additional security:
  • 3D Secure for cards
  • OTP verification
  • Device fingerprinting
  • IP whitelisting (enterprise)
Automatic fraud detection:
  • Unusual transaction patterns
  • Multiple failed attempts
  • Suspicious device/location
  • Velocity checks
Notifications:
  • New payment method added
  • Payment method used
  • Failed authorization
  • Suspicious activity
Regulatory compliance:
  • PCI DSS Level 1
  • CBN regulations
  • GDPR compliant
  • KYC/AML checks
Your controls:
  • Enable/disable methods
  • Delete anytime
  • View usage history
  • Export data

Best Practices

Use Nicknames

Give descriptive names to easily identify payment methods

Set Default

Mark your most-used method as default for faster deposits

Review Regularly

Check saved methods and remove unused ones

Monitor Usage

Track usage count and last used date

Keep Updated

Update expired cards before they fail

Enable Notifications

Get alerts when payment methods are used

Common Issues

Problem: Card payment fails during depositCommon causes:
  • Insufficient funds
  • Expired card
  • International card restrictions
  • Daily limit exceeded
  • Card not enabled for online transactions
Solutions:
  • Verify card balance
  • Check expiry date
  • Contact your bank to enable online transactions
  • Try a different card
  • Use bank transfer instead
Problem: Cannot use saved payment methodChecks:
const method = await monei.paymentMethods.get('pm_abc123');
console.log('Status:', method.status);
console.log('Is Enabled:', method.isEnabled);
console.log('Capabilities:', method.capabilities);
Solutions:
  • Ensure status is ACTIVE
  • Check if enabled
  • Verify capabilities
  • Re-sync payment methods
  • Delete and re-add
Problem: Payment methods not showingSolutions:
  1. Sync payment methods:
    await monei.paymentMethods.sync({
      subWalletId: 'subwallet_id_here'
    });
    
  2. Check correct subwallet:
    const wallet = await monei.wallet.me();
    const subwalletId = wallet.subwallets[0].id;
    
  3. Verify API key permissions

Next Steps

Deposits

Use payment methods to fund your wallet

Payouts

Send money from your wallet

Security Guidelines

Learn security best practices

Webhooks

Get real-time payment notifications