Quickstart

This walks through placing an order with a sandbox key and fetching its codes.

1. Create a sandbox key

In your reseller dashboard, create an API key in the test environment. It is prefixed sc_test_ and shown once — copy it now.

2. Browse the catalog

Each catalog item is a purchasable denomination. Its id is what you order.

curl https://api.sodacards.com/v1/catalog \
  -H "X-API-Key: sc_test_your_key_here"

import requests

resp = requests.get(
    "https://api.sodacards.com/v1/catalog",
    headers={"X-API-Key": "sc_test_your_key_here"},
)
print(resp.json())

const resp = await fetch("https://api.sodacards.com/v1/catalog", {
  headers: { "X-API-Key": "sc_test_your_key_here" },
});
console.log(await resp.json());

Response

{
  "data": [
    {
      "id": "a0c4d81e-d668-4dd4-9333-8551cadff904",
      "name": "25 TL",
      "faceValue": { "amount": "25", "currency": "TRY" },
      "price": { "amount": "395", "currency": "XOF" },
      "bonus": "0",
      "minQuantity": 1,
      "purchasable": true
    }
  ]
}

Some products require purchase-form values (a game top-up needs a player id, for example). They carry an inputFields array — see Purchase input fields. This gift card needs none.

3. Place an order

An order carries one or more lines, each a product id and a quantity. Include an Idempotency-Key so a retry never places the order twice (see Idempotency).

curl https://api.sodacards.com/v1/orders \
  -H "X-API-Key: sc_test_your_key_here" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Content-Type: application/json" \
  -d '{"lines": [{"product_id": "a0c4d81e-d668-4dd4-9333-8551cadff904", "quantity": 1}]}'

import requests

resp = requests.post(
    "https://api.sodacards.com/v1/orders",
    headers={
        "X-API-Key": "sc_test_your_key_here",
        "Idempotency-Key": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    },
    json={"lines": [{"product_id": "a0c4d81e-d668-4dd4-9333-8551cadff904", "quantity": 1}]},
)
print(resp.json())

Response

{
  "order": {
    "id": "bbc26d24-cf7d-42a4-899e-92cbe819729d",
    "status": "completed",
    "total": { "amount": "395", "currency": "XOF" }
  }
}

The response carries the order id and its status. In the sandbox an order is fulfilled at once, so it is born completed; a live order settles asynchronously — follow it on the order lifecycle.

4. Fetch the codes

Once the order is completed — you receive an order.fulfilled webhook, or you poll GET /v1/orders/{id} — fetch the codes:

curl https://api.sodacards.com/v1/orders/4102a9c6-fff4-4a15-a617-16e615f4c1a2/codes \
  -H "X-API-Key: sc_test_your_key_here"

Response

{ "codes": [ { "label": "25 TL", "code": "TEST-488acb9426f25b39" } ] }

In the sandbox the codes are deterministic TEST- values. Switch to a sc_live_ key to order against your real wallet and supply.

Get started

Core concepts

Webhooks

Reference

1. Create a sandbox key

2. Browse the catalog

3. Place an order

4. Fetch the codes

​1. Create a sandbox key

​2. Browse the catalog

​3. Place an order

​4. Fetch the codes

1. Create a sandbox key

2. Browse the catalog

3. Place an order

4. Fetch the codes