---
description: >-
  Create wallets, retrieve wallet details, check real-time balances, and
  fetch paginated transaction statements using the Wallets API.
---

# Wallet Management

This page covers wallet lifecycle operations: creating wallets, retrieving wallet details, checking balances, and fetching transaction history.

---

## Create a Wallet

### Endpoint

```
POST https://{FQDN}/wallets
```

**Headers:**

| Header | Value |
|---|---|
| `Authorization` | `Bearer {accessToken}` |
| `Content-Type` | `application/json` |

### Request

| Field | Type | Required | Description |
|---|---|---|---|
| `accountAsset` | string | ❌ | Currency or asset code for the wallet (e.g., `"USD"`, `"BRL"`) |
| `ownerId` | string | ❌ | Identifier for the wallet owner |
| `beneficiaryId` | string | ❌ | Identifier for the beneficiary |
| `type` | string | ❌ | Wallet type (e.g., `"PERSONAL"`, `"BUSINESS"`) |
| `additionalInfo` | object | ❌ | Arbitrary metadata to attach to the wallet |

### Example Request

```bash
curl -X POST https://{FQDN}/wallets \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountAsset": "USD",
    "ownerId": "user-12345",
    "beneficiaryId": "user-12345",
    "type": "PERSONAL"
  }'
```

### Response (200)

```json
{
  "walletId": "w-a1b2c3d4-e5f6-7890",
  "accountAsset": "USD",
  "ownerId": "user-12345",
  "beneficiaryId": "user-12345",
  "type": "PERSONAL",
  "status": "ACTIVE",
  "createdAt": "2025-03-31T10:00:00Z"
}
```

---

## Get Wallet Details

### Endpoint

```
GET https://{FQDN}/wallets/{walletId}
```

**Headers:**

| Header | Value |
|---|---|
| `Authorization` | `Bearer {accessToken}` |

### Path Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `walletId` | string | ✅ | The wallet identifier |

### Example Request

```bash
curl -X GET https://{FQDN}/wallets/w-a1b2c3d4-e5f6-7890 \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'
```

### Response (200)

```json
{
  "walletId": "w-a1b2c3d4-e5f6-7890",
  "accountAsset": "USD",
  "ownerId": "user-12345",
  "beneficiaryId": "user-12345",
  "type": "PERSONAL",
  "status": "ACTIVE",
  "createdAt": "2025-03-31T10:00:00Z"
}
```

---

## Get Wallet Balance

### Endpoint

```
GET https://{FQDN}/wallets/{walletId}/balance
```

**Headers:**

| Header | Value |
|---|---|
| `Authorization` | `Bearer {accessToken}` |

### Path Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `walletId` | string | ✅ | The wallet identifier |

### Example Request

```bash
curl -X GET https://{FQDN}/wallets/w-a1b2c3d4-e5f6-7890/balance \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'
```

### Response (200)

```json
{
  "walletId": "w-a1b2c3d4-e5f6-7890",
  "accountAsset": "USD",
  "availableBalance": 1250.75,
  "heldBalance": 200.00,
  "totalBalance": 1450.75
}
```

| Field | Type | Description |
|---|---|---|
| `availableBalance` | number | Funds available for transactions |
| `heldBalance` | number | Funds reserved by pending holds |
| `totalBalance` | number | Sum of available and held balances |

---

## Get Wallet Statement

Retrieve a paginated transaction history for a wallet, with optional date-range filtering.

### Endpoint

```
GET https://{FQDN}/wallets/{walletId}/statement
```

**Headers:**

| Header | Value |
|---|---|
| `Authorization` | `Bearer {accessToken}` |

### Path Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `walletId` | string | ✅ | The wallet identifier |

### Query Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `from` | string | ❌ | Start date (ISO 8601, e.g., `"2025-03-01"`) |
| `until` | string | ❌ | End date (ISO 8601, e.g., `"2025-03-31"`) |
| `page` | integer | ❌ | Page number (zero-based) |
| `size` | integer | ❌ | Results per page |

### Example Request

```bash
curl -X GET 'https://{FQDN}/wallets/w-a1b2c3d4-e5f6-7890/statement?from=2025-03-01&until=2025-03-31&page=0&size=20' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'
```

### Response (200)

```json
{
  "walletId": "w-a1b2c3d4-e5f6-7890",
  "entries": [
    {
      "transactionId": "txn-001",
      "externalId": "order-5001",
      "type": "CREDIT",
      "amount": 500.00,
      "description": "Wallet top-up",
      "balanceAfter": 1450.75,
      "createdAt": "2025-03-15T14:30:00Z"
    },
    {
      "transactionId": "txn-002",
      "externalId": "order-5002",
      "type": "DEBIT",
      "amount": 49.25,
      "description": "Payment to merchant",
      "balanceAfter": 1401.50,
      "createdAt": "2025-03-16T09:15:00Z"
    }
  ],
  "page": 0,
  "size": 20,
  "totalEntries": 2
}
```

## What's Next

- [Transactions and transfers](transactions.md) — Execute wallet transactions, holds, and wallet-to-wallet transfers
- [Balance](../balance.md) — Check payer balance across all providers