NovaCodes

Quick start

From a new key to your first code or your first eSIM in five minutes.

Steps 1 and 2 are the same for everyone. After them, follow the path of the product family you sell and skip the other one.

1. Create a key

Open Account → API, press Send code, and create a key with the code we send to your phone or email. The key is shown once: store it as a secret on your server. One key works for both families.

export NOVACODES_KEY=nc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. Check your balance

curl -s https://api.novacodes.app/v1/balance \
  -H "Authorization: Bearer $NOVACODES_KEY"
Response
{"data": {"MVR": 406000, "USD": 12500, "USDT": 8200}}

Amounts are in minor units: 406000 is MVR 4,060.00 and 12500 is USD 125.00 and 8200 is USDT 82.00 (see Balances & amounts). If they are all zero, add balance first.

Path A · Your first gift-card code

A3. See what you can order

curl -s https://api.novacodes.app/v1/products \
  -H "Authorization: Bearer $NOVACODES_KEY"

Pick a sku (or variant_id) whose available is at least the quantity you want.

A4. Place the order

curl -s https://api.novacodes.app/v1/orders \
  -H "Authorization: Bearer $NOVACODES_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sku":"SKU0012","quantity":1,"balance":"USD","reference":"inv-2291-1"}'
Response · 201 (shortened)
{"data": {"number": "NC-1042", "reference": "inv-2291-1", "status": "completed",
  "quantity": 1, "delivered": 1, "currency": "USD", "unit_price": 1210, "total": 1210, "charged": 1210,
  "codes": [{"unit": 1, "code": "XXXX-XXXX-XXXX", "pin": "1234", "link": null, "serial": null, "expires_at": null}]}}

The codes are in codes. That is the whole integration. Next: Gift card products and Gift card orders.

Path B · Your first eSIM

B3. List the plans of a destination

curl -s https://api.novacodes.app/v1/esim/destinations/MV \
  -H "Authorization: Bearer $NOVACODES_KEY"
Response (shortened)
{"data": {"code": "MV", "slug": "maldives", "name": "Maldives", "kind": "country",
  "plans": [
    {"plan_id": 43, "name": "Maldives 1GB 7Days", "type": "fixed", "data_mb": 1024, "days": 7,
     "price": {"MVR": 18000, "USD": 899, "USDT": 872}},
    {"plan_id": 44, "name": "Maldives 3GB 15Days", "type": "fixed", "data_mb": 3072, "days": 15,
     "price": {"MVR": 52000, "USD": 2599, "USDT": 2521}}
  ]}}

Pick a plan_id. To find a destination, GET /esim/destinations lists every one on sale.

B4. Place the order

curl -s https://api.novacodes.app/v1/esim/orders \
  -H "Authorization: Bearer $NOVACODES_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan_id":43,"quantity":1,"balance":"MVR","reference":"trip-8841"}'
Response · 201 (shortened)
{"data": {"number": "NC-22748", "reference": "trip-8841", "kind": "esim", "status": "completed",
  "quantity": 1, "delivered": 1, "currency": "MVR", "unit_price": 18000, "total": 18000, "charged": 18000,
  "esims": [{"iccid": "8985224628000101", "state": "ready",
    "install": {
      "lpa": "LPA:1$rsp.test$MATCH-1",
      "smdp_address": "rsp.test",
      "activation_code": "MATCH-1",
      "qr_svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" …>…</svg>",
      "ios_install_url": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA%3A1%24rsp.test%24MATCH-1"
    }}]}}

If status is processing, the eSIM is still being prepared and esims is empty. Read the order by your reference every few seconds until the status changes:

curl -s https://api.novacodes.app/v1/esim/orders/trip-8841 \
  -H "Authorization: Bearer $NOVACODES_KEY"

B5. Show the QR

install.qr_svg is a ready QR code as SVG markup: put it into your own page or email, under your own name. On an iPhone, install.ios_install_url opens eSIM set-up without scanning anything. Your customer never sees NovaCodes. Next: eSIMs and eSIM orders.

In both families, always send your own unique reference, and if a request times out, send it again with the same reference. You get the first order back and are never charged twice.