LogoZebo Studio

One-Time Passwords

One-time passwords let you confirm that a customer controls an international phone number without asking them to remember another credential. Commerce creates a short-lived token, sends it by SMS, and records the recipient's verification attempt.

Prerequisites

  • An opaque Commerce API key stored outside client-side code
  • A customer phone number in international format
  • A server-side record that can associate the OTP transaction with the pending action

How the OTP flow works

The public OTP flow currently uses SMS:

  1. Call Initiate OTP transaction with recipient, service_name, and token_size.
  2. Store the returned ot_<TRANSACTION_ID> value and show an OTP input in your application.
  3. Submit the phone number, transaction ID, and user-entered token to Verify OTP.
  4. Continue the protected action only when verification_attempt.result.verdict is pass.

An HTTP 200 response from verification means the attempt was recorded; it does not prove that the token matched. A mismatch is represented by a fail verdict in that response. Do not authorize from HTTP status, delivery state, or transaction status alone.

Initiation rules

The initiation fields that most integrations need are:

  • recipient - Required international phone number
  • sender - Optional sender identifier, 3-12 trimmed characters
  • service_name - Required service name, 2-20 trimmed characters
  • token_alphabet_type - Optional alpha, alphanumeric, or numeric; the default alphabet is alphanumeric
  • token_size - Required token length from 5 through 10
  • validity_duration_in_minutes - Optional validity from 3 through 10,080 minutes; defaults to 10

Set async_delivery to true only if your integration can handle a transaction returned before transmission details are available. Such a transaction can have status pending_delivery; after the SMS is sent and before it is verified, it can have status pending_verification.

Use an idempotency key for initiation retries so one logical attempt does not send duplicate messages. Do not log submitted tokens or verification response bodies.

Implement verification

Follow Verify users with OTP for maintained examples in cURL, TypeScript, Go, Python, PHP, Ruby, Java, and C#. The guide demonstrates the required verdict check and uses opaque environment-based credentials.

Use Lookup OTP transaction to refresh state. Use Cancel OTP transaction to invalidate an abandoned transaction; its reason field is optional.

Was this page helpful?