Wallets API

The Wallets API provides comprehensive access to client wallet information, enabling balance queries, wallet listing, and detailed wallet metadata retrieval for multi-currency transaction management.

Overview

The Wallets API consists of two main endpoints:

• List Wallets - Retrieve all wallets for the authenticated client with filtering options
• Get Wallet by ID - Get detailed information for a specific wallet including current balance

All wallet endpoints require authentication and return data in a consistent JSON format with real-time balance information.

List Wallets

Retrieve a paginated list of wallets for the authenticated client with optional filtering by currency, type, and status.

Endpoint

GET /api/v1/wallets

Authentication: API Key + Secret required

Query Parameters

Sort Object Format

{
  "field": "id",        // Options: "id", "amount", "created_at", "updated_at"
  "direction": "DESC"   // Options: "ASC" or "DESC"
}

Response

Success Response (200 OK)

Headers:

X-Page: 1
X-Per-Page: 50
X-Total-Count: 5
X-Total-Pages: 1
X-Page-Size: 50
X-Has-More: false

Response Body:

[
  {
    "id": 101,
    "currency_id": 1,
    "amount": 5000.00,
    "type": "PREPAID"
  },
  {
    "id": 102,
    "currency_id": 2,
    "amount": 2500.50,
    "type": "PREPAID"
  },
  {
    "id": 103,
    "currency_id": 3,
    "amount": 10000.00,
    "type": "POSTPAID"
  }
]

Response Fields

Error Responses

400 Bad Request

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid query parameters"
  }
}

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired authentication token"
  }
}

500 Internal Server Error

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Could not retrieve wallets"
  }
}

Examples

# List wallets filtered by currency
curl -X GET "{{host}}/api/v1/wallets?currency_id=1&limit=10" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here" \
  -H "Accept: application/json"

Get Wallet by ID

Retrieve detailed information for a specific wallet including current balance, currency details, and wallet metadata.

Endpoint

GET /api/v1/wallets/:id

Authentication: API Key + Secret required

Path Parameters

Response

Success Response (200 OK)

{
  "id": 101,
  "currency_id": 1,
  "amount": 5000.00,
  "type": "PREPAID"
}

Response Fields

Error Responses

400 Bad Request

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid wallet ID"
  }
}

404 Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Wallet not found"
  }
}

500 Internal Server Error

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Failed to retrieve wallet"
  }
}

Examples

# Get specific wallet by ID
curl -X GET "{{host}}/api/v1/wallets/101" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here" \
  -H "Accept: application/json"

Implementation Notes

Balance Precision

Wallet balances are returned with precision appropriate to the currency:

• Fiat currencies: 2 decimal places (e.g., USD: 100.50)
• Zero-decimal currencies: No decimal places (e.g., JPY: 1000)

Wallet Types

PREPAID Wallets

• Pre-funded wallet type for purchases
• Requires balance to be loaded before making purchases
• Funds must be available before transaction execution
• Real-time balance deduction on purchase
• Subject to transaction limits based on client configuration

POSTPAID Wallets

• Credit-based wallet type allowing purchases on credit
• Transactions allowed up to configured credit limit
• Balance can be negative up to the credit limit
• Requires periodic settlement/payment
• Typically used for enterprise/corporate clients with credit arrangements

Security Considerations

Access Control

• Clients can only access their own wallets
• Admin users may have cross-client visibility
• Wallet IDs are globally unique and non-guessable

Balance Consistency

• Balances are calculated in real-time from transaction ledger
• All operations are atomic to prevent race conditions
• Implements optimistic locking for concurrent updates

Rate Limiting

The Wallets API implements the following rate limits:

• List Wallets: 1000 requests per minute
• Get Wallet by ID: 2000 requests per minute
• Rate limits are applied per client authentication token

Caching Recommendations

For optimal performance:

• Cache wallet list for up to 5 minutes
• Cache individual wallet details for up to 1 minute
• Always verify balance before initiating transactions
• Implement cache invalidation on transaction events

Integration Examples

# List all wallets
curl -X GET "{{host}}/api/v1/wallets?limit=100&is_active=true" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here" \
  -H "Accept: application/json"

# Get specific wallet
curl -X GET "{{host}}/api/v1/wallets/101" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here" \
  -H "Accept: application/json"

# Filter wallets by currency
curl -X GET "{{host}}/api/v1/wallets?currency_id=1&limit=50" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here" \
  -H "Accept: application/json"

# Filter by wallet type
curl -X GET "{{host}}/api/v1/wallets?type=PREPAID" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here" \
  -H "Accept: application/json"

Webhook Events

The Wallets API can trigger the following webhook events:

FAQ

Q: How many wallets can a client have? A: Clients can have one wallet per currency, with no limit on the number of different currencies supported.

Q: Can I transfer funds between wallets? A: Yes, wallet-to-wallet transfers are supported through the Transactions API, subject to forex rates for cross-currency transfers.

Q: What happens to wallet balance when an order fails? A: Failed orders trigger automatic refunds, returning the full amount to the source wallet within 24 hours.

Q: How are negative balances handled? A: The system prevents negative balances through pre-authorization checks. All transactions verify sufficient balance before processing.

Q: Can wallets be deleted? A: Wallets cannot be deleted but can be deactivated. Deactivated wallets retain their balance and transaction history for audit purposes.