Estimating order charges

Each vertical has its own charges endpoint that returns the precise wallet impact of a hypothetical order — face value, discount applied, any FX conversion, and the final amount that would leave the wallet. Use it to:

• Show a real price to the end-user before they confirm.
• Pre-check the wallet balance before placing bulk orders.
• Price-monitor across currencies.
• Surface max-quantity limits (vouchers only) without bumping into them.

The three endpoints follow the same response shape, so the integration logic is the same — only the request body differs.

Vouchers

POST /api/v1/products/:id/charges

curl -X POST "$HOST/api/v1/products/123/charges" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "denomination": 50.00,
    "quantity": 5,
    "wallet_id": 1
  }'

Voucher charges support multi-quantity (a single quote covers quantity units of the same denomination). The response includes max_quantity — the per-product ceiling the wallet is allowed to order at once.

Topups

POST /api/v1/topups/charges

curl -X POST "$HOST/api/v1/topups/charges" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 4218,
    "amount": 4.99,
    "wallet_id": 1
  }'

Topup orders are 1-at-a-time, so there is no quantity field and no max_quantity in the response. The variant Octopus Cards picks for (product_id, amount) is reported back via charges_details (and used directly by POST /topups/orders).

eSIM

POST /api/v1/esim/charges

curl -X POST "$HOST/api/v1/esim/charges" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 712,
    "amount": 4.50,
    "wallet_id": 1
  }'

eSIM orders always represent a single eSIM — there is no quantity field and no max_quantity in the response. amount must equal one of the variant amounts returned by GET /esim/products/:id/variants.

The shared response shape

All three endpoints return the same shape. The field that matters most is total_payable — that is what leaves the wallet if the order is placed. Everything else exists to explain how it was computed.

{
  "non_discounted_total": 250.00,
  "discount_amount": 8.75,
  "total_amount": 241.25,
  "discount": 3.5,
  "total_payable": 241.25,
  "charges_details": {
    "source_currency": "USD",
    "destination_currency": "USD",
    "forex_rate": null,
    "conversion_fee": null
  }
}

Cross-currency orders

When the wallet's currency differs from the variant's currency, Octopus Cards looks up an admin-managed forex rate and the response carries the conversion fields:

{
  "non_discounted_total": 250.00,
  "discount_amount": 8.75,
  "total_amount": 241.25,
  "net_amount": 222.31,
  "handling_fee_amount": 0.50,
  "total_payable": 222.81,
  "charges_details": {
    "source_currency": "USD",
    "destination_currency": "EUR",
    "forex_rate": 0.9214,
    "conversion_fee": 0.5
  }
}

total_payable = net_amount + handling_fee_amount, always in the wallet's destination_currency. If no rate exists for the source → destination pair, the request rejects with 400 "Exchange rate not available for the wallet currency". Full walkthrough: Cross-currency orders.

When to call it

Good places to call it:

• Right before an order. Use the returned total_payable to pre-check the wallet balance.
• When rendering a checkout/pricing UI. Call once when the user opens the step; re-call if they change amount / denomination / quantity.
• When planning a bulk campaign. Estimate total cost before committing, without holding any inventory.

Bad places:

• Every tick of a loop — the cache returns the same answer anyway, and rate-limit hits are easy.
• As a proxy for placing the order. Charges is a read-shaped calculation; it doesn't reserve anything. Only the create-order endpoint actually creates the order.

Pre-flight: check balance first

Pattern is identical across verticals — quote, fetch wallet, gate on balance. Example using the voucher charges endpoint:

func canAfford(host, token string, productID uint64, denom float64, qty int, walletID uint64) (bool, error) {
    // 1. Quote
    q, err := voucherCharges(host, token, productID, voucherChargesReq{
        Denomination: denom,
        Quantity:     qty,
        WalletID:     &walletID,
    })
    if err != nil {
        return false, err
    }

    // 2. Read wallet balance
    w, err := getWallet(host, token, walletID)
    if err != nil {
        return false, err
    }

    // 3. Gate the order on sufficient funds
    return w.Amount >= q.TotalPayable, nil
}

This avoids the INSUFFICIENT_FUNDS error path on the order endpoint, especially useful for bulk workflows where fast failure matters.

Example: pricing a user-facing checkout

type Quote struct {
    DisplayPrice float64
    Currency     string
    Discount     float64
    FaceValue    float64
    MaxQuantity  int // 0 when not applicable (topup/eSIM)
}

func PriceForCheckout(host, token string, productID uint64, denom float64, qty int) (*Quote, error) {
    c, err := voucherCharges(host, token, productID, voucherChargesReq{
        Denomination: denom,
        Quantity:     qty,
    })
    if err != nil {
        return nil, err
    }

    return &Quote{
        DisplayPrice: c.TotalPayable,
        Currency:     c.ChargesDetails.DestinationCurrency,
        Discount:     c.DiscountAmount,
        FaceValue:    c.NonDiscountedTotal,
        MaxQuantity:  c.MaxQuantity,
    }, nil
}

Render displayPrice + currency to the user. If they change quantity (vouchers) or amount (topup/eSIM), call again.

Errors worth handling

Vertical references for the full error list:

• Voucher charges
• Topup charges
• eSIM charges

Summary

• Always quote before committing. total_payable is what will actually be paid.
• Three endpoints, one response shape — choose by vertical (/products/:id/charges, /topups/charges, /esim/charges).
• Cache hits are server-side and last 5 minutes — don't hammer.
• Pre-check the wallet balance against total_payable before bulk voucher orders or whenever a clean failure mode is wanted.
• charges_details.forex_rate reveals whether an FX conversion is about to happen.