Authenticated API

This endpoint requires a valid JWT Bearer token. Accessible via the API gateway at /v1/commerce/*.

Digital Wallet API

Manage digital wallets, gift cards, stored value accounts, and balance operations.

Authentication Required

All endpoints require a valid Bearer token. See Authentication for details.

Overview

Attribute	Value
Base Path	`/api/v1/wallet`
Authentication	Bearer Token
Required Roles	`customer`, `customer_support`, `system_admin`, `super_admin`

Wallet Types

Type	Description
`customer_wallet`	Customer stored value account
`gift_card`	Physical or digital gift card
`store_credit`	Refund/credit balance
`promotional`	Promotional balance
`rewards`	Loyalty rewards balance

Customer Wallets

Get Customer Wallet

Retrieve customer's wallet balances.

GET /api/v1/wallet/customers/{customer_id}

Response

{
  "customer_id": "cust_abc",
  "wallets": [
    {
      "id": "wallet_001",
      "type": "customer_wallet",
      "name": "Main Wallet",
      "balance": 45.50,
      "currency": "USD",
      "status": "active",
      "created_at": "2025-06-01T00:00:00Z"
    },
    {
      "id": "wallet_002",
      "type": "store_credit",
      "name": "Store Credit",
      "balance": 12.99,
      "currency": "USD",
      "expires_at": "2026-06-01T00:00:00Z",
      "status": "active"
    },
    {
      "id": "wallet_003",
      "type": "rewards",
      "name": "Reward Points",
      "balance": 500,
      "currency": "points",
      "point_value_usd": 5.00,
      "status": "active"
    }
  ],
  "total_balance_usd": 63.49
}

Create Wallet

Create a new wallet for a customer.

POST /api/v1/wallet/customers/{customer_id}/wallets

Request Body

{
  "type": "customer_wallet",
  "name": "Main Wallet",
  "initial_balance": 0,
  "currency": "USD"
}

Add Funds

Add funds to a wallet.

POST /api/v1/wallet/{wallet_id}/add-funds

Request Body

{
  "amount": 50.00,
  "payment_method_id": "pm_abc123",
  "description": "Wallet top-up"
}

Response

{
  "transaction_id": "txn_xyz",
  "wallet_id": "wallet_001",
  "type": "credit",
  "amount": 50.00,
  "new_balance": 95.50,
  "payment_id": "pay_abc",
  "created_at": "2026-01-24T19:00:00Z"
}

Redeem Balance

Use wallet balance for payment.

POST /api/v1/wallet/{wallet_id}/redeem

Request Body

{
  "amount": 25.00,
  "order_id": "ord_xyz",
  "description": "Order payment"
}

Response

{
  "transaction_id": "txn_abc",
  "wallet_id": "wallet_001",
  "type": "debit",
  "amount": 25.00,
  "new_balance": 70.50,
  "order_id": "ord_xyz",
  "created_at": "2026-01-24T19:05:00Z"
}

Transfer Balance

Transfer between wallets.

POST /api/v1/wallet/transfer

Request Body

{
  "from_wallet_id": "wallet_001",
  "to_wallet_id": "wallet_004",
  "amount": 20.00,
  "description": "Transfer to family member"
}

Gift Cards

Create Gift Card

Issue a new gift card.

POST /api/v1/wallet/gift-cards

Request Body

{
  "amount": 50.00,
  "currency": "USD",
  "type": "digital",
  "recipient": {
    "email": "recipient@example.com",
    "name": "Jane Doe"
  },
  "sender": {
    "name": "John Doe",
    "message": "Happy Birthday!"
  },
  "deliver_at": "2026-02-01T09:00:00Z"
}

Response

{
  "gift_card_id": "gc_abc123",
  "code": "GIFT-XXXX-XXXX-XXXX",
  "amount": 50.00,
  "balance": 50.00,
  "status": "active",
  "type": "digital",
  "delivery_status": "scheduled",
  "deliver_at": "2026-02-01T09:00:00Z",
  "expires_at": null,
  "created_at": "2026-01-24T19:00:00Z"
}

Lookup Gift Card

Check gift card balance.

GET /api/v1/wallet/gift-cards/lookup

Query Parameters

Parameter	Type	Description
`code`	string	Gift card code
`pin`	string	PIN if required

Response

{
  "gift_card_id": "gc_abc123",
  "code": "GIFT-****-****-1234",
  "balance": 35.50,
  "currency": "USD",
  "status": "active",
  "expires_at": null,
  "restrictions": {
    "location_ids": null,
    "item_categories": null
  }
}

Gift Card Status Values

Status	Description
`pending`	Not yet activated
`active`	Ready to use
`redeemed`	Fully used
`expired`	Past expiration
`cancelled`	Cancelled/voided

Redeem Gift Card

Apply gift card to order.

POST /api/v1/wallet/gift-cards/{gift_card_id}/redeem

Request Body

{
  "amount": 25.00,
  "order_id": "ord_xyz",
  "pin": "1234"
}

Activate Physical Card

Activate a physical gift card.

POST /api/v1/wallet/gift-cards/activate

Request Body

{
  "code": "GIFT-XXXX-XXXX-XXXX",
  "amount": 50.00
}

List Gift Cards

Get gift cards for merchant.

GET /api/v1/wallet/gift-cards

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status
`type`	string	`digital`, `physical`
`date_from`	date	Created after
`date_to`	date	Created before

Store Credits

Issue Store Credit

Issue credit to customer.

POST /api/v1/wallet/store-credit

Request Body

{
  "customer_id": "cust_abc",
  "amount": 15.99,
  "reason": "refund",
  "order_id": "ord_xyz",
  "expires_in_days": 365,
  "notes": "Item out of stock refund"
}

Response

{
  "credit_id": "credit_001",
  "wallet_id": "wallet_002",
  "amount": 15.99,
  "balance": 28.98,
  "reason": "refund",
  "expires_at": "2027-01-24T00:00:00Z",
  "created_at": "2026-01-24T19:00:00Z"
}

Store Credit Reasons

Reason	Description
`refund`	Order refund
`complaint`	Customer complaint resolution
`promotion`	Promotional credit
`goodwill`	Goodwill gesture
`adjustment`	Manual adjustment

Promotional Balance

Issue Promotional Credit

POST /api/v1/wallet/promotional

Request Body

{
  "customer_id": "cust_abc",
  "amount": 10.00,
  "campaign_id": "camp_001",
  "expires_at": "2026-02-28T23:59:59Z",
  "restrictions": {
    "min_order_amount": 25.00,
    "excluded_categories": ["alcohol"]
  }
}

Transaction History

Get Transactions

Retrieve wallet transaction history.

GET /api/v1/wallet/{wallet_id}/transactions

Query Parameters

Parameter	Type	Description
`type`	string	`credit`, `debit`, `adjustment`
`start_date`	date	Filter start
`end_date`	date	Filter end
`limit`	integer	Results per page

Response

{
  "data": [
    {
      "id": "txn_001",
      "type": "debit",
      "amount": 25.00,
      "balance_after": 70.50,
      "description": "Order payment",
      "order_id": "ord_xyz",
      "created_at": "2026-01-24T19:05:00Z"
    },
    {
      "id": "txn_002",
      "type": "credit",
      "amount": 50.00,
      "balance_after": 95.50,
      "description": "Wallet top-up",
      "payment_id": "pay_abc",
      "created_at": "2026-01-24T19:00:00Z"
    }
  ],
  "has_more": true
}

Balance Adjustments

Adjust Balance

Make a manual balance adjustment.

POST /api/v1/wallet/{wallet_id}/adjust

Request Body

{
  "amount": -5.00,
  "reason": "correction",
  "notes": "Duplicate credit correction",
  "admin_id": "admin_001"
}

Analytics

Get Wallet Analytics

GET /api/v1/wallet/analytics

Query Parameters

Parameter	Type	Description
`start_date`	date	Analysis start
`end_date`	date	Analysis end

Response

{
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-24"
  },
  "summary": {
    "total_liability": 125000.00,
    "gift_card_liability": 75000.00,
    "store_credit_liability": 35000.00,
    "promotional_liability": 15000.00
  },
  "activity": {
    "funds_added": 45000.00,
    "funds_redeemed": 38000.00,
    "gift_cards_sold": 150,
    "gift_cards_sold_value": 8500.00,
    "redemption_rate": 84.4
  },
  "top_users": [
    {
      "customer_id": "cust_001",
      "total_balance": 250.00,
      "redemptions_count": 12
    }
  ]
}

Bulk Operations

Bulk Issue Gift Cards

POST /api/v1/wallet/gift-cards/bulk

Request Body

{
  "count": 100,
  "amount": 25.00,
  "type": "physical",
  "prefix": "HOLIDAY",
  "expires_at": "2026-12-31T23:59:59Z"
}

Response

{
  "batch_id": "batch_001",
  "count": 100,
  "total_value": 2500.00,
  "download_url": "https://...",
  "created_at": "2026-01-24T19:00:00Z"
}

Webhooks

Event	Description
`wallet.funds_added`	Balance increased
`wallet.funds_redeemed`	Balance used
`wallet.low_balance`	Below threshold
`gift_card.purchased`	New gift card
`gift_card.redeemed`	Gift card used
`gift_card.delivered`	Digital card sent
`store_credit.issued`	Credit issued
`store_credit.expiring`	Credit expiring soon

Error Responses

Status	Code	Description
400	`insufficient_balance`	Not enough funds
400	`card_expired`	Gift card expired
400	`invalid_pin`	Incorrect PIN
404	`wallet_not_found`	Wallet ID not found
404	`gift_card_not_found`	Gift card not found
409	`card_already_redeemed`	Card fully used

Gift Cards API - Gift card management
Payments API - Payment processing
Customers API - Customer management

Overview​

Wallet Types​

Customer Wallets​

Get Customer Wallet​

Create Wallet​

Add Funds​

Redeem Balance​

Transfer Balance​

Gift Cards​

Create Gift Card​

Lookup Gift Card​

Gift Card Status Values​

Redeem Gift Card​

Activate Physical Card​

List Gift Cards​

Store Credits​

Issue Store Credit​

Store Credit Reasons​

Promotional Balance​

Issue Promotional Credit​

Transaction History​

Get Transactions​

Balance Adjustments​

Adjust Balance​

Analytics​

Get Wallet Analytics​

Bulk Operations​

Bulk Issue Gift Cards​

Webhooks​

Error Responses​

Related Documentation​

Overview

Wallet Types

Customer Wallets

Get Customer Wallet

Create Wallet

Add Funds

Redeem Balance

Transfer Balance

Gift Cards

Create Gift Card

Lookup Gift Card

Gift Card Status Values

Redeem Gift Card

Activate Physical Card

List Gift Cards

Store Credits

Issue Store Credit

Store Credit Reasons

Promotional Balance

Issue Promotional Credit

Transaction History

Get Transactions

Balance Adjustments

Adjust Balance

Analytics

Get Wallet Analytics

Bulk Operations

Bulk Issue Gift Cards

Webhooks

Error Responses

Related Documentation