GetOTP ロゴ

GetOTPドキュメント

マルチ-チャンネル OTP

マルチ-チャンネル OTPは、Eメール OTP、SMS OTP、音声 OTPの組み合わせを利用して、マルチプルOTPを利用可能にします。

マルチ-チャンネル OTP APIのリクエスト

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

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

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

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

メモ

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

以下パラメーター：

名前 説明 必須 データ型 オプション 例
channel OTP配信のためのチャンネル。カンマで分割し、複数設定可能 はい 文字列 email,sms,voice
email ユーザー Eメールアドレス いいえ 文字列 ali@getotp.test
phone_sms ユーザーの携帯番号（国コードを含む） いいえ 文字列 +60123456789
phone_voice ユーザーの携帯番号（国コードを含む） いいえ 文字列 +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 email / phone_sms / phone_voice value. Disabled by default. いいえ 文字列 true / false true
lang OTP UI言語を変更（プロプランのみの機能）。 いいえ 文字列 en / ja / ko / es / fr ja

メモ

channel パラメータの注意点:

  • 利用可能なチャンネルを複数設定できます。例えば、Eメールと音声チャンネル email,voiceのマルチ OTP

email、 phone_sms、 phone_voice パラメータの注意点:

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

captcha パラメータの注意点:

例

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

curl -L -X POST 'http://localhost:8090/api/' \
-u 'mTbI2W4hleNdFPxA1iGtHcu5p6MZXf7K:mpktanoshzf4c81e3bydjl76ixr9wugv' \
-F 'channel="email,sms,voice"' \
-F 'email="ali@getotp.test"' \
-F 'phone_sms="+60123456789"' \
-F 'phone_voice="+60123456789"' \
-F 'callback_url="https://mysite.com/payments/otp-callback/"' \
-F 'success_redirect_url="https://mysite.com/payments/qHgZiJQ8YF/otp-complete/"' \
-F 'fail_redirect_url="https://mysite.com/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": "3zphnqslxc0n96utnjxz",
  "link": "https://getotp.com/authenticate/3YOikMm9TP/multi/",
  "otp_secret": "etloxfhrg11zkebcpqks"
}

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

名前 説明 データ型 例
otp_id このリクエストのユニークなOTP ID 文字列 3zphnqslxc0n96utnjxz
link OTPコードを入力するためにユーザーのリダイレクト先URL 文字列 https://getotp.com/authenticate/3YOikMm9TP/multi/
otp_secret このリクエストのユニークなOTPシークレット 文字列 etloxfhrg11zkebcpqks

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:"
}

OTP フォーム

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

https://getotp.com/authenticate/3YOikMm9TP/multi/

ユーザーは、各OTPフォームに入力する必要があります。

マルチチャンネルOTPフォーム

OTPコールバック

エンドユーザ様があるチャネルのOTP認証完了するたびにPOSTリクエストは送信されます。

例えば、マルチチャネルのEメール、SMSと音声を利用すると、callback_urlに３つのコールバックが発生します。 

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

メモ

各チャネルのコールバック詳細について以下のリンクからご参照ください。

成功リダイレクト

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 フロー