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

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

Sandbox is for testing and development purposes where you can use test data and personas. Production is the live environment for real consumer transactions. The Sandbox base URL is https://riskos.sandbox.socure.com/api/evaluation.

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

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

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

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.

If delivery fails, you'll receive a response indicating the failure in the data_enrichments array. You can test this scenario in Sandbox using the phone number +11234567890.

Yes, you can customize SMS and email templates, including multiple languages and custom branding. Contact your Socure Account Manager for template customization.

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

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

Socure operates a shared, managed messaging layer designed for scale. Aggregators integrate once, and all downstream financial institutions (FIs) inherit the same sender identity unless specific customization is needed.

Socure owns:

• Sender setup and registration
• Carrier registration and compliance
• Message throughput and deliverability management

This eliminates the need for per-FI phone numbers, carrier paperwork, or contract flow-down, avoiding a per-client operational model by design.

We use a centralized approach:

• Single sender per region: One centrally managed sender identity serves multiple clients
• Centralized template control: Message templates are controlled and maintained by Socure
• Central compliance management: All carrier and provider compliance is handled centrally

This keeps onboarding lightweight for both aggregators and their downstream FIs.

Customization is available within certain limits. While Socure controls message templates, the messaging can be updated as needed.

• FI-defined SMS copy
• Dynamic fields for verification or document links
• Localization (supported by default)

Yes, FI-defined SMS copy is supported. However, including FI branding is treated by carriers as sender identity signaling and may have compliance implications.

• Per use case: Yes. Different templates are available for distinct use cases (e.g., OTP vs. Document Verification)
• Per FI: Yes, this is supported

• Today: No. SMS template controls are not currently exposed in RiskOS™
• Near term: Configuration remains centralized with Socure
• Longer term: Selective controls for platform partners are being evaluated with strict compliance constraints

• Brand registration: Required for dedicated short codes, but not required for caller names or customized templates
• Use-case declarations: Must be tied to the FI
• Ongoing enforcement: Content enforcement and audits are continuous
• Regional variations: Approval processes and enforcement vary by region

If an FI requires a dedicated sender identity:

• The FI must be registered as a sender
• Carrier forms, approvals, and lead times apply
• Deliverability issues become FI-specific
• The responsible party must own remediation when messages are blocked

Socure handles all registration and compliance centrally.

• Shared sender model across clients
• Socure-managed templates
• Centralized compliance and carrier management
• Zero per-FI operational overhead

• Limited multi-tenant template variants keyed by FI ID
• Guardrailed branding fields within a fixed template structure
• Selective enablement for high-value platform partners

• Per-FI numbers or short codes at scale
• Self-serve SMS editing in RiskOS™

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

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.

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

The document doesn't specify an explicit expiration time, but OTPs are session-based and tied to a verificationId. Best practice is to implement your own timeout (typically 5-10 minutes).

• APPROVE: OTP verification successful, user can proceed
• DECLINE: OTP verification failed or invalid
• REVIEW: Evaluation is on hold, typically waiting for OTP input (status: "Pending OTP Code")

It’s expected to see more than one Verify OTP SMS enrichment in a single evaluation. Each enrichment represents an individual OTP verification attempt. When a user retries—whether due to a typo, delay, or incorrect code—Socure generates a new enrichment.

• status: pending means the user hasn’t successfully verified that attempt (e.g. incorrect or missing code).
• status: approved means the correct code was submitted and the phone number was successfully verified.

To confirm whether verification succeeded, check if any of the OTP enrichments have status: approved. That confirms the phone number has been verified.

If you're only storing the most recent enrichment (e.g. from a webhook), checking that one is usually enough. There’s no scenario where an approved OTP is followed by a new pending one in the same session. If you're storing multiple enrichments, scanning across them ensures you catch successful verifications.

You can also use the attemptCount field to track how many attempts were made.

The evaluation_not_paused error occurs when an OTP PATCH request is made to an evaluation that is no longer waiting for OTP input. This usually means the evaluation has already completed the OTP step—or was never paused.

This can happen if:

• A user starts signup and receives an OTP (Evaluation A).
• They restart the flow with a new email or retry, generating a new evaluation (Evaluation B).
• Your app still attempts to PATCH Evaluation A, which is no longer active.

• Each signup attempt creates a new eval_id.
• Always PATCH the latest eval_id tied to the active OTP session.
• Do not reuse stale eval_ids across retries or multiple signups.

Yes, phone numbers can be reused. Each OTP session is tied to its own evaluation—even when the same phone number is used across different accounts or retries.

Yes, you can resend OTPs using the same eval_id. A PATCH request with "resend": true will issue a new OTP and keep the evaluation in a paused state.

If you're rejecting users based on phone number (e.g., internal test accounts), make sure those rejections happen before the OTP step. For example, a reject reason like "Employee on Deny List" should prevent users from ever reaching the OTP screen or triggering code delivery.

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.

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

No, the attempt count is not reset when resending. The user still has the same remaining verification attempts.

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

Yes, users can switch channels (e.g., from SMS to Email) by sending a force resume request with "resume": true, which skips the current OTP step and moves to the next channel.

Send a PATCH request with "actions": {"resume": true} to skip the current paused step, then send a new POST request for OTP delivery via the new channel. Validate the email format before sending.

No, consumers can only change channels once and cannot toggle between SMS and Email.

The previous OTP session is skipped, and a new OTP is generated for the new channel with a new verificationId.

The rate limit for generating one-time passcodes is 5 requests per minute per destination (phone number or email).

The rate limit for verifying one-time passcodes is 10 requests per minute per verification ID.

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

The system uses multiple security measures: a 5-attempt limit for verification, a 10-minute cooling period after max attempts, and rate limiting on both generation and verification requests.

No, never log or store OTP codes in plain text. This is a critical security consideration. Only store session identifiers like verificationId and attemptCount for tracking purposes.

All data is encrypted in transit (TLS 1.2+) and at rest (AES-256).

Yes. The platform meets PCI, SOC2, GDPR, and other major security frameworks.

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, using the eval_id from the POST response.

The eval_id is a server-generated UUID that uniquely identifies an evaluation attempt. It's required for the PATCH request to verify the OTP and must be included in the URL path.

The verificationId is returned in the OTP delivery response and maintains session continuity. Store it in your application state to track the verification session and ensure you're verifying against the correct OTP session.

When "resume": true is set in the actions object, the workflow will skip the current paused step and resume execution from the next step in the sequence.

Use force resume when a step is stuck, failed, or no longer needed, or when a consumer switches channels to receive OTP (e.g., from SMS to Email). Use this flag with caution as skipping steps may affect the workflow's completeness.

You can integrate using REST APIs or configure it directly through the workflow builder.

Most integrations are live within 2–4 weeks. Sandbox and pre-built connectors can speed up deployment.

Yes. OTP uses standard protocols and integrates with most web, mobile, and IAM systems.

The system can auto-resend, enforce retry limits, and fall back to another channel (e.g., SMS → email/voice).

Use the Sandbox base URL https://riskos.sandbox.socure.com/api/evaluation with your sandbox API key and the test personas provided in the documentation.

For successful tests, use +12105558899 and [email protected]. For unsuccessful OTP delivery, use +11234567890.

The Sandbox environment includes predefined OTP (One-Time Passcode) test cases so you can easily simulate different outcomes:

• Reject: Use 00000 (five zeros) to simulate a permanently rejected code.
• Pending: Use 000000 (six zeros) to simulate a pending or invalid verification attempt.
• Success: Use any other 6-digit numeric code (for example, 123456) to simulate a successful verification.

These scenarios allow you to validate both successful and failure paths in your OTP integration.

Use the phone number +11234567890 in your test request to simulate an unsuccessful OTP delivery scenario.

Use the code 000000 in your verification request to simulate an invalid OTP code and trigger a decline decision.

• 200: Successful request (OTP delivered, verification in progress, or approved)
• 400: Bad request (max attempts exceeded, invalid input)
• 429: Too many requests (rate limit exceeded)

A 400 status code typically indicates that maximum verification attempts have been reached (5 attempts). The response will include "msg": "Max verify attempts reached" and "status": "Error".

Implement proper error handling with try-catch blocks, display user-friendly error messages, and provide an option to retry or resend the OTP. Log the error with correlation IDs for debugging.

• For incorrect OTP with remaining attempts: "Incorrect OTP. You have NaN attempt(s) remaining."
• For max attempts reached: "Maximum verification attempts reached. Please wait 10 minutes before requesting a new OTP."
• Disable input fields and buttons during the cooling period and show a countdown timer.

The data_enrichments array contains details about enrichment processes executed during the workflow, including OTP delivery and verification. Each entry includes the enrichment name, provider, status code, request/response payloads, and whether data was cached.

Check the data_enrichments array for an entry with "enrichment_name": "Deliver OTP SMS" (or Email) and "status_code": 200. The response will include a verificationId confirming successful delivery.

The verification response includes an attemptCount field. Calculate remaining attempts as 5 - attemptCount. Store this in your application state to display to users.

• status: Overall evaluation status set in the workflow (e.g., "ON_HOLD", "CLOSED")
• sub_status: More specific state or reason (e.g., "Pending OTP Code", "Approve", "Decline")

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

For each OTP channel (e.g., SMS, Email, Voice), two events are generated:

• Delivery attempt (request to send the OTP)
• Verification attempt (user submission of the OTP)

If the user reports not receiving the OTP, multiple delivery attempts may be triggered. However, the downstream MFA service does not currently return attempt counts for delivery requests—only verification attempts are counted.

When a user repeatedly enters an incorrect OTP, each failed entry is recorded as a verification attempt. Retry logic and maximum attempt enforcement are managed entirely by the MFA service, which determines when to block further attempts or escalate according to its policy. User is allowed 5 retries for entering the OTP correctly.

Keep them short, clear, and action-oriented to reduce confusion and drop-offs.

The MFA service enforces the following limits (configurable per integration):

• Code length: Default is a 6-digit OTP
• Expiration: OTPs expire after 10 minutes
• Retry attempts: Maximum of 5 verification attempts allowed
• Cooldown: After exceeding retry limits, a 10-minute enforced cooldown is applied before new attempts are permitted

Yes, always validate phone numbers (E.164 format) and email addresses before sending OTP requests. This is considered good practice and helps prevent errors.

Log requests/responses with correlation IDs, status codes, eval_id, verificationId, attempt counts, and error messages. Monitor OTP delivery success in logs and dashboards.

Always redact OTP codes from logs. Never log or store OTP codes in plain text for security reasons.

Monitor: OTP delivery success rates, verification success rates, average attempt counts, rate limit hits, error rates by status code, cooling period triggers, and channel switching patterns.

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

Support is available 24/7 for sender ID, routing, and channel troubleshooting.

Yes. Reports can be exported in CSV or JSON formats for analytics and compliance.

Workflows are configured in the RiskOS™ platform. The workflow name (e.g., "individual_onboarding") must be specified in your API requests. Contact your Account Manager or refer to the RiskOS™ Setup guide for workflow configuration details.

Decision logic is configured within your RiskOS™ workflow settings. The workflow determines when to return APPROVE, DECLINE, or REVIEW based on OTP verification results and other factors.

Review queues are specified in the review_queues array and indicate which queue an evaluation is routed to for manual review if needed. This is configured in your workflow settings.

Tags are arbitrary labels attached to the evaluation (e.g., "OTP Unsuccessful") that help categorize and filter evaluations. They're set by your workflow configuration and appear in the tags array of the response.