Charges

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

Calculate the exact cost of an order before placing it. Returns the breakdown including face value, discount, FX conversion (if applicable), and the final amount that will be deducted from your wallet.

Always call this endpoint before creating an order. It gives you the exact amount that will be charged, including any FX conversion fees. The response is cached for 5 minutes per unique combination of product, denomination, quantity, and wallet.

Request

curl -X POST "https://api.octopuscards.io/api/v1/products/123/charges" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "denomination": 50.00,
    "quantity": 5,
    "wallet_id": 1
  }'

Request Parameters

Key	Type	Required	Description
`id`	integer	Yes	Product ID (path parameter)
`denomination`	number	Yes	Face value of the product. Must be between 0.01 and 1,000,000,000. Must fall within an available denomination range.
`quantity`	integer	Yes	Number of vouchers. Must be at least 1 and not exceed your client's bulk limit.
`wallet_id`	integer	No	Wallet to debit from. If omitted, Octopus Cards uses your wallet matching the product's currency. Required when paying with a different currency (triggers FX conversion).

Response

{
  "non_discounted_total": 250.00,
  "discount_amount": 8.75,
  "total_amount": 241.25,
  "discount": 3.5,
  "gst_amount": 0.00,
  "total_payable": 241.25,
  "max_quantity": 100,
  "net_amount": 241.25,
  "handling_fee_amount": 0.00,
  "charges_details": {
    "source_currency": "USD",
    "destination_currency": "USD",
    "forex_rate": null,
    "conversion_fee": null
  }
}

With FX conversion (e.g. paying from EUR wallet for a USD product):

{
  "non_discounted_total": 250.00,
  "discount_amount": 8.75,
  "total_amount": 241.25,
  "discount": 3.5,
  "gst_amount": 0.00,
  "total_payable": 222.81,
  "max_quantity": 100,
  "net_amount": 222.81,
  "handling_fee_amount": 0.50,
  "charges_details": {
    "source_currency": "EUR",
    "destination_currency": "USD",
    "forex_rate": 0.9210,
    "conversion_fee": 0.50
  }
}

Response Fields

Key	Type	Description
`non_discounted_total`	number	Face value × quantity (before discount)
`discount_amount`	number	Total discount applied
`total_amount`	number	Amount after discount (before FX conversion)
`discount`	number	Discount percentage applied
`gst_amount`	number	Tax amount (if applicable)
`total_payable`	number	Final amount deducted from your wallet (after FX + fees)
`max_quantity`	integer	Maximum units you can order for this product
`net_amount`	number or null	Net amount after all adjustments
`handling_fee_amount`	number or null	Handling fee (if applicable)
`charges_details.source_currency`	string	Your wallet's currency
`charges_details.destination_currency`	string	The product's currency
`charges_details.forex_rate`	number or null	FX rate applied (`null` if same currency)
`charges_details.conversion_fee`	number or null	FX conversion fee (`null` if same currency)

Pricing Calculation

non_discounted_total  = denomination × quantity
discount_amount       = non_discounted_total × (discount / 100)
total_amount          = non_discounted_total − discount_amount
total_payable         = (total_amount × forex_rate) + conversion_fee + handling_fee

Errors

400 Bad Request - Product ID is not valid.

{
  "error": {
    "name": "BadRequestError",
    "code": "BAD_REQUEST",
    "message": "Invalid product ID"
  }
}

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