Wallets & Transactions

The Octopus Cards platform uses a prepaid wallet system. Every order is settled by deducting from your wallet balance. Each client can hold one wallet per currency, enabling multi-currency operations without manual conversion.

How Wallets Work

Client Account
├── USD Wallet  →  balance: $5,000.00
├── EUR Wallet  →  balance: €2,300.50
└── GBP Wallet  →  balance: £1,100.00

Wallets are created by your account manager when you onboard a new currency.
When you place an order, the cost is deducted from the wallet matching the product's currency.
Every credit (top-up) and debit (order, adjustment) is recorded as a transaction with a full audit trail.

Wallet Types

Type	Description
`PREPAID`	Balance must be sufficient before an order can be placed. This is the default.
`POSTPAID`	Orders are fulfilled on credit and settled periodically. Available by arrangement.

Transaction Types

Every wallet movement creates a transaction record:

Type	Direction	Example
`CREDIT`	Money in	Wallet top-up, refund
`DEBIT`	Money out	Order settlement, adjustment

Transaction Statuses

Status	Description
`COMPLETED`	Transaction is settled and the balance has been updated
`PENDING`	Transaction is awaiting processing (e.g. async order)
`FAILED`	Transaction did not complete (balance unchanged)

Top-ups

Wallet top-ups are performed by your account manager or via your admin dashboard — there is no public API endpoint for self-service top-ups. When a top-up is processed:

The specified amount is credited to the target wallet
A CREDIT transaction is created with status COMPLETED
The wallet balance is updated atomically (balance update + transaction + ledger entry happen in a single database operation)
The transaction remarks will read: {Currency} Wallet credited by amount {Amount} - {remarks}

Top-up $1,000 to USD Wallet
┌─────────────────────────────┐
│ USD Wallet                  │
│ Balance: $5,000 → $6,000    │
│                             │
│ Transaction #789            │
│   Type:   CREDIT            │
│   Amount: $1,000.00         │
│   Status: COMPLETED         │
│   Remark: USD Wallet        │
│     credited by amount      │
│     1000.00 - Monthly top-up│
└─────────────────────────────┘

To request a top-up, contact your account manager with the wallet currency and amount. Top-ups are typically processed within the same business day.

Deductions

Wallet deductions happen in two scenarios:

1. Order settlement (automatic)

When you create an order via POST /api/v1/orders, the platform automatically deducts the order cost from the wallet matching the product's currency. If the wallet has insufficient balance, the order is rejected with an error.

Order: 5x Steam $50 Gift Cards = $250.00
┌─────────────────────────────┐
│ USD Wallet                  │
│ Balance: $6,000 → $5,750    │
│                             │
│ Transaction #790            │
│   Type:   DEBIT             │
│   Amount: $250.00           │
│   Status: COMPLETED         │
│   Remark: Order #ORD-12345  │
└─────────────────────────────┘

2. Manual adjustment (admin)

Your account manager can also manually deduct from a wallet for corrections, refunds to the platform, or other adjustments. These follow the same atomic process as top-ups but create a DEBIT transaction.

For PREPAID wallets, the wallet balance must be greater than or equal to the deduction amount. If the balance is insufficient, the operation fails and no funds are moved. Always check your wallet balance before placing large orders.

Balance Updates

All balance changes — whether top-up, order deduction, or manual adjustment — are atomic. A single database operation handles:

Wallet balance update — the actual amount change
Transaction record — the CREDIT or DEBIT entry you see via the API
Ledger entry — an internal audit record linking the transaction to the operation

This means a balance will never be partially updated. If any step fails, the entire operation rolls back and the balance remains unchanged.

FX Conversion

When an order's product currency differs from your wallet currency, the platform performs automatic forex conversion.

How Rates are Determined

Forex rates are sourced as mid-market rates from XE.com — the same rates you see on Google or financial news sites, with no hidden markup. The mid-market rate is the midpoint between the buy and sell prices for a currency pair, representing the fairest exchange rate available.

Rates are refreshed periodically and locked at the time of order placement. The exact rate applied to your transaction is recorded and visible on every transaction record.

Conversion Flow

Order: 10x Google Play ₹500 (INR product)
Your wallet: USD

1. Product cost:  ₹5,000.00
2. XE mid-market: 1 USD = 83.45 INR
3. Converted:     $59.92
4. FX fee:        $0.60 (if applicable)
5. Total deducted: $60.52 from USD wallet

Transaction Fields

The transaction record captures full FX details:

Field	Description
`source_currency`	The currency being converted from (your wallet currency)
`destination_currency`	The currency being converted to (the product currency)
`forex_rate`	The XE mid-market rate applied at the time of the order
`conversion_charges`	Any fee charged for the conversion (may be `null` if no fee applies)

FX rates are determined at the time of order placement and cannot be changed after the fact. The exact rate and any conversion charges are always visible on the transaction record. If no FX conversion was needed (wallet currency matches product currency), these fields will be null.

On this page