Dokumentasi API

API Endpoint Reference

Referensi lengkap NEXOTP API v1. Setiap endpoint berisi fungsi, authentication, parameter, request body, response sukses, error umum, implementation notes, dan contoh kode multi-bahasa.

Base URL

Gunakan domain production Anda sebagai base URL. Semua endpoint di bawah memakai prefix API v1 dan membutuhkan Authorization header.

https://webnokosai.vercel.app

GET/api/v1/balance

Get wallet balance

Mengambil saldo wallet akun yang sedang digunakan. Gunakan endpoint ini sebelum membuat order untuk memastikan saldo cukup.

Authentication

Required. Bearer API key production atau sandbox.

Success Response

Example

{
  "success": true,
  "data": {
    "balance": 2450000,
    "currency": "IDR",
    "updatedAt": "2026-06-22T06:00:00.000Z"
  },
  "requestId": "req_01HX..."
}

Error Response

401

API key tidak valid atau tidak dikirim.

429

Request melebihi limit.

Catatan Implementasi

Saldo selalu dibaca dari ledger internal.
Nilai balance dikembalikan dalam satuan rupiah tanpa pemisah ribuan.

Contoh CURL

Example

curl -X GET "https://webnokosai.vercel.app/api/v1/balance" \
  -H "Authorization: Bearer nx_live_xxx"

Contoh JavaScript

Example

const res = await fetch('https://webnokosai.vercel.app/api/v1/balance', {
  headers: { Authorization: 'Bearer nx_live_xxx' }
});
const data = await res.json();

Contoh PHP

Example

$ch = curl_init('https://webnokosai.vercel.app/api/v1/balance');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer nx_live_xxx']
]);
$response = curl_exec($ch);

Contoh Python

Example

import requests

res = requests.get(
  'https://webnokosai.vercel.app/api/v1/balance',
  headers={'Authorization': 'Bearer nx_live_xxx'}
)
print(res.json())

GET/api/v1/services

List services

Mengambil daftar layanan OTP yang tersedia untuk order. Data ini dipakai untuk menampilkan pilihan aplikasi atau platform kepada user.

Authentication

Required. Bearer API key production atau sandbox.

Query parameters

qstring

Opsional. Filter nama layanan.

limitnumber

Opsional. Jumlah data maksimum.

Success Response

Example

{
  "success": true,
  "data": [
    {
      "serviceCode": "whatsapp",
      "name": "WhatsApp",
      "category": "messaging",
      "available": true
    }
  ],
  "requestId": "req_01HX..."
}

Error Response

401

API key tidak valid.

503

Katalog layanan sedang tidak tersedia.

Catatan Implementasi

Simpan cache singkat di aplikasi Anda untuk mengurangi request berulang.
Gunakan serviceCode saat membuat order.

Contoh CURL

Example

curl -X GET "https://webnokosai.vercel.app/api/v1/services" \
  -H "Authorization: Bearer nx_live_xxx"

Contoh JavaScript

Example

const res = await fetch('https://webnokosai.vercel.app/api/v1/services', {
  headers: { Authorization: 'Bearer nx_live_xxx' }
});
const services = await res.json();

Contoh PHP

Example

$ch = curl_init('https://webnokosai.vercel.app/api/v1/services');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer nx_live_xxx']
]);
$response = curl_exec($ch);

Contoh Python

Example

import requests

res = requests.get(
  'https://webnokosai.vercel.app/api/v1/services',
  headers={'Authorization': 'Bearer nx_live_xxx'}
)
print(res.json())

GET/api/v1/countries

List countries

Mengambil daftar negara yang dapat digunakan untuk order nomor virtual. Gunakan countryCode pada request order.

Authentication

Required. Bearer API key production atau sandbox.

Query parameters

servicestring

Opsional. Filter negara berdasarkan layanan tertentu.

Success Response

Example

{
  "success": true,
  "data": [
    {
      "countryCode": "id",
      "name": "Indonesia",
      "prefix": "+62",
      "available": true
    }
  ],
  "requestId": "req_01HX..."
}

Error Response

401

API key tidak valid.

400

Filter service tidak dikenali.

Catatan Implementasi

Country code menggunakan format lowercase.
Ketersediaan dapat berubah sesuai stok dan provider.

Contoh CURL

Example

curl -X GET "https://webnokosai.vercel.app/api/v1/countries?service=whatsapp" \
  -H "Authorization: Bearer nx_live_xxx"

Contoh JavaScript

Example

const res = await fetch('https://webnokosai.vercel.app/api/v1/countries?service=whatsapp', {
  headers: { Authorization: 'Bearer nx_live_xxx' }
});
const countries = await res.json();

Contoh PHP

Example

$ch = curl_init('https://webnokosai.vercel.app/api/v1/countries?service=whatsapp');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer nx_live_xxx']]);
$response = curl_exec($ch);

Contoh Python

Example

import requests

res = requests.get(
  'https://webnokosai.vercel.app/api/v1/countries',
  params={'service': 'whatsapp'},
  headers={'Authorization': 'Bearer nx_live_xxx'}
)
print(res.json())

GET/api/v1/providers

List providers

Mengambil daftar provider yang tersedia untuk kombinasi layanan dan negara. Gunakan providerCode untuk memilih provider spesifik.

Authentication

Required. Bearer API key production atau sandbox.

Query parameters

servicestring

Opsional. Service code.

countrystring

Opsional. Country code.

Success Response

Example

{
  "success": true,
  "data": [
    {
      "providerCode": "any",
      "name": "Any Provider",
      "price": 6500,
      "stock": 120
    }
  ],
  "requestId": "req_01HX..."
}

Error Response

401

API key tidak valid.

400

Parameter service atau country tidak valid.

Catatan Implementasi

Gunakan provider any untuk pemilihan otomatis.
Harga pada response sudah mengikuti pricing rule akun Anda.

Contoh CURL

Example

curl -X GET "https://webnokosai.vercel.app/api/v1/providers?service=whatsapp&country=id" \
  -H "Authorization: Bearer nx_live_xxx"

Contoh JavaScript

Example

const url = new URL('https://webnokosai.vercel.app/api/v1/providers');
url.searchParams.set('service', 'whatsapp');
url.searchParams.set('country', 'id');
const res = await fetch(url, { headers: { Authorization: 'Bearer nx_live_xxx' } });

Contoh PHP

Example

$ch = curl_init('https://webnokosai.vercel.app/api/v1/providers?service=whatsapp&country=id');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer nx_live_xxx']]);
$response = curl_exec($ch);

Contoh Python

Example

import requests

res = requests.get(
  'https://webnokosai.vercel.app/api/v1/providers',
  params={'service': 'whatsapp', 'country': 'id'},
  headers={'Authorization': 'Bearer nx_live_xxx'}
)
print(res.json())

POST/api/v1/order

Create order

Membuat order nomor virtual baru. Sistem akan memvalidasi saldo, menghitung harga final, membuat order, dan mengembalikan nomor jika tersedia.

Authentication

Required. Bearer API key production atau sandbox.

Request body

servicestring

Wajib. Service code.

countrystring

Wajib. Country code.

providerstring

Opsional. Provider code, default any.

idempotencyKeystring

Disarankan. Mencegah order ganda saat retry.

Success Response

Example

{
  "success": true,
  "data": {
    "orderId": "ord_01HX...",
    "status": "waiting",
    "phoneNumber": "+62812xxxxxxx",
    "price": 6500,
    "expiresAt": "2026-06-22T06:15:00.000Z"
  },
  "requestId": "req_01HX..."
}

Error Response

400

Body request tidak lengkap.

402

Saldo tidak cukup.

409

Idempotency key sudah dipakai untuk payload berbeda.

503

Nomor tidak tersedia.

Catatan Implementasi

Selalu gunakan idempotencyKey saat membuat order dari backend Anda.
Order aktif bisa dipantau melalui endpoint detail order.

Contoh CURL

Example

curl -X POST "https://webnokosai.vercel.app/api/v1/order" \
  -H "Authorization: Bearer nx_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"service":"whatsapp","country":"id","provider":"any","idempotencyKey":"order-1001"}'

Contoh JavaScript

Example

const res = await fetch('https://webnokosai.vercel.app/api/v1/order', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer nx_live_xxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ service: 'whatsapp', country: 'id', provider: 'any', idempotencyKey: 'order-1001' })
});
const order = await res.json();

Contoh PHP

Example

$payload = json_encode(['service' => 'whatsapp', 'country' => 'id', 'provider' => 'any', 'idempotencyKey' => 'order-1001']);
$ch = curl_init('https://webnokosai.vercel.app/api/v1/order');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer nx_live_xxx', 'Content-Type: application/json']
]);
$response = curl_exec($ch);

Contoh Python

Example

import requests

res = requests.post(
  'https://webnokosai.vercel.app/api/v1/order',
  headers={'Authorization': 'Bearer nx_live_xxx'},
  json={'service': 'whatsapp', 'country': 'id', 'provider': 'any', 'idempotencyKey': 'order-1001'}
)
print(res.json())

GET/api/v1/order/{id}

Get order detail

Mengambil detail order, status terbaru, nomor virtual, countdown, dan kode OTP jika sudah diterima.

Authentication

Required. Bearer API key production atau sandbox.

Success Response

Example

{
  "success": true,
  "data": {
    "orderId": "ord_01HX...",
    "status": "received",
    "phoneNumber": "+62812xxxxxxx",
    "otp": "123456",
    "remainingSeconds": 420
  },
  "requestId": "req_01HX..."
}

Error Response

401

API key tidak valid.

403

Order bukan milik akun ini.

404

Order tidak ditemukan.

Catatan Implementasi

Status yang umum: waiting, received, success, expired, cancelled.
Polling 3–5 detik sudah cukup untuk sebagian besar integrasi.

Contoh CURL

Example

curl -X GET "https://webnokosai.vercel.app/api/v1/order/ord_01HX" \
  -H "Authorization: Bearer nx_live_xxx"

Contoh JavaScript

Example

const res = await fetch('https://webnokosai.vercel.app/api/v1/order/ord_01HX', {
  headers: { Authorization: 'Bearer nx_live_xxx' }
});
const order = await res.json();

Contoh PHP

Example

$ch = curl_init('https://webnokosai.vercel.app/api/v1/order/ord_01HX');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer nx_live_xxx']]);
$response = curl_exec($ch);

Contoh Python

Example

import requests

res = requests.get(
  'https://webnokosai.vercel.app/api/v1/order/ord_01HX',
  headers={'Authorization': 'Bearer nx_live_xxx'}
)
print(res.json())

POST/api/v1/order/{id}/cancel

Cancel order

Membatalkan order aktif. Jika order memenuhi syarat refund, saldo akan dikembalikan melalui wallet transaction.

Authentication

Required. Bearer API key production atau sandbox.

Request body

reasonstring

Opsional. Alasan cancel untuk audit log.

Success Response

Example

{
  "success": true,
  "data": {
    "orderId": "ord_01HX...",
    "status": "cancelled",
    "refunded": true,
    "refundAmount": 6500
  },
  "requestId": "req_01HX..."
}

Error Response

400

Order tidak bisa dibatalkan pada status saat ini.

403

Order bukan milik akun ini.

404

Order tidak ditemukan.

Catatan Implementasi

Cancel hanya berlaku untuk order yang masih aktif.
Refund diproses sekali dan dilindungi idempotency.

Contoh CURL

Example

curl -X POST "https://webnokosai.vercel.app/api/v1/order/ord_01HX/cancel" \
  -H "Authorization: Bearer nx_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"reason":"user_requested"}'

Contoh JavaScript

Example

const res = await fetch('https://webnokosai.vercel.app/api/v1/order/ord_01HX/cancel', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer nx_live_xxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ reason: 'user_requested' })
});
const result = await res.json();

Contoh PHP

Example

$ch = curl_init('https://webnokosai.vercel.app/api/v1/order/ord_01HX/cancel');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode(['reason' => 'user_requested']),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer nx_live_xxx', 'Content-Type: application/json']
]);
$response = curl_exec($ch);

Contoh Python

Example

import requests

res = requests.post(
  'https://webnokosai.vercel.app/api/v1/order/ord_01HX/cancel',
  headers={'Authorization': 'Bearer nx_live_xxx'},
  json={'reason': 'user_requested'}
)
print(res.json())