One-time passwords (OTPs)

Use One-Time Passwords (OTPs) to confirm that a customer controls a phone number 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 pass verdict.

Operations

Initiate OTP transaction
Verify OTP
Lookup OTP transaction

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

Name
cancel_reason
Type
string
Description
Explanation for why this transaction was canceled. Omitted unless status is canceled.
Name
canceled_at
Type
timestamp
Description
When this transaction was canceled. Omitted unless status is canceled.
Name
expires_at
Type
timestamp
Description
When this token expires and can no longer be verified.
Name
full_message
Type
string
Description
The message template with the service name substituted and the token placeholder preserved as {token}. The token value is not included in this field.
Name
id
Type
string
Description
Unique identifier for this transaction—use it to verify tokens and lookup transaction status.
Name
initiated_at
Type
timestamp
Description
When this transaction was created and token generation began.
Name
status
Type
string
Description
Current transaction status. Possible values are canceled, expired, pending, pending_delivery, pending_verification, and verified. pending_delivery means delivery-attempt fields are not available yet; pending_verification means the message was sent and the transaction is waiting for a verification attempt.
transmissionobjectDelivery details for the OTP message. Recipient and sender are always present; attempt fields are omitted until delivery begins.Click or tap to expand
- Name
  recipient
  Type
  string
  Description
  Normalized international phone number targeted by the SMS.
- Name
  sender_id
  Type
  string
  Description
  Sender identifier shown to the recipient—alphanumeric sender ID or short code.
- Name
  sent_at
  Type
  timestamp
  Description
  When the message was sent. Omitted until the delivery attempt.
- Name
  sent_via
  Type
  string
  Description
  Delivery mechanism. OTP transactions currently use sms. Omitted until the delivery attempt starts.
- Name
  status
  Type
  string
  Description
  Delivery status: submitted, delivered, or failed. Omitted until the delivery attempt.

Non-success responses return a top-level error object. Use the HTTP status for control flow, inspect error.code and error.fix_code when present, and keep message and detail for display or diagnostics rather than parsing their prose. Some OTP failures currently omit a stable code, so clients must not require one.

POST/otp/initiate

Initiate OTP transaction

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

Required attributes

Name
recipient
Type
string
Description
International phone number that will receive the SMS, such as +233241234567.
Name
service_name
Type
string
Description
Service or application name substituted for {service} in the message template. Length: 2-20 characters.
Name
token_size
Type
integer
Description
Generated token length. The current API requires a value from 5 through 10, inclusive.

Optional attributes

Name
async_delivery
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 pending_delivery.
Name
message_template
Type
string
Description
Custom SMS template. It must include {token} and can include {service}. If omitted, the API uses its configured template.
Name
purpose
Type
string
Description
Label for the verification flow, such as login or transaction_confirm. Defaults to unspecified.
request_metaobjectRequest-specific controls that do not change the OTP being initiated.Click or tap to expand
- Name
  idempotency_key
  Type
  string
  Description
  Optional request key.
Name
sender
Type
string
Description
Sender identifier shown to the recipient. If supplied, its trimmed length must be 3-12 characters. If omitted, the API uses its configured sender.
Name
token_alphabet
Type
string
Description
Custom alphabet for token generation. Pass a string of characters to use (e.g., 0123456789ABCDEF for hexadecimal tokens). Mutually exclusive with token_alphabet_type—use one or the other, not both.
Name
token_alphabet_type
Type
enum
Description
Predefined alphabet type for token generation. Supported values are alpha, alphanumeric, and numeric. If neither alphabet field is supplied, the default alphabet is alphanumeric. Mutually exclusive with token_alphabet.
Name
validity_duration_in_minutes
Type
integer
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. The transaction expires after its validity window even if delivery is delayed.

Response

Returns 200 when the transaction is created, 400 for malformed input, 401 when authorization fails, and 422 when the OTP request or delivery could not be completed. With synchronous delivery, inspect transmission.status: submitted means the message was accepted for delivery, delivered means delivery was confirmed, and failed means the delivery attempt failed.

Request

POST/otp/initiate

curl https://api.inttegro.com/otp/initiate \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: otp-login-67890" \
  -d '{
    "message_template": "Your {service} code is {token}.",
    "purpose": "transaction_confirm",
    "recipient": "+233241234567",
    "sender": "Acme",
    "service_name": "Acme Bank",
    "token_alphabet_type": "numeric",
    "token_size": 6,
    "validity_duration_in_minutes": 10
  }'

SDK versionv8.2.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_confirm",
  recipient: "+233241234567",
  sender: "Acme",
  serviceName: "Acme Bank",
  tokenAlphabetType: "numeric",
  tokenSize: 6,
  validityDurationInMinutes: 10,
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  params := map[string]any{
    "message_template": "Your {service} code is {token}.",
    "purpose": "transaction_confirm",
    "recipient": "+233241234567",
    "sender": "Acme",
    "service_name": "Acme Bank",
    "token_alphabet_type": "numeric",
    "token_size": 6,
    "validity_duration_in_minutes": 10,
  }
  result, err := client.Otp.Initiate(ctx, params)
  if err != nil {
    log.Fatal(err)
  }
  _ = result
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.otp.initiate(inttegro.otp.InitiateRequest(
  message_template="Your {service} code is {token}.",
  purpose="transaction_confirm",
  recipient="+233241234567",
  sender="Acme",
  service_name="Acme Bank",
  token_alphabet_type="numeric",
  token_size=6,
  validity_duration_in_minutes=10,
))

SDK versionv5.3.0

<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->otp->initiate([
  'message_template' => 'Your {service} code is {token}.',
  'purpose' => 'transaction_confirm',
  'recipient' => '+233241234567',
  'sender' => 'Acme',
  'service_name' => 'Acme Bank',
  'token_alphabet_type' => 'numeric',
  'token_size' => 6,
  'validity_duration_in_minutes' => 10,
]);

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.otp.initiate(
  message_template: "Your {service} code is {token}.",
  purpose: "transaction_confirm",
  recipient: "+233241234567",
  sender: "Acme",
  service_name: "Acme Bank",
  token_alphabet_type: "numeric",
  token_size: 6,
  validity_duration_in_minutes: 10
)

SDK versionv5.2.0

import com.inttegro.Client;
import com.inttegro.otp.InitiateOtpParams;
import com.inttegro.otp.OtpAlphabetType;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = InitiateOtpParams.builder()
      .messageTemplate("Your {service} code is {token}.")
      .purpose("transaction_confirm")
      .recipient("+233241234567")
      .sender("Acme")
      .serviceName("Acme Bank")
      .tokenAlphabetType(OtpAlphabetType.NUMERIC)
      .tokenSize(6)
      .validityDurationInMinutes(10)
      .build();
    var result = client.otp().initiate(params);
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.Otp.InitiateAsync(new {
  message_template = "Your {service} code is {token}.",
  purpose = "transaction_confirm",
  recipient = "+233241234567",
  sender = "Acme",
  service_name = "Acme Bank",
  token_alphabet_type = "numeric",
  token_size = 6,
  validity_duration_in_minutes = 10,
});

Response

Object
JSON

SDK versionv8.2.0

TransactionResponse {
  transaction: { … },
}

SDK versionv8.2.0

{
  "transaction": {
    "expires_at": "2026-08-28T10:10:00Z",
    "full_message": "Your Acme Bank code is {token}.",
    "id": "ot_<TRANSACTION_ID>",
    "initiated_at": "2026-08-28T10:00:00Z",
    "status": "pending_verification",
    "transmission": { … }
  }
}

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 verification_attempt.result.verdict is pass.

Required attributes

Name
recipient
Type
string
Description
Phone number that received the OTP. Must match the recipient from the initiation request.
Name
token
Type
string
Description
The OTP token submitted by the user. This is the code they received via SMS. Cannot be blank or whitespace-only.
Name
transaction_id
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 verification_attempt. The attempt contains attempted_at, id, presented_token, recipient, and result. result.verdict is pass or fail; result.detail is omitted for a pass and explains a failed match when available. Treat presented_token as sensitive and exclude verification request and response bodies from logs.

Returns 200 for both matching and non-matching tokens, 400 for malformed input, 401 when authorization fails, and 422 when the transaction is expired, canceled, over its attempt limit, or otherwise cannot be verified.

Request

POST/otp/verify

response=$(curl https://api.inttegro.com/otp/verify \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Idempotency-Key: otp-verify-67890" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "+233241234567",
    "token": "<OTP_CODE_FROM_USER>",
    "transaction_id": "ot_<TRANSACTION_ID>"
  }')

jq -e '.verification_attempt.result.verdict == "pass"' <<< "$response"

SDK versionv8.2.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>",
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  params := map[string]any{
    "recipient": "+233241234567",
    "token": "<OTP_CODE_FROM_USER>",
    "transaction_id": "ot_<TRANSACTION_ID>",
  }
  result, err := client.Otp.Verify(ctx, params)
  if err != nil {
    log.Fatal(err)
  }
  _ = result
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.otp.verify(inttegro.otp.VerifyRequest(
  recipient="+233241234567",
  token="<OTP_CODE_FROM_USER>",
  transaction_id="ot_<TRANSACTION_ID>",
))

SDK versionv5.3.0

<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->otp->verify([
  'recipient' => '+233241234567',
  'token' => '<OTP_CODE_FROM_USER>',
  'transaction_id' => 'ot_<TRANSACTION_ID>',
]);

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.otp.verify(
  recipient: "+233241234567",
  token: "<OTP_CODE_FROM_USER>",
  transaction_id: "ot_<TRANSACTION_ID>"
)

SDK versionv5.2.0

import com.inttegro.Client;
import com.inttegro.otp.VerifyOtpParams;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = VerifyOtpParams.builder()
      .recipient("+233241234567")
      .token("<OTP_CODE_FROM_USER>")
      .transactionId("ot_<TRANSACTION_ID>")
      .build();
    var result = client.otp().verify(params);
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.Otp.VerifyAsync(new {
  recipient = "+233241234567",
  token = "<OTP_CODE_FROM_USER>",
  transaction_id = "ot_<TRANSACTION_ID>",
});

A failed match still returns HTTP 200 with a fail verdict. The API echoes the submitted value as presented_token; the example uses a placeholder so no real code is exposed.

Response (failed match)

Object
JSON

SDK versionv8.2.0

Response {
  verificationAttempt: { … },
  transaction: { … },
}

SDK versionv8.2.0

{
  "verification_attempt": { … },
  "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

Name
transaction_id
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. Returns 200 when found, 400 for malformed input, 401 when authorization fails, and 422 when the transaction does not exist or cannot be loaded.

Request

POST/otp/lookup

curl https://api.inttegro.com/otp/lookup \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "ot_<TRANSACTION_ID>"
  }'

SDK versionv8.2.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>",
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  params := map[string]any{
    "transaction_id": "ot_<TRANSACTION_ID>",
  }
  result, err := client.Otp.Lookup(ctx, params)
  if err != nil {
    log.Fatal(err)
  }
  _ = result
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.otp.lookup(inttegro.otp.LookupRequest(
  transaction_id="ot_<TRANSACTION_ID>",
))

SDK versionv5.3.0

<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->otp->lookup([
  'transaction_id' => 'ot_<TRANSACTION_ID>',
]);

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.otp.lookup(
  transaction_id: "ot_<TRANSACTION_ID>"
)

SDK versionv5.2.0

import com.inttegro.Client;
import com.inttegro.otp.LookupOtpParams;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = LookupOtpParams.builder()
      .transactionId("ot_<TRANSACTION_ID>")
      .build();
    var result = client.otp().lookup(params);
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.Otp.LookupAsync(new {
  transaction_id = "ot_<TRANSACTION_ID>",
});

Response

Object
JSON

SDK versionv8.2.0

TransactionResponse {
  transaction: { … },
}

SDK versionv8.2.0

{
  "transaction": {
    "expires_at": "2026-08-28T10:10:00Z",
    "full_message": "Your Acme Bank code is {token}.",
    "id": "ot_<TRANSACTION_ID>",
    "initiated_at": "2026-08-28T10:00:00Z",
    "status": "pending_verification",
    "transmission": { … }
  }
}

Create customer - Associate verified contact details with a customer record.
Send Chime - Send transactional SMS and email notifications after verification.

The OTP transaction object

Properties​

Initiate OTP transaction

Required attributes​

Optional attributes​

Response​

Request

Response

Verify OTP

Required attributes​

Response​

Request

Response (failed match)

Lookup OTP transaction

Required attributes​

Response​

Request

Response

Related resources

Properties

Required attributes

Optional attributes

Response

Required attributes

Response

Required attributes

Response