One-Time Passcode Troubleshooting & FAQs

Common errors

The table below outlines common errors that may occur when using OTP Verification in RiskOS™. These issues can result from formatting problems, unsupported phone numbers, or OTP policy limits. Understanding these patterns can help you fine-tune workflows, reduce friction, and improve security.

Issue	Explanation	Suggested fix
API returns `Invalid phone number`	The phone number is not formatted correctly. Must follow E.164 format.	Ensure phone number is in `+{country_code}{number}` format (e.g., `+15034700244`). Remove spaces/dashes. Confirm it’s valid SMS.
Verification always returns `pending`	OTP has not yet been verified but is still within the 10-minute window.	Wait for user to submit OTP. Confirm delivery succeeded. Check expiration and retry count.
Voice call not received	Destination may not support voice delivery.	Confirm the number can accept calls. Note some VoIP or virtual numbers may not support voice OTP.
OTP verification rejected	The OTP session has expired (10-minute window elapsed) or the user has exceeded the maximum 5 verification attempts.	Verify the OTP was submitted within 10 minutes of delivery. Check `attemptCount` to confirm the user has not exceeded 5 attempts. If expired, start a new evaluation to generate a fresh OTP session.
401 Unauthorized	Invalid or expired API token.	Verify Bearer token is correct and active. Use correct token for sandbox vs production.
403 Forbidden	API token lacks permissions.	Contact support to enable OTP access. Confirm account entitlements.
Missing required fields	Payload missing destination or channel.	Include all mandatory fields. Check names are case-sensitive. Ensure phone numbers are in E.164.
Evaluation not found on PATCH	Invalid or expired `eval_id`.	Verify you’re using the correct `eval_id`. Check same environment (sandbox vs production). Confirm UUID format.
OTP delivery failed	No OTP received by user. Missing enrichment response.	Confirm valid mobile/email. Check carrier or inbox deliverability. Retry with alternate destination if needed.
Invalid OTP	OTP entered by the user is incorrect.	OTP entered by the user is incorrect. OTP will be six digit numeric.

How to debug

To debug One-Time Passcode (OTP) behavior in RiskOS™:

Use the eval_id to trace execution in the Developer Console or RiskOS™ logs.
Check the status_code in each data_enrichments[] block. A 200 indicates success. Any other status should be flagged.
Validate the correct channel (SMS, email, voice) was triggered.
Review the OTP status (pending, approved, reject). Confirm expiry and retry counts.
Check the verificationId is consistent across delivery and verify requests.

Fallback strategies

If OTP doesn't yield a successful verification:

Retry delivery: Allow resend if OTP is not received.
OTP expires: Allow resend if OTP expires before verification.
Switch channels: If SMS fails, attempt email or voice delivery.
Force resume: Use the actions.resume flag to skip a stalled step and continue the workflow.
Escalate to review: Route persistent OTP failures to manual review.

Escalation path

For production-impacting issues or debugging edge cases:

Reproduce the issue in sandbox or staging if possible.
Capture relevant identifiers, including:
- eval_id
- Full request payload
- verificationId from OTP enrichment
Open a support ticket — Contact Socure Support or your Solutions Consultant team and include workflow name, request details, and logs.
Urgent escalation — Use Slack (if integrated) or your designated Socure escalation channel for high-severity cases.

Known limitations

Carrier dependency: SMS/voice OTP delivery may vary by carrier or region.
OTP window: Codes typically expire in 10 minutes. Expired codes always fail verification.
Retry limits: Max of 5 attempts per OTP session. Further attempts auto-fail.
Channel restrictions: Some VoIP/virtual numbers may not support SMS or voice delivery.
No storage of OTP codes: For security, OTP values are never logged or retrievable.

📘 Note: Use the Developer Console to view raw request/response logs in real time for debugging or validation.

FAQs

Integration FAQ

How do I enable OTP for my workspace?

Contact your Socure Account Manager to confirm that OTP is enabled for your workspace. This is a prerequisite before you can begin integration.

Where can I find my API key for OTP integration?

Go to the RiskOS™ Dashboard > Developer Workbench > API Keys page to generate and retrieve your API key.

What's the difference between Sandbox and Production environments?

Sandbox is for testing and development purposes where you can use test data and personas. Production is the live environment for real consumer transactions.

Do I need to complete RiskOS™ setup before integrating OTP?

Yes, you must complete the RiskOS™ environment Setup guide as part of the prerequisites before starting your OTP integration.

One-Time Passcode delivery

What channels are supported for OTP delivery (SMS, email, voice)?

OTP can be delivered via SMS, voice, and email channels. The channel is configured in your workflow settings in RiskOS™.

What format should phone numbers be in?

Phone numbers must be in E.164 format (e.g., +14155550100). Always validate the phone format before sending the POST request.

How long does it take for an OTP to be delivered?

Delivery times vary by channel, but typically OTPs are delivered within seconds for SMS and email. The exact timing depends on the carrier or email provider.

What happens if the OTP delivery fails?

If delivery fails, you'll receive a response indicating the failure in the data_enrichments array.

Can I customize the OTP message template?

Yes, you can customize SMS and email templates, including multiple languages and custom branding.

Can we control the locale/language of OTP messages?

Locale override is not currently supported. Messages automatically localize based on the phone number's country code, and manual locale control is not available.

Does our OTP service support the appHash parameter for Android auto-fill functionality?

App hash for Android auto-fill is not currently supported.

One-Time Passcode verification

How many times can a user attempt to enter an OTP?

Users can attempt to enter an OTP a maximum of 5 times. After the 5th failed attempt, verification will be blocked.

What happens after the maximum verification attempts are reached?

After 5 failed attempts, the API returns a 400 status code with the message "Max verify attempts reached" and the user must wait through a cooling period before requesting a new OTP.

How long is the cooling period after failed attempts?

The cooling period is 10 minutes. After this time, the user can request a new OTP.

Does the OTP code expire? If so, when?

Yes. Each OTP code expires after a 10-minute session window that starts when the code is first delivered.

What does each decision type mean (ACCEPT, REJECT, REVIEW)?

ACCEPT: OTP verification successful, user can proceed
REJECT: OTP verification failed. Common causes include:
- Session expired — The user submitted the code after the 10-minute OTP session window elapsed.
- Max attempts exceeded — The user used all 5 verification attempts without entering the correct code.
REVIEW: Evaluation is on hold, typically waiting for OTP input.

How to identify this scenario in your logs:

Check for expired-session rejections in the data_enrichments array in the evaluation response.

Verification behavior

Why are there multiple Verify OTP SMS enrichments in one evaluation?

It’s expected to see more than one Verify OTP SMS enrichment in a single evaluation. Each enrichment represents an individual OTP verification attempt.

Resend functionality

How does the OTP resend feature work?

Send a PATCH request to /api/evaluation/{eval_id} with "resend": true in the OTP object. This will resend the OTP to the user through the same channel.

Is the same OTP code sent when I use resend?

Yes, the resend feature sends the same OTP code from the current verification session.

How many times can I resend an OTP?

Generation is rate-limited to 5 requests per minute per destination.

Channel switching

Can users switch from SMS to email after requesting an OTP?

Yes, users can switch channels (e.g., from SMS to Email) by sending a force resume request with "resume": true.

Rate limits & security

What are the rate limits for OTP generation?

The rate limit for generating one-time passcodes is 5 requests per minute per destination.

What happens if I exceed the rate limits?

Exceeding these limits will result in a 429 Too Many Requests response.

API implementation

What's the difference between POST and PATCH requests in the OTP flow?

POST requests are used to initiate a new evaluation and request OTP delivery. PATCH requests are used to verify the OTP code that was entered by the user.

User experience and restrictions

Can I control when OTP is required?

Yes. You can configure OTP to trigger only during high-risk actions.

Best practices

Should I validate phone numbers or emails before sending OTP requests?

Yes, always validate phone numbers (E.164 format) and email addresses before sending OTP requests.

Operations and support

How do I monitor OTP performance?

Use the RiskOS™ Dashboard to track delivery success, retries, and error rates in real time.