Skip to main content
View as Markdown

One-time passwords (OTPs)

Use One-Time Passwords (OTPs) to confirm that a customer controls a phone number or email address before you sign them in, change sensitive account data, or approve an action. Inttegro generates and sends the time-limited code; your application should continue only after verification returns a

Inttegro.OtpVerificationVerdicts.Pass

verdict.

The OTP transaction object

An OTP transaction represents one code from generation through delivery and verification. Initiation and lookup responses never expose the generated code: collect the code from the customer, then submit that value to the verify endpoint.

Properties​

TypeScript SDK responseOtpTransactionv12.0.0
POST/otp/initiate

Initiate OTP transaction

Generate a one-time password, deliver it by SMS to an international phone number or by email to a bare email address, and return a typed transaction ID for verification.

Required attributes​

TypeScript SDK requestInitiateOtpRequestv12.0.0
  • Name
    recipient
    Type
    string
    Description

    International phone number that will receive SMS, such as +233241234567, or a bare email address. The transport is inferred unless specified.

  • Name
    serviceName
    Type
    string
    Description

    Service or application name substituted for {service} in the message template. Length: 2-20 characters.

  • Name
    purpose
    Type
    OTPPurpose
    Required
    required
    Description

    Intent of the verification flow. Supported values are account_creation, account_recovery, email_verification, financial_account_verification, password_reset, payment_confirmation, payment_method_verification, payout_confirmation, phone_verification, sensitive_action, sign_in, transaction_confirmation, and unspecified. Unsupported values are rejected. Use unspecified explicitly for a general verification request.

  • Name
    tokenSize
    Type
    number
    Description

    Generated token length. The current API requires a value from 5 through 10, inclusive.

Optional attributes​

TypeScript SDK requestInitiateOtpRequestv12.0.0
  • Name
    asyncDelivery
    Type
    boolean
    Description

    When false or omitted, the request waits for the initial transmission attempt. When true, the transaction can be returned before transmission details are available, with status

    Inttegro.OtpStatuses.PendingDelivery

    .

  • Name
    messageTemplate
    Type
    string
    Description

    Custom SMS body or email copy. It must include {token} exactly once and can include {service}. Email sends it as the plain-text fallback and renders the copy around the code in a branded HTML layout. For email, custom copy overrides the purpose-specific default body, but the selected purpose still controls the subject and heading. If omitted, the API uses its transport-specific purpose-aware template.

  • Name
    sender
    Type
    string
    Description

    SMS sender identifier (3-12 characters). Email OTP always uses {service_name} <[email protected]>; omit this field for email.

  • Name
    preferredGateway
    Type
    'twilio' | 'vonage' | 'africas-talking' | 'termii' | string
    Description

    Optional SMS gateway. Do not supply it for email OTP; email uses the configured default provider.

  • Name
    transport
    Type
    string union
    Description

    Optional "sms" or "email". A phone recipient selects SMS and an email recipient selects email when omitted.

  • Name
    tokenAlphabet
    Type
    string
    Description

    Custom alphabet for token generation. Pass a string of characters to use (for example, "0123456789ABCDEF" for hexadecimal tokens). Mutually exclusive with tokenAlphabetType—use one or the other, not both.

  • Name
    tokenAlphabetType
    Type
    OTPAlphabetType
    Description

    Predefined alphabet type for token generation. Supported values are Inttegro.OtpAlphabetTypes.Alpha, Inttegro.OtpAlphabetTypes.Alphanumeric, and Inttegro.OtpAlphabetTypes.Numeric. If neither alphabet field is supplied, the default alphabet is alphanumeric. Mutually exclusive with tokenAlphabet.

  • Name
    validityDurationInMinutes
    Type
    number
    Description

    How long the token remains valid. Accepted values are 3 through 10,080 minutes (7 days), inclusive. Defaults to 10 minutes.

The fully rendered SMS, including the generated code and substituted service name, must be no longer than 120 characters; email text is limited to 2,048 characters. The transaction expires after its validity window even if delivery is delayed.

For email OTP, send a bare email recipient and omit the SMS-only preferred_gateway field. The {service_name} <[email protected]> From mailbox and SES provider are selected automatically:

{
  "recipient": "[email protected]",
  "service_name": "Inttegro",
  "token_size": 6,
  "purpose": "sign_in"
}

The verification request uses the returned transaction ID, this same recipient, and the code supplied by the customer.

Response​

With synchronous delivery, inspect transmission.status: Inttegro.OtpTransmissionStatuses.Submitted means the SMS message was submitted for delivery, Inttegro.OtpTransmissionStatuses.Delivered means delivery was confirmed, and Inttegro.OtpTransmissionStatuses.Failed means the delivery attempt failed. For email, accepted means SES accepted the send; it does not prove inbox delivery.

Request

POST/otp/initiate
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.otp.initiate({
  messageTemplate: "Your {service} code is {token}.",
  purpose: "transaction_confirmation",
  recipient: "+233241234567",
  sender: "Acme",
  serviceName: "Acme Bank",
  tokenAlphabetType: "numeric",
  tokenSize: 6,
  validityDurationInMinutes: 10,
})

Response

SDK versionv12.0.0
TransactionResponse {
  transaction: { … },
}
POST/otp/verify

Verify OTP

Record a verification attempt for a user-submitted token. An HTTP 200 response means the attempt was recorded; it does not mean the token matched. Authorize the user or action only when verificationAttempt.result.verdict is Inttegro.OtpVerificationVerdicts.Pass.

Required attributes​

TypeScript SDK requestVerifyOtpRequestv12.0.0
  • Name
    recipient
    Type
    string
    Description

    Phone number or bare email address that received the OTP. Must match the recipient and stored transport from initiation.

  • Name
    token
    Type
    string
    Description

    The OTP token submitted by the user. This is the code they received by SMS or email. Cannot be blank or whitespace-only.

  • Name
    transactionId
    Type
    string
    Description

    Typed ID returned from /otp/initiate, in the form ot_<TRANSACTION_ID>.

The current transaction accepts at most five recorded attempts; after that, initiate a new transaction.

Response​

Returns both transaction and verificationAttempt. The attempt contains verificationAttempt.attemptedAt, verificationAttempt.id, verificationAttempt.presentedToken, verificationAttempt.recipient, and verificationAttempt.result. verificationAttempt.result.verdict is

Inttegro.OtpVerificationVerdicts.Pass

or Inttegro.OtpVerificationVerdicts.Fail; verificationAttempt.result.detail is omitted for a passing result and explains a failed match when available. Treat verificationAttempt.presentedToken as sensitive and exclude verification request and response bodies from logs. Matching and non-matching tokens both produce a successful response. Use verificationAttempt.result.verdict to determine whether verification passed.

Request

POST/otp/verify
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.otp.verify({
  recipient: "+233241234567",
  token: "<OTP_CODE_FROM_USER>",
  transactionId: "ot_<TRANSACTION_ID>",
})

A failed match still returns HTTP 200 with a

Inttegro.OtpVerificationVerdicts.Fail

verdict. The API echoes the submitted value as verificationAttempt.presentedToken; the example uses a placeholder so no real code is exposed.

Response (failed match)

SDK versionv12.0.0
Response {
  verificationAttempt: { … },
  transaction: { … },
}
POST/otp/lookup

Lookup OTP transaction

Retrieve details of an existing OTP transaction by its ID. Check transaction status, delivery state, and verification status.

Required attributes​

TypeScript SDK requestLookupOtpRequestv12.0.0
  • Name
    transactionId
    Type
    string
    Description

    Typed OTP transaction ID to look up.

Response​

Returns the transaction without the generated code or verification-attempt history. Optional cancellation and delivery-attempt fields are omitted when they do not apply.

Request

POST/otp/lookup
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.otp.lookup({
  transactionId: "ot_<TRANSACTION_ID>",
})

Response

SDK versionv12.0.0
TransactionResponse {
  transaction: { … },
}
  • Create customer - Associate verified contact details with a customer record.
  • Send Chime - Send transactional SMS and email notifications after verification.