Wallets

External CRUD for billing wallets.

Wallets

Prefix: /api/v1/external/wallets

See Overview for authentication, pagination, and errors.

Flat CRUD for the billing Wallet object. Top-up and drawdown operations remain on the existing wallet operational APIs; this API manages wallet records.

Endpoint summary

Method	Path
GET	`/wallets`
GET	`/wallets/{walletId}`
POST	`/wallets`
PUT	`/wallets/{walletId}`
DELETE	`/wallets/{walletId}`

List wallets

GET /api/v1/external/wallets?page=0&size=20&q=acme
Authorization: Bearer YOUR_API_TOKEN

Query	Description
`page`	0-based page index (default `0`)
`size`	Page size (default 20, max 20)
`q`	Optional search on `title` and `customerId` (Stripe Customer ID)

Response 200 — ApiResponse + Spring Page. See Overview.

{
  "requestId": "00000000-0000-0000-0000-000000000001",
  "success": true,
  "status": 200,
  "errors": [],
  "data": {
    "content": [
      {
        "__type__": "Wallet",
        "Id": "11111111-1111-1111-1111-111111111111",
        "Type": null,
        "Unit": null,
        "Level": null,
        "Title": "Acme prepaid wallet",
        "OrgId": "33333333-3333-3333-3333-333333333333",
        "OrgId__r": {
          "Name": "Acme Corporation"
        },
        "Balance": 100,
        "Deleted": false,
        "IsActive": null,
        "AccountId": "44444444-4444-4444-4444-444444444444",
        "CreatedAt": "2026-01-15T10:00:00.000000",
        "CreatedBy": null,
        "ServiceId": null,
        "UpdatedAt": "2026-01-15T10:00:00.000000",
        "UpdatedBy": null,
        "CurrencyId": "55555555-5555-5555-5555-555555555555",
        "CurrencyId__r": {
          "Name": "United States Dollar"
        },
        "CustomerId": null,
        "FailureCount": null,
        "FrozenAmount": null,
        "Classification": null,
        "HierarchyMode": null,
        "ApprovalStatus": null,
        "CustomerIdMc": null,
        "ReservedBalance": null,
        "AvailableBalance": null,
        "AutoTopUpAmount": null,
        "EnableDisableTopUp": null,
        "ClassificationBalances": null,
        "ThresholdTopUpAmount": null,
        "AutoTopUpAmountMcMc": null,
        "EnableDisableTopUpMc": null,
        "ThresholdTopUpAmountMc": null,
        "WalletExternalV1ReferenceidMc": null
      },
      {
        "__type__": "Wallet",
        "Id": "22222222-2222-2222-2222-222222222222",
        "Type": null,
        "Unit": null,
        "Level": null,
        "Title": "Demo wallet",
        "OrgId": "33333333-3333-3333-3333-333333333333",
        "OrgId__r": {
          "Name": "Acme Corporation"
        },
        "Balance": 50,
        "Deleted": false,
        "IsActive": null,
        "AccountId": "66666666-6666-6666-6666-666666666666",
        "CreatedAt": "2026-01-16T10:00:00.000000",
        "CreatedBy": null,
        "ServiceId": null,
        "UpdatedAt": "2026-01-16T10:00:00.000000",
        "UpdatedBy": null,
        "CurrencyId": "55555555-5555-5555-5555-555555555555",
        "CurrencyId__r": {
          "Name": "United States Dollar"
        },
        "CustomerId": null,
        "FailureCount": null,
        "FrozenAmount": null,
        "Classification": null,
        "HierarchyMode": null,
        "ApprovalStatus": null,
        "CustomerIdMc": null,
        "ReservedBalance": null,
        "AvailableBalance": null,
        "AutoTopUpAmount": null,
        "EnableDisableTopUp": null,
        "ClassificationBalances": null,
        "ThresholdTopUpAmount": null,
        "AutoTopUpAmountMcMc": null,
        "EnableDisableTopUpMc": null,
        "ThresholdTopUpAmountMc": null,
        "WalletExternalV1ReferenceidMc": null
      }
    ],
    "pageable": {
      "pageNumber": 0,
      "pageSize": 20,
      "sort": {
        "sorted": false,
        "unsorted": true,
        "empty": true
      },
      "offset": 0,
      "paged": true,
      "unpaged": false
    },
    "last": true,
    "totalElements": 2,
    "totalPages": 1,
    "first": true,
    "sort": {
      "sorted": false,
      "unsorted": true,
      "empty": true
    },
    "size": 20,
    "number": 0,
    "numberOfElements": 2,
    "empty": false
  }
}

Get wallet

GET /api/v1/external/wallets/{walletId}
Authorization: Bearer YOUR_API_TOKEN

Response 200

{
  "requestId": "00000000-0000-0000-0000-000000000002",
  "success": true,
  "status": 200,
  "errors": [],
  "data": {
    "__type__": "Wallet",
    "Id": "11111111-1111-1111-1111-111111111111",
    "Type": null,
    "Unit": null,
    "Level": null,
    "Title": "Acme prepaid wallet",
    "OrgId": "33333333-3333-3333-3333-333333333333",
    "Balance": 100,
    "Deleted": false,
    "IsActive": null,
    "AccountId": "44444444-4444-4444-4444-444444444444",
    "CreatedAt": "2026-01-15T10:00:00.000000",
    "CreatedBy": null,
    "ServiceId": null,
    "UpdatedAt": "2026-01-15T10:00:00.000000",
    "UpdatedBy": null,
    "CurrencyId": "55555555-5555-5555-5555-555555555555",
    "CustomerId": null,
    "FailureCount": null,
    "FrozenAmount": null,
    "Classification": null,
    "HierarchyMode": null,
    "ApprovalStatus": null,
    "CustomerIdMc": null,
    "ReservedBalance": null,
    "AvailableBalance": null,
    "AutoTopUpAmount": null,
    "EnableDisableTopUp": null,
    "ClassificationBalances": null,
    "ThresholdTopUpAmount": null,
    "AutoTopUpAmountMcMc": null,
    "EnableDisableTopUpMc": null,
    "ThresholdTopUpAmountMc": null,
    "WalletExternalV1ReferenceidMc": null,
    "OrgId__r": {
      "Name": "Acme Corporation"
    },
    "CurrencyId__r": {
      "Name": "United States Dollar"
    }
  }
}

Create wallet

POST /api/v1/external/wallets
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

Required fields: title, accountId. accountId must reference an existing billing account.

customerId is the Stripe Customer ID (stored as Wallet customer_id). It is optional; when sent it must be a non-blank string (for example cus_NffrFeUfNV2Hib). A blank value returns 400.

Request

{
  "title": "Acme prepaid wallet",
  "accountId": "11111111-1111-1111-1111-111111111111",
  "customerId": "cus_NffrFeUfNV2Hib",
  "currency": "USD",
  "unit": "USD",
  "isActive": true,
  "balance": 0,
  "availableBalance": 0
}

curl -sS -X POST "https://YOUR_TENANT_HOST/api/v1/external/wallets" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Acme prepaid wallet",
    "accountId": "11111111-1111-1111-1111-111111111111",
    "currency": "USD",
    "isActive": true
  }'

Response 201

{
  "id": "5c7b9e31-2d4f-4a80-b6c3-9f1e8d0a7b52",
  "title": "Acme prepaid wallet",
  "accountId": "11111111-1111-1111-1111-111111111111",
  "customerId": "cus_NffrFeUfNV2Hib",
  "currency": "USD",
  "unit": "USD",
  "isActive": true,
  "balance": 0,
  "availableBalance": 0
}

Response 409 on a duplicate title.

{
  "status": 409,
  "error": "Conflict",
  "message": "Wallet title already exists",
  "path": "uri=/api/v1/external/wallets"
}

Update wallet

PUT /api/v1/external/wallets/{walletId}
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

Request — turn on auto top-up.

{
  "title": "Acme prepaid wallet",
  "enableDisableTopUp": true,
  "thresholdTopUpAmount": 100.0,
  "autoTopUpAmount": 500.0
}

Response 200

{
  "id": "5c7b9e31-2d4f-4a80-b6c3-9f1e8d0a7b52",
  "title": "Acme prepaid wallet",
  "accountId": "11111111-1111-1111-1111-111111111111",
  "currency": "USD",
  "isActive": true,
  "enableDisableTopUp": true,
  "thresholdTopUpAmount": 100.0,
  "autoTopUpAmount": 500.0
}

Delete wallet

DELETE /api/v1/external/wallets/{walletId}
Authorization: Bearer YOUR_API_TOKEN

Response 204 — no body.

On this page