Skip to main content

​
Overview

Dancity eSIMs give your users data connectivity in 150+ countries without swapping a physical SIM. The eSIM flow is:
  1. Browse regions to find the destination country or region
  2. Browse packages for that region to see data, validity, and price
  3. Purchase the eSIM — the user installs it on their device via a QR code
  4. Optionally top up an existing eSIM with additional data

​
Authentication

All eSIM endpoints use your merchant API key only. 
Authorization: Bearer dcy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

​
Step 1 — Browse regions

GET /api/v1/esim/regions
Query paramTypeDescription
typenumber1 = single-country, 2 = multi-country/regional
# Single-country eSIMs
curl -sS "https://api.dancity.app/api/v1/esim/regions?type=1" \
  -H "Authorization: Bearer $DANCITY_API_KEY"

​
Step 2 — Browse packages for a region

GET /api/v1/esim/packages
Query paramTypeRequiredDescription
regionCodestring✓Region code from /esim/regions (e.g. "NG")
regionTypestringRegion type from the regions response: "country" (single country, default) or "multi-country" (regional bundle). Pass the same value as the region you selected.
typestring"BASE" = new eSIM install, "TOPUP" = add data to existing eSIM (default "BASE")
curl -sS "https://api.dancity.app/api/v1/esim/packages?regionCode=NG&type=BASE" \
  -H "Authorization: Bearer $DANCITY_API_KEY"

​
Step 3 — Purchase eSIM

POST /api/v1/esim/purchase

​
Request body

FieldTypeRequiredDescription
packageCodestring✓Package code from /esim/packages or /esim/topup-packages
customerRefstringYour internal reference ID
iccidstringICCID of existing eSIM — required for TOPUP packages
curl -sS -X POST "https://api.dancity.app/api/v1/esim/purchase" \
  -H "Authorization: Bearer $DANCITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "packageCode": "NG-1GB-30D",
    "customerRef": "ESIM-REF-001"
  }'

​
Top up an existing eSIM

When a user’s eSIM is running low on data, list compatible add-on packages using its ICCID (the SIM identifier assigned after the first purchase). 
GET /api/v1/esim/topup-packages

​
Query parameters

ParamTypeRequiredDescription
iccidstring✓ICCID of the active eSIM — from purchase details, GET /api/v1/esim/my-esims, or GET /api/v1/esim/details/{transactionId}
curl -sS "https://api.dancity.app/api/v1/esim/topup-packages?iccid=8960000000000000001" \
  -H "Authorization: Bearer $DANCITY_API_KEY"

​
Sample response

{
  "success": true,
  "message": "eSIM topup packages fetched successfully",
  "data": {
    "packages": [
      {
        "packageCode": "NG-500MB-7D-TOP",
        "name": "Nigeria 500MB Top-Up",
        "description": "Add 500MB valid for 7 days",
        "price": 0.62,
        "currency": "USD",
        "volume": 524288000,
        "duration": 7,
        "type": "TOPUP",
        "regionCode": "NG",
        "priceInNaira": 1005
      }
    ],
    "exchangeRate": 1620
  }
}
Then purchase the selected package with POST /api/v1/esim/purchase using the returned packageCode.

​
Fetch eSIMs

List active eSIMs on the merchant account. Each row includes the ICCID (needed for top-ups), package details, and activation status. 
GET /api/v1/esim/my-esims

​
Query parameters

ParamTypeDescription
pageintegerPage number (default 1)
limitintegerResults per page (default 20)
curl -sS "https://api.dancity.app/api/v1/esim/my-esims?page=1&limit=20" \
  -H "Authorization: Bearer $DANCITY_API_KEY"

​
Sample response

{
  "success": true,
  "message": "User eSIMs fetched successfully",
  "data": {
    "esims": [
      {
        "transactionId": "6a1c50347d0125d168aa32da",
        "tranxId": "DNTY4364368AOMYD",
        "packageCode": "CKH513",
        "packageName": "Qatar 1GB 7Days",
        "packageVolume": 1073741824,
        "packageDuration": 7,
        "regionCode": "QA",
        "amount": 2835,
        "currency": "NGN",
        "iccid": "8948010010013845234",
        "qrCodeUrl": "https://p.qrsim.net/4a8cf5af5f1c48e0b44f8eaf3af20220.png",
        "activationCode": "LPA:1$rsp-eu.simlessly.com$72056D3B588B49B4903120FC95BB96A4",
        "imsi": "260010183468325",
        "smdpAddress": null,
        "status": "GOT_RESOURCE",
        "dataUsageRemaining": 1073741824,
        "purchasedAt": "2026-05-31T15:13:56.436Z"
      },
      {
        "transactionId": "6a12d0d366a638d7d9e402a9",
        "tranxId": "DNTY003519MQ5RPN",
        "packageCode": "P0Q24KI1C",
        "packageName": "Nigeria 100MB 7Days",
        "packageVolume": 104857600,
        "packageDuration": 7,
        "regionCode": "NG",
        "amount": 975,
        "currency": "NGN",
        "iccid": "8948010010014447758",
        "qrCodeUrl": "https://p.qrsim.net/6d17f9164c9c4ad3a97ec890eac4f01b.png",
        "activationCode": "LPA:1$rsp-eu.simlessly.com$537A63701D1A4699ADB0A3206EE4CEA6",
        "imsi": "260010183528577",
        "smdpAddress": null,
        "status": "GOT_RESOURCE",
        "dataUsageRemaining": 104857600,
        "purchasedAt": "2026-05-24T10:20:03.519Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 2,
      "totalPages": 1,
      "hasPrevious": false,
      "hasNext": false
    }
  }
}

​
Get eSIM details

Fetch QR code, ICCID, activation code, and status for a purchased eSIM. Use this to display the install QR code to your customer or to retrieve the ICCID for top-ups. 
GET /api/v1/esim/details/{transactionId}

​
Path parameter

ParamDescription
transactionIdMongo _id, tranxId (e.g. DNTY8374056F678V), or customerRef from the eSIM purchase
curl -sS "https://api.dancity.app/api/v1/esim/details/DNTY8374056F678V" \
  -H "Authorization: Bearer $DANCITY_API_KEY"

​
Sample response

{
  "success": true,
  "message": "eSIM details fetched successfully",
  "data": {
    "iccid": "8948010010013845234",
    "imsi": "260010183468325",
    "qrCodeUrl": "https://p.qrsim.net/4a8cf5af5f1c48e0b44f8eaf3af20220.png",
    "activationCode": "LPA:1$rsp-eu.simlessly.com$72056D3B588B49B4903120FC95BB96A4",
    "status": "GOT_RESOURCE",
    "totalVolume": 1073741824,
    "totalDuration": 7,
    "validityRemaining": 7,
    "dataUsageRemaining": 1073741824,
    "packageDetails": {
      "name": "Qatar 1GB 7Days",
      "code": "CKH513",
      "volume": 1073741824,
      "duration": 7,
      "location": "QA",
      "price": 1.7115,
      "currency": "USD",
      "locationLogo": "https://flagcdn.com/w320/qa.png",
      "description": "Qatar 1GB 7Days",
      "speed": "3G/4G/5G",
      "coverage": [
        {
          "locationName": "Qatar",
          "locationLogo": "https://flagcdn.com/w320/qa.png",
          "locationCode": "QA",
          "operatorList": [
            {
              "operatorName": "ooredoo",
              "networkType": "5G"
            }
          ]
        }
      ]
    },
    "createdAt": "2026-05-31T15:13:57.571Z",
    "expiredAt": "2026-11-27T15:13:58.000Z"
  }
}

​
Full purchase flow

1. GET /esim/regions?type=1
   → user selects destination country → note regionCode

2. GET /esim/packages?regionCode=NG&type=BASE
   → user selects data package → note packageCode

3. POST /esim/purchase { packageCode, customerRef? }
   → note transactionId

4. GET /esim/details/{transactionId}
   → display QR code to user for device installation

5. (Optional) GET /esim/topup-packages?iccid={iccid}
   → user selects top-up package → POST /esim/purchase with packageCode
Save the transactionId after purchase. Use GET /esim/details/{transactionId} to retrieve and re-display the QR code if the user needs it again.

​
Next steps