Nexar Reseller API · v1

One API for the digital productsyour customers need.

Check prices, place orders, and track delivery for virtual numbers, eSIMs, gift cards, social media services, airtime, data, and bills.

Make your first request Get an API key

Base URL

https://resellers.nexarhq.com/api/v1/reseller

30 documented endpointsSame JSON format in every responseSafe retries for order requestsVerified webhook events

Try it

Quickstart

Make your first request in minutes.

Your API access is linked to your Nexar account. After approval, create an API key for the products you need, then call GET /account to check that it works.

Get reseller access

Apply from your Nexar account and choose the services your business wants to resell.

Create an API key

In the reseller portal, choose only the products this API key needs.

Test your API key

Call GET /account to check your account, wallet balances, and available services.

Try the API

Test your connection

Read-only requests

This page sends your key directly to resellers.nexarhq.com. It is kept only in this tab and is never saved.

Test your API key with GET /account

In production, keep the key in a server-side environment variable. Never put it in browser or mobile app code.

cURL quickstart

curl "https://resellers.nexarhq.com/api/v1/reseller/account" \
  --header "Accept: application/json" \
  --header "X-API-Key: nx_live_YOUR_API_KEY"

Before you build

How every API request works.

Every API key belongs to one approved reseller account. Its permissions decide which products it can use. Request IDs help you find requests in your logs, while retry keys help prevent duplicate orders.

Send your API key

Add your key to the X-API-Key header on every request. Bearer authentication also works, but we recommend X-API-Key.

X-API-Key: nx_live_••••••••

Retry orders safely

Every new order needs a new Idempotency-Key. Use 8–120 letters, numbers, dots, underscores, colons, or hyphens, starting with a letter or number. If a request times out, retry within 24 hours with the same key, endpoint, and body. Nexar returns the original result instead of making a second order.

Idempotency-Key: order_01J8YQ6…

Track a request

Every response includes X-Request-ID and request_id. Save this ID in your logs. You can also send your own UUID in X-Request-ID.

X-Request-ID: 43f87c5a-…

Avoid sending too fast

Most endpoints allow 60 requests per minute from one IP address. Cancel and resend allow 20. If you get a 429 response, check Retry-After and the rate-limit headers before trying again.

X-RateLimit-Remaining: 57

API permissions (scopes)

A scope is a product permission. Your reseller account and API key must both have access to the product.

Give each key only the access it needs

virtual_numbers

Virtual Numbers

Find countries and services, check prices, place orders, and get OTPs.

esim

eSIM

Find plans, place orders, and get QR codes and activation details.

social_boost

Social Boosting

Find social media services and place orders.

gift_cards

Gift Cards

Find cards, place orders, and get redeem codes.

airtime_data

Airtime & Data

Buy airtime and mobile data.

bill_payments

Bill Payments

Pay electricity, TV, education, and other bills.

Response format

Every JSON response has the same main fields: success tells you if the request worked, message explains the result, data contains the result, and request_id helps you find the request when troubleshooting.

Successful response

The same top-level fields on every endpoint

200 OK

{
  "success": true,
  "message": "Request completed successfully.",
  "data": {
    "account": {
      "id": 42,
      "business_name": "Acme Digital",
      "status": "active"
    }
  },
  "request_id": "43f87c5a-c12c-43d6-8bf5-8b2e79bd7286"
}

Error response

Field errors may appear in the errors object

403 Forbidden

{
  "success": false,
  "message": "This API key does not have access to the requested service.",
  "data": {
    "service": "esim"
  },
  "request_id": "43f87c5a-c12c-43d6-8bf5-8b2e79bd7286"
}

Money and wallets

Your account has separate USD and NGN wallets. wallet_currency (or pay_with for gift cards) chooses which wallet to charge; it does not change the product’s own currency. In a money object, display is ready to show a person, whole is the decimal amount, and amount is a string in the smallest unit (cents or kobo). For example, "amount": "12540" means USD 125.40. Do not send consumer coupon codes with reseller requests; the API will return 422.

API reference

Every reseller endpoint.

Product details may change when suppliers update their catalogs. The top-level response format stays the same.

Showing 30 of 30 endpoints

Account

View your reseller account, wallet balances, approved products, discounts, and this key’s permissions.

GET

/account

Get account details

Start here. This shows which account owns the key, your wallet balances, approved products, and the products this key can use.

Example JSON

{
  "account": {
    "id": 42,
    "business_name": "Acme Digital",
    "status": "active"
  },
  "wallets": {
    "USD": {
      "amount": "12540",
      "display": "$125.40",
      "whole": "125.40",
      "symbol": "$",
      "currency": "USD"
    },
    "NGN": {
      "amount": "8500000",
      "display": "₦85,000",
      "whole": "85000",
      "symbol": "₦",
      "currency": "NGN"
    }
  },
  "services": [
    {
      "key": "esim",
      "label": "eSIM",
      "discount_type": "percentage",
      "discount_value": 15,
      "currency": null,
      "key_has_access": true
    }
  ]
}

https://resellers.nexarhq.com/api/v1/reseller/account

Virtual Numbers

Find available countries and services, check a number’s price, place an order, and wait for its OTP.

GET

/virtual-numbers/countries

List countries

Returns countries where virtual numbers are currently available.

URL parameters

driver

prime | alternate

Optional. Leave it out to use the default provider, or use alternate for the backup provider.

https://resellers.nexarhq.com/api/v1/reseller/virtual-numbers/countries

GET

/virtual-numbers/countries/{service}

List countries for a service

Returns countries where a selected service is available.

URL parameters

serviceRequired

string

Service ID returned by the services endpoint.

driver

prime | alternate

Optional. Leave it out to use the default provider, or use alternate for the backup provider.

https://resellers.nexarhq.com/api/v1/reseller/virtual-numbers/countries/{service}

GET

/virtual-numbers/services

List services

Returns available verification services, current stock, and your reseller prices.

URL parameters

driver

prime | alternate

Optional. Leave it out to use the default provider, or use alternate for the backup provider.

https://resellers.nexarhq.com/api/v1/reseller/virtual-numbers/services

POST

/virtual-numbers/price

Check a number’s price

Returns your current reseller price before you place an order.

URL parameters

driver

prime | alternate

Optional. Leave it out to use the default provider, or use alternate for the backup provider.

JSON body

countryRequired

string | number

Country ID returned by the countries endpoint.

serviceRequired

string | number

Service ID returned by the services endpoint.

Example JSON

{
  "country": 1,
  "service": 10
}

https://resellers.nexarhq.com/api/v1/reseller/virtual-numbers/price

POST

/virtual-numbers/ordersRetry key requiredCharges your wallet

Order a number

Buys a verification number and charges the wallet you choose.

This request creates a real order and may charge your Nexar wallet. There is no test mode yet.

Use a new Idempotency-Key for each new order. If you retry that order, reuse the same key, endpoint, and request body. Nexar will return the original result instead of creating a second order.

URL parameters

driver

prime | alternate

Optional. Leave it out to use the default provider, or use alternate for the backup provider.

JSON body

countryRequired

string | number

Country ID returned by the countries endpoint.

serviceRequired

string | number

Service ID returned by the services endpoint.

wallet_currency

USD | NGN

Wallet to charge. Defaults to USD where supported.

Example JSON

{
  "country": 1,
  "service": 10,
  "wallet_currency": "USD"
}

https://resellers.nexarhq.com/api/v1/reseller/virtual-numbers/orders

GET

/virtual-numbers/orders

List orders

Returns one page of your virtual-number order history.

URL parameters

page

integer

Page number. Defaults to 1.

per_page

integer

Results per page. Defaults to 15.

https://resellers.nexarhq.com/api/v1/reseller/virtual-numbers/orders

GET

/virtual-numbers/orders/{order}/status

Check order status

Returns the latest order status and the OTP when it arrives.

URL parameters

orderRequired

integer

Nexar virtual-number order ID.

https://resellers.nexarhq.com/api/v1/reseller/virtual-numbers/orders/{order}/status

POST

/virtual-numbers/orders/{order}/cancel

Cancel an order

Cancels an order if it can still be canceled. You can call this endpoint up to 20 times per minute.

URL parameters

orderRequired

integer

Nexar virtual-number order ID.

https://resellers.nexarhq.com/api/v1/reseller/virtual-numbers/orders/{order}/cancel

POST

/virtual-numbers/orders/{order}/resend

Request another SMS

Requests another SMS for an active order that supports resends. You can call this endpoint up to 20 times per minute.

URL parameters

orderRequired

integer

Nexar virtual-number order ID.

https://resellers.nexarhq.com/api/v1/reseller/virtual-numbers/orders/{order}/resend

Find social media services such as followers, likes, and views, then place an order at your reseller price.

POST

/social-boost/ordersRetry key requiredCharges your wallet

Create an order

Places an order for the selected service and social media URL.

This request creates a real order and may charge your Nexar wallet. There is no test mode yet.

Use a new Idempotency-Key for each new order. If you retry that order, reuse the same key, endpoint, and request body. Nexar will return the original result instead of creating a second order.

URL parameters

driver

global | nigerian

Optional. Use global or nigerian. Defaults to global.

JSON body

serviceRequired

integer

Service ID returned by the services endpoint.

quantityRequired

integer

Number of followers, likes, views, or other units to order. Stay within the service limits.

linkRequired

URL

Public URL of the account or post you want to boost.

comments

string

Only required when the selected service needs custom comments.

wallet_currency

USD | NGN

Wallet to charge. Global services default to USD; Nigerian services default to NGN.

Example JSON

{
  "service": 1204,
  "quantity": 100,
  "link": "https://www.instagram.com/p/example",
  "wallet_currency": "USD"
}

https://resellers.nexarhq.com/api/v1/reseller/social-boost/orders

eSIM

Browse international data plans, buy an eSIM, and get its setup details.

GET

/esim/countries

List countries

Returns countries with eSIM coverage.

https://resellers.nexarhq.com/api/v1/reseller/esim/countries

GET

/esim/plans/{country}

List plans

Returns available data plans and your reseller price for a two-letter country code.

URL parameters

countryRequired

ISO 3166-1 alpha-2

Two-letter country code, for example GB or US.

https://resellers.nexarhq.com/api/v1/reseller/esim/plans/{country}

GET

/esim/orders

List orders

Returns one page of your eSIM order history.

URL parameters

page

integer

Page number. Defaults to 1.

per_page

integer

Results per page. Defaults to 15.

https://resellers.nexarhq.com/api/v1/reseller/esim/orders

POST

/esim/ordersRetry key requiredCharges your wallet

Purchase a plan

Buys an eSIM plan and charges the wallet you choose.

This request creates a real order and may charge your Nexar wallet. There is no test mode yet.

Use a new Idempotency-Key for each new order. If you retry that order, reuse the same key, endpoint, and request body. Nexar will return the original result instead of creating a second order.

JSON body

planRequired

integer

Plan ID returned by the plans endpoint.

countryRequired

ISO 3166-1 alpha-2

Two-letter country code for the selected plan.

wallet_currency

USD | NGN

Wallet to charge. Defaults to USD.

Example JSON

{
  "plan": 4832,
  "country": "GB",
  "wallet_currency": "USD"
}

https://resellers.nexarhq.com/api/v1/reseller/esim/orders

GET

/esim/orders/{orderId}/profile

Get activation details

Returns the QR code and setup details for one of your eSIM orders.

URL parameters

orderIdRequired

integer

Nexar eSIM order ID.

https://resellers.nexarhq.com/api/v1/reseller/esim/orders/{orderId}/profile

Gift Cards

Browse gift cards, place an order, and get the card number or PIN when it is ready.

GET

/gift-cards/countries

List countries

Returns supported gift-card countries.

https://resellers.nexarhq.com/api/v1/reseller/gift-cards/countries

GET

/gift-cards/categories

List categories

Returns supported gift-card categories.

https://resellers.nexarhq.com/api/v1/reseller/gift-cards/categories

POST

/gift-cards/products

Find products

Returns gift cards for the country and category you choose.

JSON body

countryCodeRequired

string

Country code returned by the countries endpoint.

categoryIdRequired

string

Category ID returned by the categories endpoint.

Example JSON

{
  "countryCode": "US",
  "categoryId": "1"
}

https://resellers.nexarhq.com/api/v1/reseller/gift-cards/products

GET

/gift-cards/catalog

Browse country catalog

Returns the country’s gift cards grouped by category.

URL parameters

countryCodeRequired

string

Country code, passed as a query parameter.

https://resellers.nexarhq.com/api/v1/reseller/gift-cards/catalog

GET

/gift-cards/orders

List orders

Returns one page of your gift-card order history.

URL parameters

page

integer

Page number. Defaults to 1.

per_page

integer

Results per page. Defaults to 15.

https://resellers.nexarhq.com/api/v1/reseller/gift-cards/orders

POST

/gift-cards/ordersRetry key requiredCharges your wallet

Purchase a gift card

Buys one gift card and charges the wallet you choose.

This request creates a real order and may charge your Nexar wallet. There is no test mode yet.

Use a new Idempotency-Key for each new order. If you retry that order, reuse the same key, endpoint, and request body. Nexar will return the original result instead of creating a second order.

JSON body

productIdRequired

integer

Product ID returned by the products endpoint.

quantityRequired

Gift-card orders currently support one card per request.

unitPriceRequired

number

Use one of the card’s fixed amounts, or an amount within its allowed range. The catalog tells you the currency.

pay_with

USD | NGN

Wallet to charge. Defaults to NGN.

Example JSON

{
  "productId": 120,
  "quantity": 1,
  "unitPrice": 25,
  "pay_with": "USD"
}

https://resellers.nexarhq.com/api/v1/reseller/gift-cards/orders

GET

/gift-cards/orders/{order}/redeem-code

Get redeem code

Returns the card number, PIN, and redemption URL for one of your orders. Keep these details private because anyone with them may be able to use the card.

URL parameters

orderRequired

integer

Nexar gift-card order ID.

https://resellers.nexarhq.com/api/v1/reseller/gift-cards/orders/{order}/redeem-code

Airtime, Data & Bills

Browse Nigerian airtime, data, and bill products, check customer details, and make payments.

GET

/utilities/categories

List categories

Returns the airtime, data, and bill categories this API key can use.

https://resellers.nexarhq.com/api/v1/reseller/utilities/categories

GET

/utilities/services

List services

Returns providers in the selected category.

URL parameters

identifierRequired

string

Category ID returned by the categories endpoint.

https://resellers.nexarhq.com/api/v1/reseller/utilities/services

GET

/utilities/variations

List variations

Returns plans, packages, or other options for the selected service.

URL parameters

serviceIDRequired

string

Service ID returned by the services endpoint.

https://resellers.nexarhq.com/api/v1/reseller/utilities/variations

POST

/utilities/verify

Verify customer

Checks a customer, meter, or smartcard number before payment.

JSON body

billersCodeRequired

string

Customer, meter, or smartcard number.

serviceIDRequired

string

Selected service ID.

type

string

Optional. Some providers require this extra verification value.

Example JSON

{
  "billersCode": "0123456789",
  "serviceID": "ikeja-electric",
  "type": "prepaid"
}

https://resellers.nexarhq.com/api/v1/reseller/utilities/verify

POST

/utilities/ordersRetry key requiredCharges your wallet

Create a utility order

Buys airtime or data, or pays a bill, using the wallet you choose.

This request creates a real order and may charge your Nexar wallet. There is no test mode yet.

Use a new Idempotency-Key for each new order. If you retry that order, reuse the same key, endpoint, and request body. Nexar will return the original result instead of creating a second order.

JSON body

serviceIDRequired

string

Selected service ID.

variation_code

string

Required when the selected service has plans or package options.

amountRequired

number

Amount to pay in naira, written in whole naira rather than kobo.

billers_code

string

Customer, meter, or smartcard number.

phoneRequired

string

Recipient phone number, 10 to 14 characters.

type

string

Optional. Some providers require this extra value.

wallet_currency

USD | NGN

Wallet to charge. Defaults to NGN.

Example JSON

{
  "serviceID": "mtn-data",
  "variation_code": "mtn-1gb",
  "amount": 1000,
  "phone": "08012345678",
  "wallet_currency": "NGN"
}

https://resellers.nexarhq.com/api/v1/reseller/utilities/orders

Webhooks

Get order updates automatically.

Add a secure HTTPS URL in the reseller portal. Nexar sends order.created and order.updated events to that URL. Each request includes a signature so you can confirm it came from Nexar.

Build the signed text as <timestamp>.<raw-body>, then verify it with HMAC-SHA256. Raw body means the request text before you parse its JSON.

Compare signatures with timingSafeEqual, or your language’s timing-safe comparison function.

Reply with a 2xx status before doing slow work.

Webhook events do not include secrets. Get OTPs, eSIM details, and gift-card codes from their order endpoints.

Keep the webhook secret on your server. When you rotate it, the reseller portal shows the new secret only once.

Delivery policy

If delivery fails, Nexar tries up to four more times: after 10 seconds, 1 minute, 5 minutes, and 15 minutes. Nexar does not follow redirects.

Webhook payload

{
  "id": "01JTESTEVENT000000000000000",
  "event": "order.updated",
  "occurred_at": "2026-07-26T14:05:22+00:00",
  "data": {
    "order_id": 42,
    "service": "virtual_numbers",
    "status": "completed"
  }
}

Node.js signature verification

import crypto from "node:crypto";

export function verifyNexarWebhook(rawBody, headers, secret) {
  const timestamp = headers["x-nexar-timestamp"];
  const received = headers["x-nexar-signature"];
  const digest = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const expected = `sha256=${digest}`;

  return (
    received?.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))
  );
}

Errors & troubleshooting

Handle errors and retries safely.

Use the HTTP status to decide what to do, and save the request ID for troubleshooting. If an order request times out, retry it with the same request body and the same Idempotency-Key. Do not create a new key.

200 / 201

Request worked

The data was returned or the order was created.

401

API key problem

The key is missing, incorrect, expired, or revoked.

403

No access to this service

Your account or API key cannot use this service.

409

Retry key conflict

This retry key is still being processed or was used with different request data.

422

Check your request

One or more fields are missing or invalid.

429

Too many requests

Wait for the time shown in the response headers, then retry.

Getting a 401?

Copy the full API key again. Check that it has not expired or been revoked.

Getting a 403 for one product?

Check that your reseller account and this API key both have access to the product.

Getting a 409 after a retry?

Send the same JSON body again with the original Idempotency-Key.

Ready to build with Nexar?

Apply for reseller access, create an API key, then test it with GET /account.

Open reseller portal Contact API support