First voucher order

Vouchers (digital gift cards — Amazon, Steam, Razer, etc.) are the simplest flow on Octopus Cards: codes return in the order response. For quantity <= 5, no polling is needed.

Three requests after authentication: browse the catalogue, quote the price, place the order.

This page assumes HOST and TOKEN are exported as described on the authentication step.

1. Find a product

Browse the catalogue, filtered to a country and category. In sandbox, country_id=1 is the US.

curl "$HOST/api/v1/products?country_id=1&category=Gaming&limit=5" \
  -H "Authorization: Bearer $TOKEN"

Pick an id and a denomination from available_denominations[]. The walkthrough uses product 123 at $50.

2. Quote the price

Get the exact amount the wallet will be debited — including any client discount.

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

Response:

{
  "non_discounted_total": 100.00,
  "discount_amount": 3.50,
  "total_payable": 96.50,
  "max_quantity": 100,
  "charges_details": {
    "source_currency": "USD",
    "destination_currency": "USD",
    "forex_rate": null,
    "conversion_fee": null
  }
}

total_payable is what will leave the wallet. Compare to the balance before placing the order.

3. Place the order

curl -X POST "$HOST/api/v1/orders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 123,
    "denomination": 50.00,
    "quantity": 2,
    "client_reference": "FIRST_VOUCHER_001"
  }'

Response (truncated):

{
  "id": 1234,
  "client_reference": "FIRST_VOUCHER_001",
  "status": "DELIVERED",
  "amount": 100.00,
  "discount": 3.50,
  "vouchers": [
    {
      "card_number": "STEAM-XXXX-XXXX-XXXX",
      "pin_code": "1234",
      "expires_at": "2027-04-01T00:00:00Z"
    },
    {
      "card_number": "STEAM-YYYY-YYYY-YYYY",
      "pin_code": "5678",
      "expires_at": "2027-04-01T00:00:00Z"
    }
  ]
}

The wallet has been debited; the two codes are usable in production (in sandbox they are mock values).

Capture the codes on first delivery

Voucher codes are decrypted only in this response. Subsequent fetches of GET /orders/:id return masked codes — persist them on your side at the point of delivery.

Why `client_reference`?

client_reference is the order's idempotency key. A second request with the same client_reference is rejected with 400 "Duplicate client_reference" instead of creating a duplicate order. See Idempotency.

What just happened

Listed products filtered to a country + category.
Quoted the price for a specific denomination + quantity.
Placed an order with an idempotent client_reference and received live voucher codes inline.

After completing this flow, the others are short cousins of the same pattern. Then:

Sync vs async orders — how Octopus Cards decides between inline delivery and polling.
Cross-currency orders — paying in a wallet whose currency differs from the variant.
Before You Go Live — the production checklist.
Voucher endpoint reference — every voucher endpoint with full request/response shapes.

1. Find a product

2. Quote the price

3. Place the order

What just happened

Next

On this page