partner api

Sell global eSIM data under your own brand. You call goAFK, we handle the carrier relationship, and your end users never see a third party.

quickstart

Partner accounts are opened by our team — there is no self-serve signup. Once your account exists you will have an API key and a pre-paid USD balance. Three calls take you from nothing to a working eSIM.

1. Find a plan. 2. Buy it. 3. Give the returned activation code to your end user. That is the whole integration.

curl https://goafk.io/api/v1/plans?country=FR \
  -H "Authorization: Bearer $GOAFK_API_KEY"

curl -X POST https://goafk.io/api/v1/esims \
  -H "Authorization: Bearer $GOAFK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"plan_id":"156057"}'

The response carries esim.activation_code — an LPA string. Show it to your user as text or as a QR code and the profile installs. Nothing else is required.

authentication

Every request carries your API key as a bearer token. Keys look like gak_live_… and are shown exactly once, at the moment we create them: we store only a hash, so a lost key cannot be recovered and has to be replaced.

Authorization: Bearer gak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Treat the key like a password. It authorises spending against your balance, so it belongs on your server only — never in a browser, a mobile app, or a public repository. If a key is exposed, tell us and we will revoke it; revocation takes effect on the next request.

A missing, malformed, unknown or revoked key all return the same 401 INVALID_API_KEY. That is deliberate — the error never confirms that a particular key once existed.

balance & pricing

Your account holds a pre-paid balance in USD. Buying an eSIM or a top-up debits it; nothing else does. Every amount in this API is an integer number of cents — there are no floating-point prices to round.

Prices are personal to your account: the catalogue is returned at wholesale plus your contracted markup, so price_usd_cents from GET /plans is exactly what you will be charged. Two partners can see different numbers for the same plan, and that is expected.

The debit is atomic and happens before we ask the carrier for an eSIM. If your balance will not cover the plan you get 402 INSUFFICIENT_FUNDS and nothing is charged. If the debit succeeds but the carrier then refuses, we write a compensating refund automatically and mark the order provider_failed — you are never charged for an eSIM you did not receive.

To add funds, contact your account manager. Top-ups are not yet self-serve.

idempotency

Both spending endpoints — POST /esims and POST /esims/{id}/topup — require an Idempotency-Key header. It is not optional, because a network timeout on a purchase is otherwise indistinguishable from a failure, and retrying blind would charge you twice.

Use any string up to 200 characters; a fresh UUID per logical purchase is the usual choice. Store it before you send the request, so a retry after a crash can reuse it.

Replaying a key returns the original order with Idempotency-Replayed: true and does not charge again. The key is the unit of replay, not the request body: sending a different plan_id under a key you already used returns the first order, it does not buy the second plan. Always use a new key for a genuinely new purchase.

rate limits

Each API key has a requests-per-minute ceiling agreed with your account manager. Every authenticated response reports where you stand:

Over the limit you get 429 RATE_LIMITED. Back off for the Retry-After interval rather than retrying immediately. GET /plans is the call most worth caching: the catalogue changes slowly and it is not paginated.

errors

Every failure returns the same shape, with the HTTP status carrying the category and error.code carrying the specific reason. Branch on the code — the message is written for humans and its wording can change.

{
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Partner balance is insufficient for plan price 4.50 USD",
    "request_id": "6f1d0b3e-6c1a-4a4e-9f2a-1c2d3e4f5a6b"
  }
}

webhooks

Rather than polling, you can have us POST to your server when something happens on your account. Add an endpoint in the partner dashboard, where you will also find its signing secret and a log of recent deliveries.

Every delivery is a JSON body with the same envelope. Deduplicate on id: a retry re-sends the identical body, so a receiver that has already processed an id should acknowledge and do nothing.

{
  "id": "whd_7c1e2f30-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "event": "esim.purchased",
  "created_at": "2026-08-17T09:24:11.482Z",
  "data": {
    "esim": {
      "id": "9c1f2a44-3b6e-4c88-a0d1-77e2b3c4d5f6",
      "iccid": "8944478000001234567",
      "activation_code": "LPA:1$smdp.example.com$QR-G-5C-1LO-1S9L3JT",
      "qr_code_url": "https://cdn.example.com/qr/8944478000001234567.png",
      "status": "inactive",
      "data_total_mb": 5120,
      "data_used_mb": 0,
      "expires_at": null,
      "plan_id": "156057"
    },
    "order": {
      "id": "2b7c9d1e-4f60-4a23-9c81-5d6e7f809a1b",
      "kind": "purchase",
      "price_usd_cents": 1595,
      "currency": "USD",
      "plan_id": "156057",
      "partner_esim_id": "9c1f2a44-3b6e-4c88-a0d1-77e2b3c4d5f6",
      "status": "completed",
      "created_at": "2026-08-17T09:24:11.482Z"
    }
  }
}

Verifying the signature

Anyone can POST to your endpoint. The signature is what proves a delivery came from us — check it before acting on the body, and compare in constant time.

Sign the raw request body, not a re-serialized object — re-encoding changes the bytes and the signature will not match. Reject anything whose timestamp is more than 5 minutes from your own clock, which is what stops a captured delivery being replayed later.

const crypto = require('crypto');

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(',').map(p => p.trim().split('=')),
  );
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(parts.t));
  if (!Number.isFinite(age) || age > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  // Constant time: a plain === leaks the answer one byte at a time.
  return parts.v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

Retries

Reply with any 2xx and we stop. Reply with a 5xx, a 408, a 429, or nothing at all, and we retry 6 times with increasing gaps — 1m, 5m, 30m, 2h, 6h, 24h — which spans more than a day in total.

Any other 4xx stops the retries immediately. A 404 or a 401 means the endpoint is misconfigured, and the same request would fail identically six hours later. Acknowledge first and process afterwards: we time out after 10 seconds, and a slow reply costs you a duplicate delivery.

Events

{
  "id": "whd_7c1e2f30-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "event": "esim.purchased",
  "created_at": "2026-08-17T09:24:11.482Z",
  "data": {
    "esim": {
      "id": "9c1f2a44-3b6e-4c88-a0d1-77e2b3c4d5f6",
      "iccid": "8944478000001234567",
      "activation_code": "LPA:1$smdp.example.com$QR-G-5C-1LO-1S9L3JT",
      "qr_code_url": "https://cdn.example.com/qr/8944478000001234567.png",
      "status": "inactive",
      "data_total_mb": 5120,
      "data_used_mb": 0,
      "expires_at": null,
      "plan_id": "156057"
    },
    "order": {
      "id": "2b7c9d1e-4f60-4a23-9c81-5d6e7f809a1b",
      "kind": "purchase",
      "price_usd_cents": 1595,
      "currency": "USD",
      "plan_id": "156057",
      "partner_esim_id": "9c1f2a44-3b6e-4c88-a0d1-77e2b3c4d5f6",
      "status": "completed",
      "created_at": "2026-08-17T09:24:11.482Z"
    }
  }
}

{
  "id": "whd_7c1e2f30-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "event": "esim.topped_up",
  "created_at": "2026-08-17T09:24:11.482Z",
  "data": {
    "esim": {
      "id": "9c1f2a44-3b6e-4c88-a0d1-77e2b3c4d5f6",
      "iccid": "8944478000001234567",
      "activation_code": "LPA:1$smdp.example.com$QR-G-5C-1LO-1S9L3JT",
      "qr_code_url": "https://cdn.example.com/qr/8944478000001234567.png",
      "status": "inactive",
      "data_total_mb": 5120,
      "data_used_mb": 0,
      "expires_at": null,
      "plan_id": "156057"
    },
    "order": {
      "id": "2b7c9d1e-4f60-4a23-9c81-5d6e7f809a1b",
      "kind": "purchase",
      "price_usd_cents": 1595,
      "currency": "USD",
      "plan_id": "156057",
      "partner_esim_id": "9c1f2a44-3b6e-4c88-a0d1-77e2b3c4d5f6",
      "status": "completed",
      "created_at": "2026-08-17T09:24:11.482Z"
    }
  }
}

{
  "id": "whd_7c1e2f30-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "event": "order.failed",
  "created_at": "2026-08-17T09:24:11.482Z",
  "data": {
    "order_id": "2b7c9d1e-4f60-4a23-9c81-5d6e7f809a1b",
    "error_code": "PROVIDER_ERROR",
    "refunded_cents": 1595,
    "currency": "USD"
  }
}

{
  "id": "whd_7c1e2f30-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "event": "balance.low",
  "created_at": "2026-08-17T09:24:11.482Z",
  "data": {
    "balance_cents": 640,
    "threshold_cents": 1000,
    "currency": "USD"
  }
}

curl -X GET https://goafk.io/api/v1/plans \
  -H "Authorization: Bearer $GOAFK_API_KEY"

{
  "plans": [
    {
      "id": "156057",
      "country_code": "FR",
      "country_name": "France",
      "region": "Europe",
      "type": "fixed",
      "data_gb": 5,
      "duration_days": 30,
      "price_usd_cents": 1595,
      "currency": "USD"
    }
  ]
}

curl -X GET https://goafk.io/api/v1/plans/156057 \
  -H "Authorization: Bearer $GOAFK_API_KEY"

{
  "plan": {
    "id": "156057",
    "country_code": "FR",
    "country_name": "France",
    "region": "Europe",
    "type": "fixed",
    "data_gb": 5,
    "duration_days": 30,
    "price_usd_cents": 1595,
    "currency": "USD"
  }
}

curl -X POST https://goafk.io/api/v1/esims \
  -H "Authorization: Bearer $GOAFK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"plan_id":"156057"}'

{
  "esim": {
    "id": "9c1f2a44-3b6e-4c88-a0d1-77e2b3c4d5f6",
    "iccid": "8944478000001234567",
    "activation_code": "LPA:1$smdp.example.com$QR-G-5C-1LO-1S9L3JT",
    "qr_code_url": "https://cdn.example.com/qr/8944478000001234567.png",
    "status": "inactive",
    "data_total_mb": 5120,
    "data_used_mb": 0,
    "expires_at": null,
    "plan_id": "156057"
  },
  "order": {
    "id": "2b7c9d1e-4f60-4a23-9c81-5d6e7f809a1b",
    "kind": "purchase",
    "price_usd_cents": 1595,
    "currency": "USD",
    "plan_id": "156057",
    "partner_esim_id": "9c1f2a44-3b6e-4c88-a0d1-77e2b3c4d5f6",
    "status": "completed",
    "created_at": "2026-08-17T09:24:11.482Z"
  }
}

curl -X GET https://goafk.io/api/v1/esims \
  -H "Authorization: Bearer $GOAFK_API_KEY"

{
  "esims": [
    {
      "id": "9c1f2a44-3b6e-4c88-a0d1-77e2b3c4d5f6",
      "iccid": "8944478000001234567",
      "activation_code": "LPA:1$smdp.example.com$QR-G-5C-1LO-1S9L3JT",
      "qr_code_url": "https://cdn.example.com/qr/8944478000001234567.png",
      "status": "inactive",
      "data_total_mb": 5120,
      "data_used_mb": 0,
      "expires_at": null,
      "plan_id": "156057"
    }
  ],
  "total": 128,
  "page": 1,
  "limit": 50
}

curl -X GET https://goafk.io/api/v1/esims/9c1f2a44-3b6e-4c88-a0d1-77e2b3c4d5f6 \
  -H "Authorization: Bearer $GOAFK_API_KEY"

{
  "esim": {
    "id": "9c1f2a44-3b6e-4c88-a0d1-77e2b3c4d5f6",
    "iccid": "8944478000001234567",
    "activation_code": "LPA:1$smdp.example.com$QR-G-5C-1LO-1S9L3JT",
    "qr_code_url": "https://cdn.example.com/qr/8944478000001234567.png",
    "status": "inactive",
    "data_total_mb": 5120,
    "data_used_mb": 0,
    "expires_at": null,
    "plan_id": "156057"
  }
}

curl -X POST https://goafk.io/api/v1/esims/9c1f2a44-3b6e-4c88-a0d1-77e2b3c4d5f6/topup \
  -H "Authorization: Bearer $GOAFK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"plan_id":"156057"}'

{
  "esim": {
    "id": "9c1f2a44-3b6e-4c88-a0d1-77e2b3c4d5f6",
    "iccid": "8944478000001234567",
    "activation_code": "LPA:1$smdp.example.com$QR-G-5C-1LO-1S9L3JT",
    "qr_code_url": "https://cdn.example.com/qr/8944478000001234567.png",
    "status": "inactive",
    "data_total_mb": 5120,
    "data_used_mb": 0,
    "expires_at": null,
    "plan_id": "156057"
  },
  "order": {
    "id": "2b7c9d1e-4f60-4a23-9c81-5d6e7f809a1b",
    "kind": "purchase",
    "price_usd_cents": 1595,
    "currency": "USD",
    "plan_id": "156057",
    "partner_esim_id": "9c1f2a44-3b6e-4c88-a0d1-77e2b3c4d5f6",
    "status": "completed",
    "created_at": "2026-08-17T09:24:11.482Z"
  }
}

curl -X GET https://goafk.io/api/v1/esims/9c1f2a44-3b6e-4c88-a0d1-77e2b3c4d5f6/usage \
  -H "Authorization: Bearer $GOAFK_API_KEY"

{
  "usage": {
    "iccid": "8944478000001234567",
    "data_used_mb": 812,
    "data_total_mb": 5120,
    "status": "active",
    "expires_at": "2026-09-16T09:24:11.482Z"
  }
}

curl -X GET https://goafk.io/api/v1/orders \
  -H "Authorization: Bearer $GOAFK_API_KEY"

{
  "orders": [
    {
      "id": "2b7c9d1e-4f60-4a23-9c81-5d6e7f809a1b",
      "kind": "purchase",
      "price_usd_cents": 1595,
      "currency": "USD",
      "plan_id": "156057",
      "partner_esim_id": "9c1f2a44-3b6e-4c88-a0d1-77e2b3c4d5f6",
      "status": "completed",
      "created_at": "2026-08-17T09:24:11.482Z"
    }
  ],
  "total": 128,
  "page": 1,
  "limit": 50
}

curl -X GET https://goafk.io/api/v1/orders/2b7c9d1e-4f60-4a23-9c81-5d6e7f809a1b \
  -H "Authorization: Bearer $GOAFK_API_KEY"

{
  "order": {
    "id": "2b7c9d1e-4f60-4a23-9c81-5d6e7f809a1b",
    "kind": "purchase",
    "price_usd_cents": 1595,
    "currency": "USD",
    "plan_id": "156057",
    "partner_esim_id": "9c1f2a44-3b6e-4c88-a0d1-77e2b3c4d5f6",
    "status": "completed",
    "created_at": "2026-08-17T09:24:11.482Z"
  }
}

schemas

The objects returned by the endpoints above. Fields marked optional may be absent; a type ending in | null is always present but may be null.

support

Questions, a new key, more balance, or a higher rate limit — write to support@goafk.io. Include the request_id from the response if you are reporting a specific failure.