> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallets

Wallets hold a consumer's balance in a specific currency. You can list a consumer's wallets and credit or debit them via the API.

Below is a flow diagram that explains how to manage wallets.

<Frame>
  <img src="https://mintcdn.com/orbt/96Fd-vuJ5g0Urlz8/images/orbt-diagrams-Flow-4---Wallet-Credit-and-Debit.png?fit=max&auto=format&n=96Fd-vuJ5g0Urlz8&q=85&s=e90aa49a83a2b3bb63b64cb50f083982" alt="Orbt Diagrams Flow 4 Wallet Credit And Debit" width="801" height="841" data-path="images/orbt-diagrams-Flow-4---Wallet-Credit-and-Debit.png" />
</Frame>

## List consumer wallets

Returns all wallets belonging to a specific consumer, including balance, currency, and wallet type.

```text theme={null}
GET /api/partner/v1/customer/{customerId}/wallets
```

### Path parameters

* `customerId` (integer, required) — The consumer's ID, returned when the consumer was created

### Query parameters

* `page` (integer, optional) — Page number, zero-indexed. Default: `0`
* `size` (integer, optional) — Results per page. Default: `20`, max: `50`

### Example request

```text theme={null}
curl -X GET "https://partner.orbt.com/api/partner/v1/customer/101/wallets?page=0&size=50" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-client-id: YOUR_CLIENT_ID" \
  -H "x-timestamp: 2026-06-03T10:00:00.000Z" \
  -H "x-body-hash: BODY_HASH" \
  -H "x-signature: SIGNATURE"
```

### Success response (200)

```text theme={null}
{
  "content": [
    {
      "walletId": "101",
      "currency": "USD",
      "balance": 50.00,
      "walletType": "STANDARD",
      "status": "ENABLED"
    },
    {
      "walletId": "102",
      "currency": "USD",
      "balance": 100.00,
      "walletType": "CAMPAIGN",
      "campaignId": "18",
      "campaignName": "Employee of the Month",
      "status": "ENABLED"
    }
  ],
  "page": 0,
  "size": 20,
  "hasNext": false
}
```

### Error responses

* **403 Forbidden** — Authentication failed
* **422 Unprocessable Entity** — Invalid consumer ID or query parameters

## Credit or debit a wallet

Adds or deducts funds from a consumer's wallet. Credits are drawn from your partner wallet balance. Use a unique `referenceId` for each transaction — this is your idempotency key to prevent duplicate processing.

```text theme={null}
POST /api/partner/v1/wallets/{walletId}/transactions
```

### Path parameters

* `walletId` (string, required) — The wallet ID to update, returned from the consumer or wallet list endpoints

### Request body

* `amount` (number, required) — Amount to credit or debit
* `transactionType` (string, required) — `CREDIT` to add funds, `DEBIT` to deduct funds
* `referenceId` (string, required) — Your unique reference for this transaction. Used for idempotency — reusing the same ID with the same payload is safe; reusing it with a different payload will return an error.
* `description` (string, optional) — A note for your own records

### Example request — credit

```text theme={null}
curl -X POST https://partner.orbt.com/api/partner/v1/wallets/101/transactions \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-client-id: YOUR_CLIENT_ID" \
  -H "x-timestamp: 2026-06-03T10:00:00.000Z" \
  -H "x-body-hash: BODY_HASH" \
  -H "x-signature: SIGNATURE" \
  -d '{
    "amount": 25.00,
    "transactionType": "CREDIT",
    "referenceId": "reward-june-2026-jane",
    "description": "Q2 performance reward"
  }'
```

### Success response (200)

```text theme={null}
{
  "success": true,
  "data": {
    "walletId": 101,
    "currency": "USD",
    "previousBalance": 50.00,
    "transactionAmount": 25.00,
    "newBalance": 75.00,
    "transactionType": "CREDIT",
    "referenceId": "reward-june-2026-jane",
    "description": "Q2 performance reward",
    "timestamp": "2026-06-03T10:00:00Z"
  }
}
```

### Error responses

* **402 BUSINESS\_RULE\_ERROR** — Your partner wallet has insufficient funds to process this credit
* **403 BUSINESS\_RULE\_ERROR** — `referenceId` has already been used with a different payload (idempotency violation)
* **500 SYSTEM\_ERROR** — Consumer wallet has insufficient funds for a debit transaction