Juvega
Cart Account

Partner API reference

Version 1 · JSON over HTTPS

The Juvega Partner API lets approved partners sell eSIMs, gift cards, phone numbers and crypto swaps from their own website, app or bot. It is a JSON REST API. Prices are in USD, and orders are paid from your prepaid partner balance.

To get access, apply on the Partners page. Once approved, create an API key there.

Basics

  • Base URL: https://juvega.com/api/v1
  • Authentication: send your key in a header: Authorization: Bearer jv_live_… (or X-API-Key: jv_live_…). Keep keys on your server, never in a web page or app.
  • Format: send JSON with Content-Type: application/json. Every reply is JSON.
  • Errors: an HTTP error status and {"error": {"code": "…", "message": "…"}}.
  • Rate limit: 120 requests per minute per partner (429 with Retry-After when exceeded).
curl https://juvega.com/api/v1/account \
  -H "Authorization: Bearer jv_live_YOUR_KEY"

Account and balance

GET /account

Your partner name, discount, balance and which services are available.

{
  "partner": "Example Ltd",
  "discount_percent": 10,
  "balance": 250.00,
  "currency": "USD",
  "services": {"esim": true, "giftcard": true, "numbers": true, "swap": true}
}

POST /account/topup

Body {"amount": 500}. Returns a payment_url: pay it in crypto and the amount is added to your balance once the payment is confirmed. Amounts from 50 to 20000 USD. You can also top up on the Partners page.

Products (eSIMs and gift cards)

GET /products

Optional filters: type=esim or type=giftcard, country=JP (eSIMs, two-letter code), q= (search), page, per_page (up to 500).

{
  "data": [
    {"id": "japan-5gb-30days", "type": "esim", "name": "Japan 5GB 30Days", "country": "Japan", "country_code": "JP",
     "data_gb": 5, "days": 30, "price": 9.00, "currency": "USD", "options": []},
    {"id": "amazon-com-usa", "type": "giftcard", "brand": "Amazon.com", "price": 23.40,
     "options": [{"id": "o1a2b3c4", "label": "25 USD", "price": 23.40}, {"id": "o5d6e7f8", "label": "50 USD", "price": 46.80}]}
  ],
  "page": 1, "per_page": 100, "total": 1240
}

price is your price (after your discount). For gift cards, buy one of the options.

GET /products/{id}

One product.

Orders

POST /orders

{"product": "japan-5gb-30days", "reference": "your-order-123"}
{"product": "amazon-com-usa", "option": "o1a2b3c4", "reference": "your-order-124"}

The price is taken from your balance straight away. reference is optional but recommended: sending the same reference again returns the first order instead of buying twice, so retries are safe.

Reply (201):

{
  "id": "20261101-142233-9f8e7d6c",
  "reference": "your-order-123",
  "status": "processing",
  "type": "esim",
  "price": 9.00,
  "delivery": null
}

GET /orders/{id}

Poll every 5 to 10 seconds until status is delivered (usually under a minute). Then delivery holds the item:

eSIM:

"delivery": {
  "iccid": "8910…",
  "activation_code": "LPA:1$smdp.example$ABC123",
  "qr_code_url": "https://…/qr.png",
  "smdp_address": "smdp.example",
  "matching_id": "ABC123"
}

Gift card:

"delivery": {"code": "XXXX-XXXX-XXXX", "pin": "", "link": "", "instructions": "…", "expires": ""}

If an item cannot be delivered, status becomes failed, error explains why, and your balance is refunded automatically.

GET /orders

Your orders, newest first (page, per_page).

eSIM top-ups

Add data to an eSIM you sold earlier.

  • GET /topups?iccid=8910…: the top-ups available for that eSIM, with your price.
  • POST /topups with {"iccid": "8910…", "package": "TOPUP_…", "reference": "…"}: paid from your balance; returns an order (type: topup). Poll GET /orders/{id} like other orders.

Phone numbers for 6 or 12 months

Keep the same number for months to receive SMS (receive only).

  • GET /rentals/offers: countries with your 6- and 12-month price.
  • POST /rentals with {"offer": "…", "months": 6}: paid from your balance; the reply's rental.id and rental.phone identify the number.
  • GET /rentals/{rental id}: the number, paid_until and its messages.
  • POST /rentals/{rental id}/renew with {"months": 6}: add more months.

Phone numbers (SMS verification)

  • GET /numbers/services: the services you can rent a number for.
  • GET /numbers/prices?service=telegram: countries, your price and how many numbers are free.
  • POST /numbers with {"service": "telegram", "country": "england"}: rents a number and takes the price from your balance.
  • GET /numbers/{id}: poll for incoming SMS (sms list with code).
  • POST /numbers/{id}/cancel: no code yet? Cancel and get a full refund. Numbers that time out without a code are refunded automatically.
  • POST /numbers/{id}/finish: done with the number.

Crypto swaps

Swaps are paid by your customer directly (they send coins to the deposit address), so they do not use your balance. You earn a share of the swap fee, added to your balance when the swap completes.

  • GET /swap/currencies
  • POST /swap/quote with {"from": "BTC", "to": "XMR", "amount": 0.01, "type": "float"}
  • POST /swap with {"from": "BTC", "to": "XMR", "amount": 0.01, "type": "float", "address": "<customer's XMR address>", "reference": "…"}: returns deposit.address and deposit.amount for your customer to pay.
  • GET /swap/{id}: status (new, pending, exchange, withdraw, done, expired, emergency).

White-label shop

No developer? Switch on your white-label shop on the Partners page: eSIMs and gift cards with your name, logo and colour, at https://juvega.com/s/your-shop/ or on your own domain. You choose your markup. Customers pay you in crypto and the difference between your price and your partner price is added to your balance.

Good practice

  • Keep your balance topped up; orders fail with 402 insufficient_balance when it runs out.
  • Use a reference on every order.
  • Show eSIM activation_code as a QR code for your customers, and tell them to install it once only.
  • Questions? Contact us.