non-voipnon-voip
API Reference

non-voip Merchant API v1

The public, customer-facing API for server-to-server integrations. Internal client and admin APIs are not included.

Open Swagger UIView Terms

Base URL & Authentication

Base URL

https://non-voip-api.0246864.xyz/api/v1

Use this host for all merchant API requests.

Authentication

All endpoints require an API key. Keep it on your server and include it in every request header.

X-Api-Key: YOUR_MERCHANT_API_KEY

Quick Start

  1. Create a merchant API key in the API Dashboard and keep it on your server. Creating, rotating and using a key all require an active merchant tier.
  2. Send X-Api-Key with every request.
  3. Read the catalog, then create a verification with its productServiceId and a unique Idempotency-Key.
  4. Poll the verification until data.messages contains a code. Single-SMS orders normally become completed, not otp_received.
export NV_API_KEY='nvr_live_...'
API='https://non-voip-api.0246864.xyz/api/v1'

PRODUCT_SERVICE_ID=$(curl --fail-with-body --silent --show-error   "$API/catalog?test=true"   -H "X-Api-Key: $NV_API_KEY" | jq -r '.data[0].productServiceId')

VERIFICATION_ID=$(curl --fail-with-body --silent --show-error   -X POST "$API/verifications?test=true"   -H "X-Api-Key: $NV_API_KEY"   -H "Idempotency-Key: $(uuidgen)"   -H "Content-Type: application/json"   -d "{"productServiceId":"$PRODUCT_SERVICE_ID"}" | jq -r '.data.verificationId')

for _ in $(seq 20); do
  curl --fail-with-body --silent --show-error --max-time 15     "$API/verifications/$VERIFICATION_ID?test=true"     -H "X-Api-Key: $NV_API_KEY" | jq -e '.data.messages[0].code' && break
  sleep 5
done

Production integration essentials

Server-side only

Keep API keys in your backend or serverless functions. Never expose them in browser JavaScript or mobile apps.

Versioned responses

Every route starts with /api/v1. Read successful payloads from data and handle HTTP status plus the application code on errors.

Retries and limits

Send an Idempotency-Key on writes and reuse it when retrying. Respect X-RateLimit-* and Retry-After response headers.

Test Mode (No Real Charges)

Add ?test=true for deterministic production-shaped data without provider calls or balance charges. Authentication, request logging, and rate limits still apply.

Webhooks

Configure your HTTPS URL and event selection in the API Dashboard. Events are verification.created, verification.otp_received, verification.completed, verification.expired, verification.cancelled, and verification.failed.

Single-SMS codes arrive on verification.completed. Multi-SMS rentals can emit verification.otp_received before completion. This is the easiest thing to get wrong: subscribe only to verification.otp_received and a single-SMS integration can sit there receiving nothing at all, so always subscribe to verification.completed as well.

Verify X-Webhook-Signature as lowercase HMAC-SHA256 of the raw body, and return 2xx within 10 seconds. A delivery is attempted up to 5 times with exponential backoff — one attempt plus four retries. Every attempt rebuilds the body, so timestamp and X-Webhook-Signature differ each time; never cache or reuse a signature across attempts. X-Webhook-Delivery is stable across them, which is what makes it the field to de-duplicate on.

Keep your endpoint reachable. After 5 consecutive deliveries exhaust every attempt, non-voip disables the webhook automatically and clears the URL, the signing secret and the event subscription. You are notified, but nothing more is delivered until you re-register the URL in the API Dashboard and generate a new secret — a prolonged outage costs you the configuration itself, not just the events you missed.

Example payload

{
  "event": "verification.completed",
  "timestamp": "2026-08-27T10:00:00.000Z",
  "balance": 124.5,
  "data": {
    "subscriptionId": "550e8400-e29b-41d4-a716-446655440000",
    "phoneNumber": "+15550001234",
    "otpCode": "483920",
    "messages": [
      {
        "code": "483920",
        "message": "Your verification code is 483920",
        "receivedAt": "2026-08-27T09:59:58.000Z"
      }
    ],
    "status": "completed",
    "productServiceId": "0f1a5a6c-1c2d-4f2b-9a1e-3c9d4b7e2f10"
  }
}

Merchant - Balance

Merchant - Catalog

Merchant - Verifications

Resources

API Dashboard

Create API keys and manage webhook settings.

Swagger UI

Interactive reference for the public Merchant API v1 only; internal client and admin APIs are excluded.

Support

Need integration help? Contact our support team at support@non-voip.com.