Wallet Management API

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

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:

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

See 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

cURLNode.jsPython

bash

curl https://api.zevpaycheckout.com/v1/checkout/wallet \
  -H "Authorization: Bearer sk_live_your_secret_key"

javascript

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

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

cURLNode.jsPython

bash

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

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

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

cURLNode.jsPython

bash

curl https://api.zevpaycheckout.com/v1/checkout/wallet/members \
  -H "Authorization: Bearer sk_live_your_secret_key"

javascript

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

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

cURLNode.jsPython

bash

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

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

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`)

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

cURLNode.jsPython

bash

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

javascript

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

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

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

cURLNode.jsPython

bash

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

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

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

API Playground

GEThttps://api.zevpaycheckout.com/v1/checkout/wallet

API Key Stored locally in your browser

Try it — List Members

API Playground

GEThttps://api.zevpaycheckout.com/v1/checkout/wallet/members

API Key Stored locally in your browser

Try it — Add Member

API Playground

POSThttps://api.zevpaycheckout.com/v1/checkout/wallet/members

API Key Stored locally in your browser

Request Body

pay_id *string

Wallet Management API ​

Authentication ​

Get Wallet ​

Authentication ​

Example Request ​

Response ​

Response Fields ​

Update Wallet Settings ​

Authentication ​

Request Body ​

Example Request ​

Response ​

List Members ​

Authentication ​

Example Request ​

Response ​

Add Member ​

Authentication ​

Request Body ​

Example Request ​

Response ​

Remove Member ​

Authentication ​

Path Parameters ​

Example Request ​

Response ​

Update Member Settings ​

Authentication ​

Path Parameters ​

Request Body ​

Example Request ​

Response ​

Error Codes ​

Permission Hierarchy ​

Try it — Get Wallet ​

Try it — List Members ​

Try it — Add Member ​

Wallet Management API

Authentication

Get Wallet

Authentication

Example Request

Response

Response Fields

Update Wallet Settings

Authentication

Request Body

Example Request

Response

List Members

Authentication

Example Request

Response

Add Member

Authentication

Request Body

Example Request

Response

Remove Member

Authentication

Path Parameters

Example Request

Response

Update Member Settings

Authentication

Path Parameters

Request Body

Example Request

Response

Error Codes

Permission Hierarchy

Try it — Get Wallet

Try it — List Members

Try it — Add Member