Welcome to Troveana

Welcome to the TROVEANA eSIM API — a RESTful interface that lets you manage eSIM packages, create and track orders, send SMS, monitor usage, and receive real‑time webhook notifications.

This single page covers everything you need to integrate. Use the cards below to jump to a section.

The Basics

Quick Start

Three steps to your first successful request:

1. Get your API key from your account manager.
2. Pick an environment — use Sandbox for testing, Production for live customers.
3. Make your first call — try listing packages:

curl -X GET "https://demo-public-api.troveana.net/api/v1/packages" \
  -H "X-API-KEY: your_secret_api_key"

That’s it — you’re integrated. Read on for the full reference.

Environments

TROVEANA provides two environments.

🚧

Webhooks are Production‑only

The Sandbox environment supports every API operation except webhooks. Test webhook handling on Production against a dedicated test partner account.

Authentication

Every request must include your API key in the X-API-KEY header.

X-API-KEY: your_secret_api_key

Example:

curl -X GET "https://api.troveana.com/api/v1/packages" \
  -H "X-API-KEY: your_secret_api_key"

❗️

Keep your API key secure

Never expose your key in client‑side code, mobile apps, or public repositories. If your key is compromised, contact your account manager immediately to rotate it.

Response Structure

Every response follows the same envelope — so error handling works identically across all endpoints.

{
  "success": true,
  "data": {},
  "error": null,
  "refCode": 0,
  "timestamp": 1702897200000
}

Success example:

{
  "success": true,
  "data": {
    "trackingId": "TRK-20251218-001",
    "status": "COMPLETED",
    "iccid": "8901234567890123456"
  },
  "error": null,
  "refCode": 0,
  "timestamp": 1702897200000
}

Error example:

{
  "success": false,
  "data": null,
  "error": "Insufficient balance to complete this order",
  "refCode": 422001,
  "timestamp": 1702897200000
}

📘

Tip

Always check success before reading data. When it’s false, read error for a human‑readable message and refCode for programmatic handling.

Pagination

Endpoints for eSIMs, order history, and packages support pagination.

Example request:

curl -X GET "https://api.troveana.com/api/v1/esims?page=1&pageSize=50" \
  -H "X-API-KEY: your_secret_api_key"

Paginated response:

{
  "success": true,
  "data": {
    "items": [],
    "pagination": {
      "currentPage": 1,
      "pageSize": 50,
      "totalItems": 250,
      "totalPages": 5,
      "hasNextPage": true,
      "hasPreviousPage": false
    }
  },
  "error": null,
  "refCode": 0,
  "timestamp": 1702897200000
}

📘

Iterating safely

Use hasNextPage to decide when to stop — it’s safer than comparing currentPage to totalPages while new items are being added.

API Endpoints

Allowed Countries

Retrieve the list of countries accessible by your account.

🔐

Authentication required

GET /api/v1/allowed/countries

Response:

{
  "success": true,
  "data": [
    {
      "code": "US",
      "name": "United States",
      "countryList": [],
      "moreInfoAboutTheCountry": {
        "id": "country_123",
        "code": "US",
        "name": "United States",
        "currencyCode": "USD",
        "lang": "en",
        "active": true
      }
    }
  ],
  "error": null,
  "refCode": 0,
  "timestamp": 1702897200000
}

Packages

List all eSIM packages available for your account.

🔐

Authentication required

GET /api/v1/packages

Query parameters:

Example:

curl -X GET "https://api.troveana.com/api/v1/packages?page=1&pageSize=20" \
  -H "X-API-KEY: your_secret_api_key"

Partner Balance

Check your current balance and available credit.

🔐

Authentication required

GET /api/v1/partner/balance

Response:

{
  "success": true,
  "data": {
    "partnerId": "partner_123",
    "balance": 5000.00,
    "currency": "USD",
    "creditLimit": 10000.00,
    "availableCredit": 5000.00,
    "lastUpdated": "2025-12-18T10:30:00Z"
  },
  "error": null,
  "refCode": 0,
  "timestamp": 1702897200000
}

📘

Before a batch order

Check availableCredit first to avoid "Insufficient balance" errors mid‑batch.

Orders

Create Order

🔐

Authentication required

POST /api/v1/orders

Request body:

{
  "item": "pkg_001",
  "quantity": 1
}

Success response:

{
  "success": true,
  "data": {
    "status": "PENDING",
    "trackingId": "TRK-20251218-001"
  },
  "error": null,
  "refCode": 0,
  "timestamp": 1702897200000
}

📘

Save the trackingId

You’ll need it to poll the order and retrieve the ICCID, activation code, and QR code once fulfillment completes.

Get Order Details

🔐

Authentication required

POST /api/v1/orders/details

Request body:

{
  "trackingId": "TRK-20251218-001"
}

Response:

{
  "success": true,
  "data": {
    "customerId": "partner_123",
    "trackingId": "TRK-20251218-001",
    "orderRequestTime": "2025-12-18T10:30:00Z",
    "status": "COMPLETED",
    "result": {
      "iccid": "8901234567890123456",
      "smdpAddress": "sm-dp.troveana.com",
      "activationCode": "LPA:1$sm-dp.troveana.com$ABC123",
      "qrCodeUrl": "https://api.troveana.com/qr/ABC123"
    }
  },
  "error": null,
  "refCode": 0,
  "timestamp": 1702897200000
}

eSIMs

List eSIMs

🔐

Authentication required

GET /api/v1/esims

Query parameters:

Installation QR Code

Get a direct link to the installation QR code for an eSIM.

🔐

Authentication required

GET /api/v1/esims/{iccid}/installation-qr

Follow‑Up Page QR Code

Get a link to a follow‑up page containing the QR code plus usage information for the customer.

🔐

Authentication required

GET /api/v1/esims/{iccid}/followup-qr

The follow‑up page includes:

• Interactive installation QR code
• Data usage statistics
• Remaining data and validity period
• Step‑by‑step installation guide

Cancel eSIM

❗️

This is irreversible

Cancelled eSIMs cannot be reactivated. Only eSIMs with status ACTIVE or PENDING can be cancelled. Partial refunds may be available based on your partner agreement.

🔐

Authentication required

POST /api/v1/esims/cancel

Request body:

{
  "iccid": "8901234567890123456",
  "reason": "Customer request",
  "trackingId": "TRK-CANCEL-20251218-001"
}

Top‑Up eSIM

Recharge an existing eSIM with a new data package.

🚧

Authorized partners only

This endpoint is only available to partners who have been granted top‑up access. Contact your account manager to enable it.

🔐

Authentication required

POST /api/v1/esims/topup

Request body:

{
  "iccid": "8901234567890123456",
  "packageId": "pkg_topup_001",
  "trackingId": "TRK-TOPUP-20251218-001"
}

SMS

Send SMS

🔐

Authentication required

POST /api/v1/esims/sms/send

Request body:

{
  "iccid": "8901234567890123456",
  "message": "Your verification code is: 123456",
  "sender": "TROVEANA",
  "trackingId": "TRK-SMS-20251218-001",
  "metadata": {
    "messageType": "verification",
    "campaignId": "CAMPAIGN-001"
  }
}

Get SMS Status

🔐

Authentication required

GET /api/v1/esims/sms/status/{trackingId}

📘

Good to know

• SMS works only for eSIMs with active SMS support
• Messages over 160 characters are split into segments
• Delivery reports may take up to 30 seconds to update
• SMS costs are deducted from your partner balance

Order History

Retrieve the complete order history for your account.

🔐

Authentication required

GET /api/v1/history/orders

Query parameters:

Example:

curl -X GET "https://api.troveana.com/api/v1/history/orders?page=1&pageSize=50&startDate=2025-12-01T00:00:00Z" \
  -H "X-API-KEY: your_secret_api_key"

Webhooks

Webhooks deliver real‑time notifications about eSIM events and usage updates to your server.

🚧

Production only

Webhooks are only available in Production (https://api.troveana.com). Contact your account manager to configure webhook endpoints.

Security

All webhook payloads are secured with asymmetric encryption and integrity verification:

• Encryption — Payload data is encrypted using your public RSA key
• Integrity — An MD5 hash of the unencrypted data is included for verification

Headers

Content-Type: application/json
X-Webhook-Signature: md5_hash_of_unencrypted_data
X-Webhook-Event: event_type
X-Webhook-Timestamp: 2025-12-18T10:30:00Z

Payload Structure

{
  "eventType": "esim.usage.updated",
  "timestamp": "2025-12-18T10:30:00Z",
  "encryptedData": "BASE64_ENCRYPTED_PAYLOAD",
  "md5Hash": "5d41402abc4b2a76b9719d911017c592"
}

Decryption Process

1. Extract the encryptedData field from the webhook payload
2. Decode the Base64‑encoded encrypted data
3. Decrypt using your private RSA key
4. Parse the decrypted JSON data
5. Calculate MD5 hash of the decrypted data
6. Compare with the md5Hash field to verify integrity

Event: esim.usage.updated

Decrypted payload:

{
  "iccid": "8901234567890123456",
  "trackingId": "TRK-20251218-001",
  "totalVolume": 5368709120,
  "usedVolume": 1073741824,
  "remainingVolume": 4294967296,
  "usagePercentage": 20,
  "lastUpdated": "2025-12-18T15:30:00Z"
}

Response & Retries

Your endpoint must respond with 200 OK within 30 seconds. If we don’t receive a successful response, we retry with exponential backoff:

📘

Best practice

Acknowledge the webhook with 200 OK immediately, then process the payload asynchronously. Long‑running handlers risk triggering unnecessary retries.

Need Help?

Contact your TROVEANA account manager for API keys, webhook configuration, top‑up access, or any integration questions.

📘

Version 1.0 · © 2025 TROVEANA. All rights reserved.