Skip to main content

​
Endpoint

GET /wallets/{id}

​
Description

Use this endpoint to fetch the current state of a wallet. The response includes balance information, associated customer and account IDs, payment methods, wallet status, and lifecycle events.

​
Path Parameters

ParameterTypeRequiredDescription
idstring (UUID)YesUnique identifier of the wallet

​
Response

​
Success Response (200 OK)

{
  "data": {
    "account_id": "f55ca88c-71aa-4dab-a10a-4d818c11e8e6",
    "balance": {
      "amount": 0,
      "currency": "USD"
    },
    "customer_id": "a08bf5a3-8459-4e65-a5bb-34a1feef94cf",
    "events": [
      {
        "action": "create",
        "id": "6a2a5833-609d-4dff-a4e6-0eaf452d7826",
        "inserted_at": "2025-07-24T08:08:07Z",
        "reason": null,
        "wallet_id": "55a76a42-ed3a-4d0b-b74c-2887d64612f6"
      }
    ],
    "id": "3d2e3f3e-3b3c-4907-a4fd-e241203440d7",
    "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"
      }
    ],
    "status": "active"
  }
}

​
Response Fields

​
Wallet Information

FieldTypeDescription
idstringWallet ID
statusstringCurrent wallet status
customer_idstringCustomer associated with the wallet
account_idstringInternal account identifier

​
Balance

FieldTypeDescription
balance.amountnumberCurrent wallet balance
balance.currencystringWallet currency

​
Payment Methods

FieldTypeDescription
payment_methodsarrayList of payment methods linked to the wallet
account_namestringName on the bank account
account_numberstringBank account number
account_typestringType of bank account (e.g., savings, current)
bank_namestringName of the bank
bank_codestringBank routing or institution code
bank_addressstringBank branch address
Sensitive fields may be partially masked depending on environment and permissions.

​
Events

FieldTypeDescription
eventsarrayHistorical actions performed on the wallet
actionstringEvent type (e.g., create, freeze, delete)
inserted_atstring (ISO 8601)Timestamp of the event
reasonstringReason for the action, if provided

​
Example cURL Request

curl -X GET https://api.yourdomain.com/wallets/{id} \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Common Errors

Status CodeDescription
401Unauthorized
404Wallet not found
403Access denied

​
Use Cases

  • Display wallet details in a dashboard
  • Check wallet balance and status before transactions
  • Review linked payment methods
  • Audit wallet activity and lifecycle events

​
Notes & Best Practices

  • Always confirm wallet status before initiating funding or payouts.
  • Cache wallet responses carefully to avoid stale balance data.
  • Use wallet events for audit logs and compliance reviews.