Update a wallet

curl --request PATCH \
  --url https://api.paystack.com/v1/wallets/{walletId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "label": "<string>",
  "metadata": {}
}
'

{
  "status": true,
  "message": "Wallet updated successfully",
  "code": "ok",
  "data": {
    "id": "wal_01HXYZABC1234567890ABCDEFG",
    "customer_id": "cust_01HXYZABC1234567890ABCDEFG",
    "currency": "USDC",
    "available_balance": "1234.567890",
    "pending_balance": "0.000000",
    "total_balance": "1234.567890",
    "metadata": {},
    "provisioned": false,
    "created_at": "2026-05-20T12:00:00.000Z",
    "updated_at": "2026-05-20T12:00:00.000Z",
    "label": "USDC Operating Wallet"
  },
  "meta": {
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

Wallets

Update a wallet

Partially updates an existing wallet. Returns the wallet in the same shape as POST /v1/wallets.

The path id is the GlobalStack external identifier (wal_…).

Mutable fields

label — non-empty string, max 255 chars.
metadata — free-form Record<string, string>.

Immutable fields

currency and customer_id cannot be changed. Including either (or any unknown field) in the request body fails validation with 400 bad_request. To move a wallet to a different currency, create a new wallet.

Semantics

label is replace-only. Omitting it leaves the stored label unchanged. Passing null (or an empty string) to clear it is rejected as 400 bad_request.
metadata is replaced whole-cloth when present. No deep merge — the new map fully replaces the stored map. {} clears it. Explicit null is rejected as 400 bad_request.
A body with neither label nor metadata is rejected as 400 invalid_input (nothing to update).

Errors

400 bad_request — class-validator failures: an immutable or unknown field (currency, customer_id, …) rejected; label set to null/empty; metadata set to null or a non-object.
400 invalid_input — malformed path id (wal_… prefix required); empty patch body with neither label nor metadata.
401 authentication_failed — invalid or missing API key.
404 not_found — wallet does not exist.

Example

PATCH /v1/wallets/wal_01HXYZABC1234567890ABCDEFG
{
  "label": "Treasury Wallet"
}

PATCH

wallets

{walletId}

Update a wallet

curl --request PATCH \
  --url https://api.paystack.com/v1/wallets/{walletId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "label": "<string>",
  "metadata": {}
}
'

{
  "status": true,
  "message": "Wallet updated successfully",
  "code": "ok",
  "data": {
    "id": "wal_01HXYZABC1234567890ABCDEFG",
    "customer_id": "cust_01HXYZABC1234567890ABCDEFG",
    "currency": "USDC",
    "available_balance": "1234.567890",
    "pending_balance": "0.000000",
    "total_balance": "1234.567890",
    "metadata": {},
    "provisioned": false,
    "created_at": "2026-05-20T12:00:00.000Z",
    "updated_at": "2026-05-20T12:00:00.000Z",
    "label": "USDC Operating Wallet"
  },
  "meta": {
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

Authorizations

Authorization

string

header

required

API key issued during merchant onboarding.

Path Parameters

walletId

string

required

Pattern: [^\/#\?]+?

Body

application/json

UpdateWalletDto

label

string

Required string length: 1 - 255

metadata

object

Response

Wallet updated successfully

status

enum<boolean>

required

Available options:

true

Example:

true

message

string

required

Human-readable summary

Example:

"Wallet updated successfully"

code

enum<string>

required

Available options:

ok

Example:

"ok"

data

object

required

Show child attributes