Skip to main content
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.

​
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