Getting Started

The Xegora Integration API is the machine-to-machine surface of your merchant workspace: browse the digital-goods catalog, lock a price, place an order against your prefunded wallet, and reveal the delivered codes. This page takes you from zero to your first fulfilled order.

Base URL

https://integration.xegora.com

Every endpoint is versioned under /api/v1. All requests and responses are JSON over HTTPS; plain HTTP is not served.

The mental model

Concept	What it is
Workspace	Your merchant tenant. Every API key belongs to exactly one workspace, and every resource you can see or create is scoped to it. You never pass a workspace id — it is derived from the key.
Wallet	Your workspace's prefunded balance, per currency. Orders reserve and spend from it; deposits credit it; withdrawals return unused funds to you.
Product	A sellable catalog item — a gift card brand, an eSIM plan, or a phone top-up — with either fixed variants (e.g. a $25 / $50 / $100 card) or a value range (min, max, step).
Quote	A short-lived, binding price for one product + quantity in your sell currency. Orders are placed against a quote, never against a raw product.
Order	The purchase itself. Creation is asynchronous: you get `202 Accepted` and follow the status until it is `Fulfilled` (or a webhook tells you).
Fulfillment	The delivered artifacts (codes, PINs, claim values). Revealed only on demand, over a dedicated endpoint, and never included in order bodies or webhooks.

Get an API key

API keys are issued from the merchant dashboard, never over the API:

Sign in to your merchant dashboard and open Developers.
Create a key, choosing only the scopes the integration needs (see Authentication for the scope catalog).
Copy the plaintext key — it starts with xkey_ and is shown once. Xegora stores only a hash.

Send the key on every request in the X-Api-Key header:

curl https://integration.xegora.com/api/v1/products?limit=5 \
  -H "X-Api-Key: xkey_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Your first order, end to end

The purchase flow is always the same four calls: find → quote → order → reveal.

1. Find a product (`products.read`)

curl "https://integration.xegora.com/api/v1/products?query=game&countryCode=US&limit=10" \
  -H "X-Api-Key: $XEGORA_API_KEY"

{
  "items": [
    {
      "id": "0198d72d-99d6-75a6-9f12-971050ba7a5f",
      "type": "gift-card",
      "name": "Everyday Digital Gift Card",
      "countryCode": "US",
      "currency": "USD",
      "isAvailable": true,
      "variants": [
        { "id": "0198d72d-a15b-7cbf-ab69-b95410e98636", "displayValue": "$50", "price": 52.50, "currency": "USD" }
      ],
      "minimumValue": null,
      "maximumValue": null,
      "valueStep": null,
      "category": "retail",
      "imageUrl": "/api/v1/catalog-product-images/img_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "isFeatured": false,
      "sortOrder": 0,
      "description": "A digital product.",
      "terms": "Terms apply.",
      "images": []
    }
  ],
  "offset": 0,
  "limit": 10,
  "hasMore": false
}

A product has either variants (pick one by id) or a value range (minimumValue, maximumValue, valueStep — pick a value). Treat every id and image reference as opaque.

2. Price it with a quote (`quotes.create`)

curl -X POST https://integration.xegora.com/api/v1/quotes \
  -H "X-Api-Key: $XEGORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "productId": "0198d72d-99d6-75a6-9f12-971050ba7a5f",
        "variantId": "0198d72d-a15b-7cbf-ab69-b95410e98636",
        "value": null,
        "quantity": 1,
        "currency": "USD"
      }'

{
  "id": "0198d72d-a6ce-77c6-9586-fc36708731d0",
  "productId": "0198d72d-99d6-75a6-9f12-971050ba7a5f",
  "variantId": "0198d72d-a15b-7cbf-ab69-b95410e98636",
  "quantity": 1,
  "total": 52.50,
  "currency": "USD",
  "expiresAtUtc": "2026-09-05T12:05:00Z"
}

The total is exactly what the order will debit from your wallet. Quotes expire after a few minutes; an expired quote is rejected at order time, so quote close to the moment of purchase.

3. Place the order (`orders.create`)

Order creation requires an Idempotency-Key header — a value you generate (1–128 printable characters) that makes retries safe. Sending the same key again returns the same order instead of buying twice.

curl -X POST https://integration.xegora.com/api/v1/orders \
  -H "X-Api-Key: $XEGORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-2026-09-05-000123" \
  -d '{
        "quoteId": "0198d72d-a6ce-77c6-9586-fc36708731d0",
        "clientReference": "your-order-1001"
      }'

HTTP/1.1 202 Accepted
Location: /api/v1/orders/0198e000-1111-7abc-9def-222233334444

{
  "id": "0198e000-1111-7abc-9def-222233334444",
  "clientReference": "your-order-1001",
  "status": "Reserved",
  "total": 52.50,
  "currency": "USD",
  "createdAtUtc": "2026-09-05T12:01:02Z",
  "updatedAtUtc": "2026-09-05T12:01:02Z"
}

202 Accepted means the order was admitted and your wallet funds are reserved — fulfillment happens asynchronously, usually within seconds. Follow it with GET /api/v1/orders/{orderId} or let a webhook push the transition to you (see Webhooks).

4. Reveal the delivered codes (`orders.read`)

Once the order is Fulfilled:

curl -X POST https://integration.xegora.com/api/v1/orders/0198e000-1111-7abc-9def-222233334444/fulfillment \
  -H "X-Api-Key: $XEGORA_API_KEY" \
  -H "Idempotency-Key: reveal-your-order-1001"

{
  "orderId": "0198e000-1111-7abc-9def-222233334444",
  "revealCount": 1,
  "artifacts": [
    { "type": "code", "value": "XXXX-XXXX-XXXX-XXXX", "expiresAtUtc": null }
  ]
}

Every reveal is counted and audited; the response is delivered with Cache-Control: no-store. Treat artifact values like passwords — see Fulfillment.

Funding the wallet

Orders debit your prefunded wallet. Check it any time:

curl "https://integration.xegora.com/api/v1/wallet/balance?currency=USD" \
  -H "X-Api-Key: $XEGORA_API_KEY"

To top it up on-chain, request your workspace's permanent BSC-USD deposit address and send funds to it — confirmed deposits credit the wallet automatically. The whole flow is covered in Wallet & Deposits.

Errors, correlation, and support

Failures return an RFC 9457 problem document with a stable machine code and a correlationId:

{
  "title": "The request could not be completed.",
  "status": 404,
  "detail": "Use the error code and correlation ID when contacting support.",
  "code": "not_found",
  "correlationId": "0HNOB6EOV3MHJ:00000001"
}

Always log the correlationId; quoting it lets support trace the exact request. The full error model, retry rules, and the 120-requests-per-minute rate limit are in Errors & Retries.

Where to next

Authentication — scopes, key hygiene, network allow-lists.
Catalog — search, categories, variants vs. ranges, images.
Quotes
Orders — idempotency and the full status lifecycle.
Fulfillment
Wallet & Deposits
Withdrawals
Webhooks
Errors & Retries
Go-Live Checklist