Frequently Asked Questions

General

What is SecureOTP?

SecureOTP is a hosted OTP delivery platform that lets your application send one-time verification codes via SMS or WhatsApp. You generate a code, we deliver it, and you verify it — no carrier contracts or WhatsApp Business API setup required.

Do I need to set up any infrastructure?

No. SecureOTP is a hosted service. You only need an API key. For WhatsApp delivery, an admin connects a WhatsApp account once via QR scan, and all sends flow through it automatically.

Billing & Credits

How does billing work?

SecureOTP uses a prepaid credit system. You purchase credits via the Console and each send deducts from your balance. There are no subscriptions or monthly fees.

| Channel | Cost | | --- | --- | | SMS | 499 credits per OTP | | WhatsApp | 299 credits per OTP |

What happens if I run out of credits?

The send request returns a 402 Payment Required error and no message is delivered. The user's balance is not modified. Top up your balance from the Purchase page in the Console.

When are credits added after a top-up order?

Credits are added once an admin confirms your payment and marks the order as Completed. Until then your order shows as Pending and no credits are added.

Do credits expire?

No. Credits do not expire.

Delivery

What phone number format should I use?

Use E.164 format: a + sign followed by the country code and subscriber number, with no spaces or dashes. Examples: +628123456789 (Indonesia), +14155551234 (US), +447911123456 (UK).

Can the same OTP code be used more than once?

No. A code is consumed on the first successful verification and cannot be verified again.

What happens if a user requests a new OTP before the old one expires?

The old code is automatically invalidated. Only the most recently sent code is valid at any time for a given phone number and channel.

How long is a code valid?

By default, 5 minutes. The exact expiry is returned in the expiresAt field of every send response. Use it to drive a countdown timer in your UI.

What does the OTP message look like?

YourAppName: A3K9PZ. Valid for 5 minutes.

The sender name is taken from your registered profile in the Console.

Does the recipient need to have my number saved?

No. WhatsApp delivers messages from unknown numbers — the recipient does not need to have the sender's number in their contacts.

What happens if the WhatsApp account disconnects?

Sends will fail until the account is reconnected. Monitor your account status from the Setup page and reconnect by scanning the QR code again. You will not be charged for failed sends.

Can I use my own WhatsApp number instead of the shared one?

Yes, if you are on the PREMIUM plan. An admin assigns your user account to a dedicated WhatsApp account. Once connected, pass its whatsappAccountId in your send request. See the WhatsApp guide for details.

Can I send WhatsApp OTPs without specifying an account ID?

Yes. Omitting whatsappAccountId always falls back to the system default account configured by the admin.

API Keys

I lost my API key — can I retrieve it?

No. For security reasons, the full key is shown only once at creation. If you have lost a key, revoke it and create a new one.

What is the difference between sk_test_ and sk_live_ keys?

sk_test_... keys simulate delivery without sending real messages and do not deduct credits. Use them during development and testing.
sk_live_... keys send real messages and deduct from your balance.

Can I restrict which domains can use an API key?

Yes. Set allowedDomains when creating a token to restrict it to specific origins (e.g. example.com,api.example.com). Requests from other origins will be rejected.

Troubleshooting

I get 503 No default WhatsApp account is configured.

An admin needs to connect at least one WhatsApp account and mark it as the Default from the Setup page in the Console.

I get 402 Insufficient balance.

Your credit balance is below the cost of the send. Top up from the Purchase page.

I get 401 API key has been revoked.

The key you are using has been deactivated. Generate a new one from the Console under API Tokens.

The OTP was sent but the user never received it.

For SMS: confirm the phone number is correct and in E.164 format. Some carriers have delivery delays.
For WhatsApp: the recipient must have WhatsApp installed and the account must be in ready status.

I get 400 Invalid or expired OTP even with the correct code.

Check that:

You are verifying against the correct channel (/sms/verify for SMS sends, /whatsapp/verify for WhatsApp sends)
The code has not expired (default TTL is 5 minutes)
A newer OTP has not been sent, which would have invalidated this one