# Wallet Management API

Programmatically manage your linked wallet — view details, add or remove members, and update settings via an admin API key.

::: warning Admin Access Required
These endpoints require an API key with **admin role** on the linked wallet. Admin API keys can manage members but **cannot** manage other admins or the wallet owner. Only the wallet owner can promote/demote admins from the dashboard.
:::

## Authentication

All wallet management endpoints require:

1. A **secret key** (`sk_live_*` or `sk_test_*`) passed via `Authorization: Bearer sk_live_...`
2. The API key must have the `transfers` permission
3. A programmable-debit wallet must be linked to the API key
4. The API key must have **admin role** on the wallet (configured from the Members tab in the dashboard)

See [Authentication](/guide/authentication) for details.

---

## Get Wallet

Retrieve the linked wallet's details including balance, members, settings, and API key members.

```
GET /v1/checkout/wallet
```

### Authentication

Secret key required. `transfers` permission required. Admin role required.

### Example Request

::: code-group

```bash [cURL]
curl https://api.zevpaycheckout.com/v1/checkout/wallet \
  -H "Authorization: Bearer sk_live_your_secret_key"
```

```javascript [Node.js]
const response = await fetch('https://api.zevpaycheckout.com/v1/checkout/wallet', {
  headers: {
    'Authorization': 'Bearer sk_live_your_secret_key',
  },
});
const { data } = await response.json();
console.log(data.name, data.balance);
```

```python [Python]
import requests

response = requests.get(
    'https://api.zevpaycheckout.com/v1/checkout/wallet',
    headers={'Authorization': 'Bearer sk_live_your_secret_key'},
)
data = response.json()['data']
print(data['name'], data['balance'])
```

:::

### Response

```json
{
  "success": true,
  "data": {
    "public_id": "wlt_abc123",
    "name": "Operations Wallet",
    "description": "Main operations wallet",
    "pay_id": "@ops.wallet",
    "owner_type": "business",
    "balance": {
      "available": 5000000,
      "currency": "NGN"
    },
    "settings": {
      "daily_limit": "5000.00",
      "monthly_limit": "155000.00",
      "single_limit": null,
      "enable_notification": true,
      "hide_members_transaction": false,
      "allow_programmable_debit": true
    },
    "members": [
      {
        "pay_id": "@john.personal",
        "display_name": "John Doe",
        "entity_type": "personal",
        "role": "owner",
        "joined_at": "2025-01-15T10:00:00.000Z"
      },
      {
        "pay_id": "@jane.personal",
        "display_name": "Jane Smith",
        "entity_type": "personal",
        "role": "member",
        "joined_at": "2025-02-01T10:00:00.000Z"
      }
    ],
    "api_key_members": [
      {
        "api_key_id": "uuid-here",
        "label": "Production Key",
        "key_prefix": "sk_live_ab",
        "role": "admin",
        "linked_at": "2025-03-01T10:00:00.000Z"
      }
    ],
    "member_count": 4,
    "created_at": "2025-01-15T10:00:00.000Z"
  }
}
```

### Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `public_id` | string | Wallet public identifier |
| `name` | string | Wallet name |
| `description` | string | Wallet description |
| `pay_id` | string | Wallet's PayID |
| `owner_type` | string | `business` or `personal` |
| `balance.available` | number | Available balance in kobo (divide by 100 for naira) |
| `balance.currency` | string | Currency code (e.g. `NGN`) |
| `settings` | object | Wallet-level settings |
| `members` | array | List of human members with their roles |
| `api_key_members` | array | List of API key members with their roles |
| `member_count` | number | Total member count (people + API keys) |
| `created_at` | string | ISO 8601 creation timestamp |

---

## Update Wallet Settings

Update the linked wallet's settings. Admin API keys can update name, description, notification, and transaction visibility settings.

```
PATCH /v1/checkout/wallet
```

### Authentication

Secret key required. `transfers` permission required. Admin role required.

### Request Body

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Wallet name (max 100 characters) |
| `description` | string | No | Wallet description |
| `enable_notification` | boolean | No | Enable/disable transaction notifications |
| `hide_members_transaction` | boolean | No | Hide transaction details from members |

### Example Request

::: code-group

```bash [cURL]
curl -X PATCH https://api.zevpaycheckout.com/v1/checkout/wallet \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Wallet Name",
    "hide_members_transaction": true
  }'
```

```javascript [Node.js]
const response = await fetch('https://api.zevpaycheckout.com/v1/checkout/wallet', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer sk_live_your_secret_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Updated Wallet Name',
    hide_members_transaction: true,
  }),
});
const { data } = await response.json();
```

```python [Python]
import requests

response = requests.patch(
    'https://api.zevpaycheckout.com/v1/checkout/wallet',
    headers={'Authorization': 'Bearer sk_live_your_secret_key'},
    json={
        'name': 'Updated Wallet Name',
        'hide_members_transaction': True,
    },
)
```

:::

### Response

```json
{
  "success": true,
  "data": {
    "success": true,
    "message": "Wallet settings updated"
  }
}
```

---

## List Members

List all members of the linked wallet, including both human members and API key members with their settings.

```
GET /v1/checkout/wallet/members
```

### Authentication

Secret key required. `transfers` permission required. Admin role required.

### Example Request

::: code-group

```bash [cURL]
curl https://api.zevpaycheckout.com/v1/checkout/wallet/members \
  -H "Authorization: Bearer sk_live_your_secret_key"
```

```javascript [Node.js]
const response = await fetch('https://api.zevpaycheckout.com/v1/checkout/wallet/members', {
  headers: {
    'Authorization': 'Bearer sk_live_your_secret_key',
  },
});
const { data } = await response.json();
console.log(data.members, data.api_key_members);
```

```python [Python]
import requests

response = requests.get(
    'https://api.zevpaycheckout.com/v1/checkout/wallet/members',
    headers={'Authorization': 'Bearer sk_live_your_secret_key'},
)
data = response.json()['data']
print(data['members'])
```

:::

### Response

```json
{
  "success": true,
  "data": {
    "members": [
      {
        "pay_id": "@john.personal",
        "display_name": "John Doe",
        "entity_type": "personal",
        "role": "owner",
        "is_active": true,
        "joined_at": "2025-01-15T10:00:00.000Z",
        "settings": {
          "enable_notification": true,
          "hide_wallet_balance": false,
          "has_daily_limit": false,
          "daily_limit": null,
          "has_monthly_limit": false,
          "monthly_limit": null,
          "has_single_limit": false,
          "single_limit": null
        }
      }
    ],
    "api_key_members": [
      {
        "api_key_id": "uuid-here",
        "label": "Production Key",
        "key_prefix": "sk_live_ab",
        "role": "admin",
        "is_active": true,
        "linked_at": "2025-03-01T10:00:00.000Z",
        "settings": {
          "hide_balance": false,
          "has_daily_limit": true,
          "daily_limit": "1000000.00",
          "has_monthly_limit": false,
          "monthly_limit": null,
          "has_single_limit": false,
          "single_limit": null
        }
      }
    ],
    "total": 4
  }
}
```

---

## Add Member

Add a new member to the wallet by their PayID. The member will be added with the `member` role.

```
POST /v1/checkout/wallet/members
```

### Authentication

Secret key required. `transfers` permission required. Admin role required.

### Request Body

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pay_id` | string | Yes | The PayID of the entity to add (e.g. `john.personal`) |

::: info
Admin API keys can only add members. They cannot promote members to admin — only the wallet owner can do that from the dashboard.
:::

### Example Request

::: code-group

```bash [cURL]
curl -X POST https://api.zevpaycheckout.com/v1/checkout/wallet/members \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{ "pay_id": "jane.personal" }'
```

```javascript [Node.js]
const response = await fetch('https://api.zevpaycheckout.com/v1/checkout/wallet/members', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_secret_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ pay_id: 'jane.personal' }),
});
const { data } = await response.json();
```

```python [Python]
import requests

response = requests.post(
    'https://api.zevpaycheckout.com/v1/checkout/wallet/members',
    headers={'Authorization': 'Bearer sk_live_your_secret_key'},
    json={'pay_id': 'jane.personal'},
)
```

:::

### Response

```json
{
  "success": true,
  "data": {
    "success": true,
    "message": "Member added to wallet"
  }
}
```

---

## Remove Member

Remove a member from the wallet by their PayID.

```
DELETE /v1/checkout/wallet/members/:payId
```

### Authentication

Secret key required. `transfers` permission required. Admin role required.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `payId` | string | The PayID of the member to remove (e.g. `jane.personal`) |

::: warning Restrictions
- Admin API keys **cannot** remove the wallet owner
- Admin API keys **cannot** remove other admins — only the wallet owner can
- Admin API keys can only remove members with the `member` role
:::

### Example Request

::: code-group

```bash [cURL]
curl -X DELETE https://api.zevpaycheckout.com/v1/checkout/wallet/members/jane.personal \
  -H "Authorization: Bearer sk_live_your_secret_key"
```

```javascript [Node.js]
const response = await fetch('https://api.zevpaycheckout.com/v1/checkout/wallet/members/jane.personal', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer sk_live_your_secret_key',
  },
});
const { data } = await response.json();
```

```python [Python]
import requests

response = requests.delete(
    'https://api.zevpaycheckout.com/v1/checkout/wallet/members/jane.personal',
    headers={'Authorization': 'Bearer sk_live_your_secret_key'},
)
```

:::

### Response

```json
{
  "success": true,
  "data": {
    "success": true,
    "message": "Member removed from wallet"
  }
}
```

---

## Update Member Settings

Update a member's individual settings including notification preferences, balance visibility, and spending limits.

```
PATCH /v1/checkout/wallet/members/:payId
```

### Authentication

Secret key required. `transfers` permission required. Admin role required.

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `payId` | string | The PayID of the member to update (e.g. `jane.personal`) |

### Request Body

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `enable_notification` | boolean | No | Enable/disable notifications for this member |
| `hide_wallet_balance` | boolean | No | Hide the wallet balance from this member |
| `has_daily_limit` | boolean | No | Enable daily spending limit |
| `daily_limit` | number | No | Daily spending limit in naira (required when `has_daily_limit` is true) |
| `has_monthly_limit` | boolean | No | Enable monthly spending limit |
| `monthly_limit` | number | No | Monthly spending limit in naira |
| `has_single_limit` | boolean | No | Enable per-transaction spending limit |
| `single_limit` | number | No | Per-transaction spending limit in naira |

::: warning Restrictions
- Admin API keys can only update settings for members with the `member` role
- Cannot update the wallet owner's settings
- Cannot update other admins' settings
- Role changes are not available via the API — only the wallet owner can change roles from the dashboard
:::

### Example Request

::: code-group

```bash [cURL]
curl -X PATCH https://api.zevpaycheckout.com/v1/checkout/wallet/members/jane.personal \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "hide_wallet_balance": true,
    "has_daily_limit": true,
    "daily_limit": 50000
  }'
```

```javascript [Node.js]
const response = await fetch('https://api.zevpaycheckout.com/v1/checkout/wallet/members/jane.personal', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer sk_live_your_secret_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    hide_wallet_balance: true,
    has_daily_limit: true,
    daily_limit: 50000,
  }),
});
const { data } = await response.json();
```

```python [Python]
import requests

response = requests.patch(
    'https://api.zevpaycheckout.com/v1/checkout/wallet/members/jane.personal',
    headers={'Authorization': 'Bearer sk_live_your_secret_key'},
    json={
        'hide_wallet_balance': True,
        'has_daily_limit': True,
        'daily_limit': 50000,
    },
)
```

:::

### Response

```json
{
  "success": true,
  "data": {
    "success": true,
    "message": "Member settings updated"
  }
}
```

---

## Error Codes

| Status | Code | Description |
|--------|------|-------------|
| `401` | Unauthorized | Missing or invalid API key |
| `403` | Forbidden | Not a secret key, no wallet linked, programmable debit disabled, or insufficient permissions |
| `403` | Forbidden | API key is not an admin on the wallet |
| `403` | Forbidden | Cannot manage admins or the wallet owner (admin can only manage members) |
| `400` | Bad Request | Validation error, member already exists, or cannot remove owner |
| `404` | Not Found | Member not found in wallet, or PayID does not exist |

### Permission Hierarchy

| Role | Can manage members | Can manage admins | Can manage owner | Can change roles |
|------|-------------------|-------------------|------------------|------------------|
| **Owner** (dashboard only) | Yes | Yes | Self only | Yes |
| **Admin** (API or dashboard) | Yes | No | No | No |
| **Member** | No | No | No | No |

## Try it — Get Wallet

<ApiPlayground
  method="GET"
  endpoint="/v1/checkout/wallet"
  authType="bearer"
/>

## Try it — List Members

<ApiPlayground
  method="GET"
  endpoint="/v1/checkout/wallet/members"
  authType="bearer"
/>

## Try it — Add Member

<ApiPlayground
  method="POST"
  endpoint="/v1/checkout/wallet/members"
  authType="bearer"
  :bodyFields="[
    { name: 'pay_id', type: 'string', required: true, placeholder: 'jane.personal', description: 'PayID of entity to add' },
  ]"
/>