# Request OTP Code

Sends a one-time password (OTP) code to the customer's email address for verification. The OTP code is valid for a limited time and can only be used once. Rate limited to 3 requests per minute per customer.

Endpoint: POST /eapi/v0/verifications/otp
Version: 0 BETA
Security: HMACAuth

## Security:

  - `HMACAuth` (unknown)
    apiKey in header Authorization

## Request fields (application/json):

  - `identityReference` (string, required)
    Identity reference of an existing customer created through our platform
    Example: c-13344

  - `email` (string, required)
    The customer's email address
    Example: user@example.com

## Request examples:

  - `Request OTP for customer` (unknown)
    Send OTP code to customer's registered email address

## Response 200:

  - `200` (unknown)
    OTP sent successfully to customer's email address

## Response 200 fields (application/json):

  - `message` (string, required)
    Success message indicating OTP was sent.
    Example: OTP sent successfully

## Response 200 headers (application/json):

  - `X-RateLimit-Limit` (integer)
    Maximum number of requests allowed per minute
    Example: 3

  - `X-RateLimit-Remaining` (integer)
    Number of requests remaining in current window
    Example: 2

## Response 401:

  - `401` (unknown)
    Authentication failed or missing credentials.
**Common Causes**:
- Missing Authorization header
- Invalid API key
- Expired or invalid HMAC signature
- Incorrect timestamp (must be within 5 minutes of server time)

## Response 401 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Unauthenticated.

  - `code` (integer)
    HTTP status code
    Example: 401

  - `traceId` (string)
    Unique identifier for this error instance
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 403:

  - `403` (unknown)
    Email verification feature is not enabled for this merchant. Contact support to enable this feature.

## Response 403 fields (application/json):

  - `message` (string)
    Example: Email validation is not enabled, please contact us to enable this feature.

  - `code` (integer)
    Example: 403

## Response 422:

  - `422` (unknown)
    Validation error - invalid or missing identity reference

## Response 422 fields (application/json):

  - `message` (string)
    Example: The identity reference field is required.

  - `errors` (object)

## Response 429:

  - `429` (unknown)
    Rate limit exceeded for OTP requests or verification attempts. Rate limits reset after 60 seconds.

## Response 429 fields (application/json):

  - `message` (string)
    Example: Too many OTP requests. Please try again later.

  - `code` (integer)
    Example: 429

  - `traceId` (string)
    Example: abc123def456

## Response 429 headers (application/json):

  - `Retry-After` (integer)
    Number of seconds to wait before retrying
    Example: 60

  - `X-RateLimit-Reset` (integer)
    Unix timestamp when the rate limit resets
    Example: 1710648000

## Response 500:

  - `500` (unknown)
    Unexpected server error.
**Action**:
- Retry with exponential backoff (up to 3 attempts)
- If error persists, contact support with the traceId

**Note**: This is a temporary issue on our side, not a problem with your request.

## Response 500 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Server Error

  - `code` (integer)
    HTTP status code
    Example: 500

  - `traceId` (string)
    Unique identifier for this error instance. **Important**: Include this when contacting support.
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 200 examples:

  - `OTP sent successfully` (unknown)

## Response 422 examples:

  - `Missing identity reference` (unknown)

  - `Invalid customer reference` (unknown)

## Response 429 examples:

  - `OTP request rate limit exceeded` (unknown)
    Maximum 3 OTP requests per minute per customer

  - `OTP verification rate limit exceeded` (unknown)
    Maximum 4 verification attempts per minute per customer