GetOTPドキュメント

SMS OTP

SMS OTPは、SMSを利用してOTPの実行を可能にします。

SMS OTP APIのリクエスト

SMS OTP APIへのリクエストへ、POSTリクエストを弊社のOTPエンドポイントに送信ください。OTPエンドポイントは、末尾にスラッシュがあることに注意してください:

https://otp.dev/api/verify/

以下の基本的なHTTP認証方法の場合:

説明 必須 データ型
APIキー はい 文字列 mtbi2w4hlendfpxa1igthcu5p6mzxf7k
APIトークン はい 文字列 mpktanoshzf4c81e3bydjl76ixr9wugv

メモ

  • このページよりAPIキーとAPIトークンを取得できます
  • 最大3つのAPIキーを作成できます
  • API呼び出しの回数は、お客様の有効なサブスクリプションにより異なります

以下パラメーター:

名前 説明 必須 データ型 オプション
channel OTP配信のためのチャネル はい 文字列 sms
phone_sms ユーザーの携帯番号(国コードを含む) いいえ 文字列 +60123456789
success_redirect_url OTP成功後のユーザーのリダイレクト先 はい URL https://mysite.test/payments/qHgZiJQ8YF/otp-complete/
fail_redirect_url OTP失敗後のユーザーのリダイレクト先 はい URL https://mysite.test/payments/qHgZiJQ8YF/otp-fail/
callback_url OTP成功後のお客様サイトへのコールバックURL いいえ URL https://mysite.test/payments/otp-callback/
metadata その他の追加したい情報。 いいえ 文字列
JSONオブジェクトの場合、JSON文字列に変換する。
{\"order_id\":\"xfdu48sfdjsdf\", \"agent_id\":2258}
captcha OTPフォームのRecaptcha機能。デフォルトで有効。 いいえ 文字列 true / false false
hide Obfuscate phone_sms value. Disabled by default. いいえ 文字列 true / false true
lang OTP UI言語を変更(プロプランのみの機能)。 いいえ 文字列 en / ja / ko / es / fr ja

メモ

phone_sms パラメータの注意点:

  • パラメータは任意のため、省略した場合、OTPフォームはデフォルトで空の電話番号欄を保持します
  • パラメーターが設定されている場合は、OPTフォームは自動的に電話番号欄に提供された値を設定します
  • 例にあるように、(+)のシンボルから始まる国コードを含む電話番号を設定する必要があります

captcha パラメータの注意点:

以下は、cURLを利用したリクエスの例です:

curl -L -X POST 'https://otp.dev/api/verify/' \
-u 'mtbi2w4hlendfpxa1igthcu5p6mzxf7k:mpktanoshzf4c81e3bydjl76ixr9wugv' \
-F 'channel="sms"' \
-F 'phone_sms="+60123456789"' \
-F 'callback_url="https://mysite.test/payments/otp-callback/"' \
-F 'success_redirect_url="https://mysite.test/payments/qHgZiJQ8YF/otp-complete/"' \
-F 'fail_redirect_url="https://mysite.test/payments/qHgZiJQ8YF/otp-fail/"' \
-F 'metadata="{\"order_id\":\"xfdu48sfdjsdf\", \"agent_id\":2258}"' \
-F 'captcha="true"' \
-F 'hide="true"' \
-F 'lang="ja"'

レスポンスはJSONフォーマットで、HTTP 200 コード ステータスで返却されます:

{
  "otp_id": "vbiwkf149jixuzhao85z",
  "link": "https://otp.dev/api/ui/verify/vbiwkf149jixuzhao85z/sms/",
  "otp_secret": "230q4j20kk9rw5b1zrh4"
}

レスポンスデータの詳細:

名前 説明 データ型
otp_id このリクエストのユニークなOTP ID 文字列 l4lckl9qkx2h54k58hnj
link OTPコードを入力するためにユーザーのリダイレクト先URL 文字列 https://otp.dev/api/ui/verify/vbiwkf149jixuzhao85z/sms/
otp_secret このリクエストのユニークなOTPシークレット 文字列 4gdpu9li6i9654dk6mui

APIコールにエラーがある場合は、この表を参照ください:

エラーコード 説明 HTTPコード レスポンス
N/A 不正なAPIキー / APIトークン 403
{
  "detail": "Verification credentials were not provided."
}
INV-01 指定されたチャネルは無効です 400
{
  "code": "INV-01",
  "message": "Invalid channel specified"
}
INV-02 無効なチャネル 400
{
  "code": "INV-02",
  "message": "Invalid channel"
}
INV-03 Eメールを指定されましたが、適切なチャンネル選択されていません 400
{
  "code": "INV-03",
  "message": "Email specified but appropriate channel not chosen"
}
INV-04 電話番号を指定されましたが、適切なチャンネル選択されていません 400
{
  "code": "INV-04",
  "message": "Phone number specified but appropriate channel not chosen"
}
INV-05 無効の言語 400
{
  "code": "INV-05",
  "message": "Invalid language"
}
INV-06 無効な埋め込みモード 400
{
  "code": "INV-06",
  "message": "Invalid embed mode"
}
INV-07 APIユーザドメインとコールバックURLは一致してません 400
{
  "code": "INV-07",
  "message": "Callback URL doesn't match API user domain"
}
INV-08 APIユーザドメインと成功URLは一致してません 400
{ 
  "code": "INV-08",
  "message": "Success URL doesn't match API user domain"
}
INV-09 APIユーザドメインと失敗URLは一致してません 400
{
  "code": "INV-09",
  "message": "Fail URL doesn't match API user domain"
}
SUB-01 APIリクエスト枠が不足しています 400
{
  "code": "SUB-01",
  "message": "Request quota exhausted for current plan"
}
SUB-02 現在プランによりチャネルクォータ超過 400
{
  "code": "SUB-02",
  "message": "Channel quota exceeded for current plan"
}
SUB-03 サブスクリプションの期限が切れています 400
{
  "code": "SUB-03",
  "message": "Validity of subscription expired"
}
SUB-04 チャンネルがサポートされていません 400
{
  "code": "SUB-04",
  "message": "Invalid channel requested for current plan"
}
SUB-05 現在プランにより無効の言語設定 400
{
  "code": "SUB-05",
  "message": "Invalid lang for plan subscribed. Allowed lang:"
}

SMS OTPの表示

ユーザーをレスポンスに含まれるリンクにリダイレクトする必要があります。

https://otp.dev/api/ui/verify/vbiwkf149jixuzhao85z/sms/

ユーザーはOTPコードをSMSを介して受信し、所定のフォームに入力する必要があります。

SMS OTP フォーム

OTPコールバック

ユーザーがOTPフォームを入力し提出すると、callback_url へのPOSTリクエストが実行されます。

https://mysite.test/payments/otp-callback/

callback_urlは、JSONフォーマットで以下のペイロードをPOSTリクエストとして受け取ります:

{
    "otp_id": "8zphnqslxc0n96utnjau",
    "auth_status": "verified",
    "channel": "sms",
    "otp_secret": "otloxfhrg55zkebcpqks",
    "phone_sms": "+60123456789",  
    "ip_address": "10.9.8.7",
    "metadata": "{\"order_id\":\"xfdu48sfdjsdf\", \"agent_id\":2258}",
    "risk_score": 0.0023
}
名前 説明 データ型
otp_id 初回OTPリクエストからのユニークなOTP ID 文字列 a3rmm7nbe6thgxiaancj
auth_status OTPステータス 文字列 verified
not_verified
channel OTPチャンネル 文字列 sms
otp_secret 初回OTPリクエストからのユニークなOTP シークレット 文字列 cu3089cibcvhfu851428
phone_sms 初回OTPリクエストからの値 文字列 +60123456789
ip_address 認証を通過するユーザーのIPアドレス 文字列 10.9.8.7
metadata 初回OTPリクエストからの追加情報 文字列 {\"order_id\":\"xfdu48sfdjsdf\", \"agent_id\":2258}
risk_score 不正防止スコアリング(プロプランのみの機能)、0が最もリスクが低く、1が最もリスクが高い。スコアリングデータがない場合、およびプロプラン以外の場合はNULLを返します。 フロート 0.0023

メモ

auth_status パラメータの注意点:

  • 値は、ユーザーが正しいOTPを入力したかどうかに依存します
  • 正しいOTPは、verified の値を返却します
  • 不正なOTPは、not_verified の値を返却します

成功リダイレクト

OTPが成功した場合、弊社のサーバーはお客様のユーザーをsuccess_redirect_urlに定義されているURLにリダイレクトします。これは、OTPが成功したことををユーザーに表示するのに便利です。

https://mysite.test/payments/qHgZiJQ8YF/otp-complete/?otp_id=m1zBsh2L0c

お客様の利便性のためにリダイレクトURLにotp_idが含まれていることに注意ください。この値は、お客様のアプリケーションデータを更新するために利用できます。ただし、OTPのコールバックの処理で実施することをお勧めします。

リダイレクト失敗

OTPが失敗した場合、弊社のサーバーはお客様のユーザーをfail_redirect_urlに定義されているURLにリダイレクトします。これは、OTPが失敗したことををユーザーに表示するのに便利です。

https://mysite.test/payments/qHgZiJQ8YF/otp-fail/?otp_id=m1zBsh2L0c

お客様の利便性のためにリダイレクトURLにotp_idが含まれていることに注意ください。この値は、お客様のアプリケーションデータを更新するために利用できます。ただし、OTPのコールバックの処理で実施することをお勧めします。

OTPフローのまとめ

上記の説明のまとめとして以下OTPフロー図をご確認ください

GetOTP OTP フロー