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": "req-1",
  "success": true,
  "status": 200,
  "errors": [],
  "data": {
    "content": [
      {
        "__type__": "Wallet",
        "Id": "5c7b9e31-2d4f-4a80-b6c3-9f1e8d0a7b52",
        "Title": "Acme prepaid wallet",
        "AccountId": "11111111-1111-1111-1111-111111111111",
        "CustomerId": "cus_NffrFeUfNV2Hib"
      }
    ],
    "totalElements": 1,
    "size": 20,
    "number": 0
  }
}

Get wallet

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

Response 200

{
  "id": "5c7b9e31-2d4f-4a80-b6c3-9f1e8d0a7b52",
  "title": "Acme prepaid wallet",
  "accountId": "11111111-1111-1111-1111-111111111111",
  "currency": "USD",
  "unit": "USD",
  "balance": 1500.0,
  "availableBalance": 1450.0,
  "reservedBalance": 50.0,
  "frozenAmount": 0,
  "isActive": true,
  "approvalStatus": "Approved",
  "customerId": "cus_NffrFeUfNV2Hib",
  "enableDisableTopUp": true,
  "thresholdTopUpAmount": 100.0,
  "autoTopUpAmount": 500.0
}

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