Send OTP from
cURL

1. Install

# cURL ships with macOS, Linux and modern Windows.
curl --version  # check you have 7.50+

2. Send your first OTP

Set NEXO_KEY in your environment, then run:

# Send OTP
curl -X POST https://nexoroute.dev/api/v1/send-otp \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"phone":"+84981234567","code":"482917"}'

# Expected response (HTTP 202):
# {
#   "ok": true,
#   "id": "8f2e1c4d-...",
#   "carrier": "viettel",
#   "status": "sent",
#   "cost": 0.022,
#   "balance": 0.088
# }


# Check delivery status
curl https://nexoroute.dev/api/v1/deliveries/8f2e1c4d-... \
  -H "Authorization: Bearer sk_live_..."

# Expected response:
# {
#   "ok": true,
#   "id": "8f2e1c4d-...",
#   "phone": "+84981234567",
#   "carrier": "viettel",
#   "status": "delivered",
#   "cost": 0.022,
#   "created_at": "2026-05-26T10:00:00Z",
#   "completed_at": "2026-05-26T10:00:25Z"
# }


# Check wallet balance
curl https://nexoroute.dev/api/v1/balance \
  -H "Authorization: Bearer sk_live_..."

# {
#   "ok": true,
#   "balance": 25.110,
#   "buckets": { "balance": 25.0, "bonus_credit": 0, "free_credit": 0.110 }
# }

3. Receive delivery webhooks

We POST a signed event to your URL when each OTP reaches a terminal state (delivered or failed). Verify the HMAC before trusting the payload.

# Test your webhook receiver from the dashboard's "Test ping" button,
# or simulate a webhook with curl + manually-computed HMAC:

SECRET="your_plaintext_webhook_secret"
KEY=$(printf '%s' "$SECRET" | openssl dgst -sha256 -binary | xxd -p -c 256)

BODY='{"type":"otp.delivered","id":"test","phone":"+84981234567","carrier":"viettel","status":"delivered","cost":0.022,"error_code":null,"created_at":"2026-05-26T10:00:00Z","completed_at":"2026-05-26T10:00:25Z"}'

SIG="sha256=$(printf '%s' "$BODY" | openssl dgst -sha256 -mac HMAC -macopt hexkey:$KEY | sed 's/^.* //')"

curl -X POST https://your-server.example.com/webhooks/nexo \
  -H "Content-Type: application/json" \
  -H "X-NEXO-Signature: $SIG" \
  -H "X-NEXO-Event-Type: otp.delivered" \
  -d "$BODY"

Common pitfalls

• !Single quotes around JSON body prevent shell interpolation — use \$ for literal $ if needed
• !On Windows cmd.exe use double quotes and escape inner quotes as \" — better to use PowerShell or Git Bash
• !curl follows redirects only with -L flag — our API does not redirect, so do not enable
• !Use --fail-with-body to make curl exit non-zero on 4xx/5xx while still printing the body
• !Pipe JSON through jq for readable output: curl ... | jq .

FAQ