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

# Add Payment Method

> This endpoint allows you to attach a payment method to an existing wallet. A payment method defines how funds can be added to or withdrawn from a wallet, such as via a bank account.

## Endpoint

```json theme={null}
POST /wallets/{id}/payment-method
```

## Description

Use this endpoint to add a payment method to a wallet that has already been created. Once a payment method is added, the wallet can be funded or used for payouts through the specified channel.

***

## Path Parameters

| Parameter | Type          | Required | Description                         |
| :-------- | :------------ | :------- | :---------------------------------- |
| `id`      | string (UUID) | Yes      | The unique identifier of the wallet |

***

## Request Body

```json theme={null}
{
  "type": "bank_account"
}
```

### Request Fields

| Field  | Type   | Required | Description                       |
| :----- | :----- | :------- | :-------------------------------- |
| `type` | string | Yes      | The type of payment method to add |

### Supported Payment Method Types

| Type           | Description                                               |
| :------------- | :-------------------------------------------------------- |
| `bank_account` | Links a bank account to the wallet for funding or payouts |

> Additional payment method types may be supported depending on your integration and region.

***

## Response

### Success Response (200 OK)

```json theme={null}
{
  "data": {
    "id": "3d2e3f3e-3b3c-4907-a4fd-e241203440d7",
    "status": "active",
    "payment_methods": [
      {
        "account_name": "Prosacco Erdman",
        "account_number": "3515200757",
        "account_type": "savings",
        "address": null,
        "bank_address": "9896 Bulah Roads, Suite 256, North Carolina, Kansas, 09819, US",
        "bank_code": "035",
        "bank_name": "Wema Bank"
      }
    ],

    "balance": {
      "amount": 0,
      "currency": "NGN"
    }
  }
}
```

## Response Fields

| Field              | Type   | Description                                        |
| :----------------- | :----- | :------------------------------------------------- |
| `id`               | string | The wallet ID                                      |
| `status`           | string | Current wallet status (`active`, `inactive`, etc.) |
| `payment_methods`  | array  | List of payment methods linked to the wallet       |
| `balance.amount`   | number | Wallet balance amount                              |
| `balance.currency` | string | Wallet currency                                    |

> The `payment_methods` array may initially be empty if additional verification or setup is required before activation.

***

## Example cURL Request

```bash theme={null}
curl -X POST https://api.yourdomain.com/wallets/{id}/payment-method \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "bank_account"
  }'
```

***

## Common Errors

| Status Code | Reason                                     |
| :---------- | :----------------------------------------- |
| `400`       | Invalid request body                       |
| `401`       | Unauthorized request                       |
| `404`       | Wallet not found                           |
| `422`       | Unsupported or invalid payment method type |

***

## Notes & Best Practices

* Ensure the wallet exists and is active before adding a payment method.
* Some payment methods may require additional verification steps before they become usable.
* Always store and reference the wallet ID securely.
* Use sandbox mode to test payment method creation before moving to production.

***

## Next Steps

After successfully adding a payment method, you can:

* Fund the wallet
* Initiate payouts
* Retrieve wallet details
* Monitor wallet activity via webhooks