---
title: "Initiate OTP"
method: POST
path: "/initiate"
tags: ["OTP Recover (Sync flow)"]
---

# Initiate OTP

`POST /initiate`

Triggers an OTP SMS to the customer if the order is eligible for recovery.
This call should be triggered from the backend after receiving a “declined” response and that the order is eligible for OTP process from /api/decide.
The response will provide the widget token which is the JWT (JSON Web Token) for the OTP widget.

## Headers

- `x-riskified-shop-domain` string, required
- `x-riskified-hmac-sha256` string, required
- `content_type` 'application/json', required
- `accept` 'application/vnd.riskified.com; version=2', required

## Request body

- OtpInitiateRequest
  - `id` string, required — The unique identifier for the order
  - `challenge_access_token` string, required — A unique token generated by the merchant. It is used to validate that the order matches the OTP after a successful OTP verification. This is critical to ensure that users cannot tamper with the OTP verification process. The token has to be at least 32 characters long and hard to guess - we recommend on using UUID
  - `localization_language` 'en-US' | 'es-ES' | 'fr-FR', required — The widget localization language. The language codes currently supported: * “en-US” (English US) * “es-ES” (Spanish Spain) * “fr-FR” (French France) Contact your Integration Engineer for instructions on expanded language support.
  - `contact_details` string — The merchant’s support contact email
  - `channel_method` ChannelMethod
    - `channel_type` 'Sms', required — The OTP sending medium - currently only 'Sms' (case-sensitive) is available
    - `sender_name` string, required — The name of the sender (merchant) that will appear in the SMS

## Response `200`

Widget token successfully returned

- OtpInitiateResponse
  - `widgetToken` string — The JWT (JSON Web Token) for the OTP widget

## Other responses

- `400` — Bad Request Possible values: - "Bad request: Order state is not eligible for recovery" - "Bad request: Recovery eligibility duration has already expired"
- `401` — Unauthorized
- `403` — Unauthorized request: Order has already passed the recovery flow
- `500` — There was an internal server error.

---

[API](https://skmtc.dev/riskified/apis/chargeback-guarantee.md) · [All operations](https://skmtc.dev/riskified/apis/chargeback-guarantee/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/riskified/chargeback-guarantee/revisions/2b7df5bce861/schema)