GetOTPドキュメント

Eメール OTP

EメールOTPは、Eメールを利用してOTPを利用可能にします。

EメールOTP APIへのリクエスト

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

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

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

以下パラメーター：

例

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

curl -L -X POST 'https://otp.dev/api/verify/' \
-u 'mtbi2w4hlendfpxa1igthcu5p6mzxf7k:mpktanoshzf4c81e3bydjl76ixr9wugv' \
-F 'channel="email"' \
-F 'email="ali@getotp.test"' \
-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": "kpb9c0a357pdf4jaz05c",
  "link": "https://otp.dev/api/ui/verify/kpb9c0a357pdf4jaz05c/email/",
  "otp_secret": "dxn07vdzqy7wfblk89r9"
}

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

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

{
  "detail": "Verification credentials were not provided."
}

{
  "code": "INV-01",
  "message": "Invalid channel specified"
}

{
  "code": "INV-02",
  "message": "Invalid channel"
}

{
  "code": "INV-03",
  "message": "Email specified but appropriate channel not chosen"
}

{
  "code": "INV-04",
  "message": "Phone number specified but appropriate channel not chosen"
}

{
  "code": "INV-05",
  "message": "Invalid language"
}

{
  "code": "INV-06",
  "message": "Invalid embed mode"
}

{
  "code": "INV-07",
  "message": "Callback URL doesn't match API user domain"
}

{ 
  "code": "INV-08",
  "message": "Success URL doesn't match API user domain"
}

{
  "code": "INV-09",
  "message": "Fail URL doesn't match API user domain"
}

{
  "code": "SUB-01",
  "message": "Request quota exhausted for current plan"
}

{
  "code": "SUB-02",
  "message": "Channel quota exceeded for current plan"
}

{
  "code": "SUB-03",
  "message": "Validity of subscription expired"
}

{
  "code": "SUB-04",
  "message": "Invalid channel requested for current plan"
}

{
  "code": "SUB-05",
  "message": "Invalid lang for plan subscribed. Allowed lang:"
}

EメールOTPを表示

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

https://otp.dev/api/ui/verify/kpb9c0a357pdf4jaz05c/email/

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

OTPコールバック

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

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

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

{
    "otp_id": "8zphnqslxc0n96utnjau",
    "auth_status": "verified",
    "channel": "email",
    "otp_secret": "otloxfhrg55zkebcpqks",
    "email": "ali@getotp.test",  
    "ip_address": "10.9.8.7",
    "metadata": "{\"order_id\":\"xfdu48sfdjsdf\", \"agent_id\":2258}",
    "risk_score": 0.0023
}

成功リダイレクト

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フロー図をご確認ください