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.

Orbt Diagrams Flow 4 Wallet Credit And Debit

List consumer wallets

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

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

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)

{
  "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.

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

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)

{
  "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

Get Started

Platform

API

Use Cases

List consumer wallets

Path parameters

Query parameters

Example request

Success response (200)

Error responses

Credit or debit a wallet

Path parameters

Request body

Example request — credit

Success response (200)

Error responses

​List consumer wallets

​Path parameters

​Query parameters

​Example request

​Success response (200)

​Error responses

​Credit or debit a wallet

​Path parameters

​Request body

​Example request — credit

​Success response (200)

​Error responses

List consumer wallets

Path parameters

Query parameters

Example request

Success response (200)

Error responses

Credit or debit a wallet

Path parameters

Request body

Example request — credit

Success response (200)

Error responses