> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monei.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Methods

> Manage saved payment methods for faster deposits and transactions

## 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:

<CardGroup cols={4}>
  <Card title="Virtual Account" icon="building-columns">
    Dedicated bank account for transfers
  </Card>

  <Card title="Debit/Credit Card" icon="credit-card">
    Save card for instant deposits
  </Card>

  <Card title="USSD" icon="phone">
    Quick deposits via USSD code
  </Card>
</CardGroup>

***

## Get All Payment Methods

Retrieve all saved payment methods for a subwallet.

<CodeGroup>
  ```javascript Node.js theme={null}
  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('---');
  });
  ```

  ```python Python theme={null}
  from monei import MoneiClient

  monei = MoneiClient(
      api_key=os.getenv('MONEI_API_KEY')
  )

  # Get all payment methods
  payment_methods = monei.payment_methods.get_all(
      sub_wallet_id='subwallet_id_here'
  )

  for method in payment_methods:
      print(f'Type: {method.type}')
      print(f'Nickname: {method.nickname}')
      print(f'Status: {method.status}')
      print(f'Is Default: {method.is_default}')
      print('---')
  ```

  ```bash cURL theme={null}
  curl "https://api.monei.cc/api/v1/payment-methods?subWalletId=subwallet_id_here" \
    -H "x-api-key: YOUR_API_KEY"
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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

<CodeGroup>
  ```javascript Node.js theme={null}
  // 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);
  ```

  ```python Python theme={null}
  # Add a new card
  card = monei.payment_methods.create(
      type='CARD',
      sub_wallet_id='subwallet_id_here',
      nickname='My GTBank Card',
      card={
          'card_number': '5531886652142950',
          'cvv': '564',
          'expiry_month': '09',
          'expiry_year': '32',
          'card_holder_name': 'JOHN DOE'
      }
  )

  print(f'Card added: {card.id}')
  print(f'Last 4: {card.details.last4}')
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.monei.cc/api/v1/payment-methods \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "CARD",
      "subWalletId": "subwallet_id_here",
      "nickname": "My GTBank Card",
      "card": {
        "cardNumber": "5531886652142950",
        "cvv": "564",
        "expiryMonth": "09",
        "expiryYear": "32",
        "cardHolderName": "JOHN DOE"
      }
    }'
  ```
</CodeGroup>

<Warning>
  Card details are securely encrypted and stored. Only the last 4 digits are visible after adding.
</Warning>

### Add USSD Method

<CodeGroup>
  ```javascript Node.js theme={null}
  // 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);
  ```

  ```python Python theme={null}
  # Add USSD method
  ussd = monei.payment_methods.create(
      type='USSD',
      sub_wallet_id='subwallet_id_here',
      nickname='GTBank USSD',
      ussd={
          'bank_code': '058'
      }
  )

  print(f'USSD added: {ussd.id}')
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.monei.cc/api/v1/payment-methods \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "USSD",
      "subWalletId": "subwallet_id_here",
      "nickname": "GTBank USSD",
      "ussd": {
        "bankCode": "058"
      }
    }'
  ```
</CodeGroup>

***

## Get Payment Method Details

Retrieve detailed information about a specific payment method.

<CodeGroup>
  ```javascript Node.js theme={null}
  // 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);
  ```

  ```python Python theme={null}
  # Get payment method
  method = monei.payment_methods.get('pm_abc123')

  print(f'Type: {method.type}')
  print(f'Nickname: {method.nickname}')
  print(f'Status: {method.status}')
  print(f'Usage Count: {method.usage_count}')
  ```

  ```bash cURL theme={null}
  curl https://api.monei.cc/api/v1/payment-methods/pm_abc123 \
    -H "x-api-key: YOUR_API_KEY"
  ```
</CodeGroup>

***

## Set Default Payment Method

Mark a payment method as default for faster deposits.

<CodeGroup>
  ```javascript Node.js theme={null}
  // 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);
  ```

  ```python Python theme={null}
  # Set as default
  monei.payment_methods.set_default('pm_abc123')

  print('Set as default')

  # Verify
  method = monei.payment_methods.get('pm_abc123')
  print(f'Is Default: {method.is_default}')
  ```

  ```bash cURL theme={null}
  curl -X PATCH https://api.monei.cc/api/v1/payment-methods/pm_abc123/default \
    -H "x-api-key: YOUR_API_KEY"
  ```
</CodeGroup>

<Info>
  Only one payment method can be default at a time. Setting a new default automatically unsets the previous one.
</Info>

***

## Use Payment Method for Deposit

Deposit using a saved payment method.

<CodeGroup>
  ```javascript Node.js theme={null}
  // Deposit with saved payment method
  const deposit = await monei.deposit.withPaymentMethod({
    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.deposit.authorize({
        type: 'otp',
        reference: deposit.reference,
        otp: '123456'
      });
    }
  }
  ```

  ```python Python theme={null}
  # Deposit with saved method
  deposit = monei.deposit.with_payment_method(
      amount=25000,
      payment_method_id='pm_abc123',
      reference=f'DEP-{int(time.time())}',
      currency='NGN',
      redirect_url='https://yourapp.com/payment/success',
      narration='Wallet funding'
  )

  print(f'Initiated: {deposit.reference}')
  print(f'Status: {deposit.status}')
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.monei.cc/api/v1/wallet/deposit/payment-method \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 25000,
      "paymentMethodId": "pm_abc123",
      "reference": "DEP-1234567890",
      "currency": "NGN",
      "narration": "Wallet funding"
    }'
  ```
</CodeGroup>

**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.

<CodeGroup>
  ```javascript Node.js theme={null}
  // Delete payment method
  await monei.paymentMethods.delete('pm_abc123');

  console.log('Payment method deleted successfully');
  ```

  ```python Python theme={null}
  # Delete payment method
  monei.payment_methods.delete('pm_abc123')

  print('Payment method deleted')
  ```

  ```bash cURL theme={null}
  curl -X DELETE https://api.monei.cc/api/v1/payment-methods/pm_abc123 \
    -H "x-api-key: YOUR_API_KEY"
  ```
</CodeGroup>

<Warning>
  Deleting a payment method is permanent and cannot be undone. You'll need to add it again if needed.
</Warning>

***

## Payment Method Status

Payment methods can have different statuses:

| Status                 | Description           | Can Use? |
| ---------------------- | --------------------- | -------- |
| `ACTIVE`               | Ready to use          | Yes      |
| `INACTIVE`             | Temporarily disabled  | No       |
| `PENDING_VERIFICATION` | Awaiting verification | No       |
| `SUSPENDED`            | Suspended by system   | No       |

***

## Payment Method Capabilities

Each payment method has specific capabilities:

<Tabs>
  <Tab title="Virtual Account">
    **Capabilities:**

    * Deposit: ✓
    * Withdrawal: ✗
    * Recurring: ✓

    **Best For:**

    * Regular deposits
    * Large amounts
    * Bank transfers
  </Tab>

  <Tab title="Card">
    **Capabilities:**

    * Deposit: ✓
    * Withdrawal: ✗ (planned)
    * Recurring: ✓

    **Best For:**

    * Instant deposits
    * International cards
    * Quick top-ups
  </Tab>

  <Tab title="USSD">
    **Capabilities:**

    * Deposit: ✓
    * Withdrawal: ✗
    * Recurring: ✗

    **Best For:**

    * No internet access
    * Quick deposits
    * Mobile users
  </Tab>

  <Tab title="Crypto Wallet">
    **Capabilities:**

    * Deposit: ✓
    * Withdrawal: ✓
    * Recurring: ✓

    **Best For:**

    * Crypto to fiat
    * Cross-border
    * DeFi integration
  </Tab>
</Tabs>

***

## Security Features

<AccordionGroup>
  <Accordion icon="shield-check" title="Encrypted Storage">
    **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
  </Accordion>

  <Accordion icon="key" title="Authentication">
    **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)
  </Accordion>

  <Accordion icon="bell" title="Monitoring">
    **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
  </Accordion>

  <Accordion icon="lock" title="Compliance">
    **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
  </Accordion>
</AccordionGroup>

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Nicknames" icon="tag">
    Give descriptive names to easily identify payment methods
  </Card>

  <Card title="Set Default" icon="star">
    Mark your most-used method as default for faster deposits
  </Card>

  <Card title="Review Regularly" icon="eye">
    Check saved methods and remove unused ones
  </Card>

  <Card title="Monitor Usage" icon="chart-line">
    Track usage count and last used date
  </Card>

  <Card title="Keep Updated" icon="arrows-rotate">
    Update expired cards before they fail
  </Card>

  <Card title="Enable Notifications" icon="bell">
    Get alerts when payment methods are used
  </Card>
</CardGroup>

***

## Common Issues

<AccordionGroup>
  <Accordion icon="circle-xmark" title="Card Declined">
    **Problem:** Card payment fails during deposit

    **Common 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
  </Accordion>

  <Accordion icon="circle-xmark" title="Payment Method Not Working">
    **Problem:** Cannot use saved payment method

    **Checks:**

    ```javascript theme={null}
    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
  </Accordion>

  <Accordion icon="exclamation-triangle" title="Missing Payment Methods">
    **Problem:** Payment methods not showing

    **Solutions:**

    1. **Sync payment methods:**
       ```javascript theme={null}
       await monei.paymentMethods.sync({
         subWalletId: 'subwallet_id_here'
       });
       ```

    2. **Check correct subwallet:**
       ```javascript theme={null}
       const wallet = await monei.wallet.me();
       const subwalletId = wallet.subwallets[0].id;
       ```

    3. **Verify API key permissions**
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Deposits" icon="arrow-down" href="/naira-wallet/deposits">
    Use payment methods to fund your wallet
  </Card>

  <Card title="Payouts" icon="arrow-up" href="/naira-wallet/payouts">
    Send money from your wallet
  </Card>

  <Card title="Security Guidelines" icon="shield" href="/security/guidelines">
    Learn security best practices
  </Card>

  <Card title="Webhooks" icon="webhook" href="/security/webhooks">
    Get real-time payment notifications
  </Card>
</CardGroup>