OTP verification system

OTP Verification System offers an API consisting of Send OTP and Verify OTP to apply the OTP verification to games.

URL¶

Server	URL
Production	https://otp.qpyou.cn
Sandbox	https://sandbox-otp.qpyou.cn

Authentication methods¶

To implement the API which OTP Send system provides, an authorization token (API KEY) is required. The authentication token is automatically issued after your game registers on AppCenter. Authorization token, which follows JWT (JSON Web Token: https://jwt.io) specification, doesn’t limit the expiry time, so it is available to keep using this token.

Send OTP¶

Send OTP SMS¶

Basic Info

Method	POST
URL	/otp/sms

Request Header

Field	Type
Content-Type	application/json
Authorization	bearer
Topic	Hive Console > Notification > SMS OTP > Sending Information Settings > Registration or Modification > Sending ID

Callback required when you send OTP SMS directly

If OTP SMS is not sent directly by OTP but by yourself, you can receive the necessary information for sending OTP SMS via a callback. In Hive Console > Notification > SMS OTP > Sending Information Settings, select Direct Sending, and the following data will be sent to the registered callback URL in JSON format in the Request Body. Please refer to Callback Request Example and Callback Data.

Request Body

Field	Type	Required	Description
to	String	O	The receiver's phone number
toCountryNo	String	O	The receiver's country code
retry	Boolean	X	This field indicates the existence of your trial to send OTP SMS to the same receiver via this API. If this field is left empty, it is set to `true` if this API was called more than once for the same receiver within the last 5 minutes, and set to `false` if not.
lookup	Boolean	X	This field indicates whether to verify `to` is in valid format for a phone number, and the default values is `false`. If it is `true`, the API response time would approximately be 250ms ~ 2000ms due to the verification process, and normally within 200ms if it is `false`.
lang	String	X	This is language code, and the default value is `en`. the valid language codes: ko en ja zh-cn zh-tw zh-hans zh-hant de fr ru es pt id th vi it tr ar

Response Header

Field	Type
Content-Type	application/json

Response Body

Field	Type	Description
otp	String	OTP number
provider	String	SMS provider
expiry	String	OTP validity time

Request Sample

//sample 1
curl --location 'https://otp.qpyou.cn/otp/send' 
--header 'Authorization: Bearer AUTH_TOKNE_VALUE' 
--header 'Topic: testTopicName' 
--header 'Content-Type: application/json' 
--data '{
    "to" : "01012345678",
    "toCountryNo" : "82",
    "lang" : "ko"
}'
//sample 2
curl --location 'https://otp.qpyou.cn/otp/send' 
--header 'Authorization: Bearer AUTH_TOKNE_VALUE' 
--header 'Topic: testTopicName' 
--header 'Content-Type: application/json' 
--data '{
    "to" : "01012345678",
    "toCountryNo" : "82",
    "lang" : "ko",
    "retry" : true,
    "lookup" : true
}'

Response Sample

{
    "otp" : "123456",
    "provider" : "YOUR SMS PROVIDER",
    "expiry" : "2022-07-20T15:18:06.885195100+09:00[Asia/Seoul]"
}

Callback example¶

curl --location 'https://{your_callback_url}' 
--header 'Content-Type: application/json' 
--data '{
"to":"01012345678",
"toCountryNo":"82",
"lang":"en",
"retry":null,
"lookup":false,
"serviceName":"LocalTest",
"otp":"809881",
"provider":"DIRECTSEND",
"expiry":"2024-06-26T11:36:29.680680500+09:00[Asia/Seoul]",
"expiryTimestamp":1719369389680
}'

Callback data informaton¶

NAME	TYPE	REQUIRED	DESCRIPTION
expiry	String	Yes	OTP validity period (e.g., 2024-06-25T11:39:43.076573600+09:00[Asia/Seoul])
expiryTimestamp	Long	Yes	OTP validity timestamp (e.g., 1719283183076)
lang	String	No	Language code, default is en
lookup	boolean	No	Verify if the to value is a valid phone number format, default is false
otp	String	Yes	OTP numvber
provider	String	Yes	SMS provider, fixed value DIRECTSEND is used for direct sending
retry	boolean	No	Retry option
serviceName	String	Yes	Service name set in the sending information settings menu (in English)
to	String	Yes	Recipient phone number
toCountryNo	String	Yes	Recipient country code

Send OTP email¶

Method	POST
URL	/otp/email

Request Header

Field	Type
Content-Type	application/json
Authorization	bearer
Topic	Hive Console > Notification > SMS OTP > Sending Information Settings > Registration or Modification > Sending ID

Request Body

Field	Type	Required	Description
sender	String	O	Sender's email address
senderName	String	O	Sender's name on email
receiver	String	O	Receiver's email address
subject	String	O	Email title
lang	String	X	This is language code, and the default value is `en`. the valid language codes: ko en ja zh-cn zh-tw zh-hans zh-hant de fr ru es pt id th vi it tr ar

Response Header

Field	Type
Content-Type	application/json

Response Body

Field	Type	Description
otp	String	OTP number
expiry	String	OTP validity time

Request Sample

//sample
curl --location 'https://otp.qpyou.cn/otp/email/send' 
--header 'Authorization: bearer AUTH_TOKEN_VALUE' 
--header 'Topic: testTopicName' 
--header 'Content-Type: application/json' 
--data-raw '{
    "sender" : "staging-no-reply@withhive.com",
    "senderName" : "YOUR SERVICE NAME",
    "receiver" : "com2us@com2us.com",
    "subject" : "OTP EMAIL SEND",
    "lang" : "ko"
}'

Response Sample

{
    "otp" : "123456",
    "expiry" : "2022-07-20T15:19:19.305116+09:00[Asia/Seoul]"
}

Verify OTP¶

Method	POST
URL	/otp/verify

Request Header

Field	Type
Content-Type	application/json
Authorization	bearer
Topic	Hive Console > Notification > SMS OTP > Sending Information Settings > Registration or Modification > Sending ID

Request Body

Field	Type	Required	Description
toCountryNo	String	X	Received country code (Required if OTP is received via SMS)
to	String	X	Received phone number (Required if OTP is received via SMS)
receiver	String	X	Received email address (Required if OTP is received via email)
otp	String	O	Received OTP

Response Header

Field	Type
Content-Type	application/json

Response Body

Field	Type	Desctiprion
result	boolean	OTP verification result

Request Sample 1

// sample 1
curl --location 'https://otp.qpyou.cn/otp/verify' 
--header 'Authorization: bearer AUTH_TOKEN_VALUE' 
--header 'Topic: testTopicName' 
--header 'Content-Type: application/json' 
--data '{
    "toCountryNo" : "82",
    "to" : "01036012891",
    "otp" : "123456"
}'

Request Sample 2

//sample 2
curl --location 'https://otp.qpyou.cn/otp/verify' 
--header 'Authorization: bearer AUTH_TOKEN_VALUE' 
--header 'Topic: testTopicName' 
--header 'Content-Type: application/json' 
--data-raw '{
    "receiver" : "com2us@com2us.com",
    "otp" : "123456"
}'

Response Sample

{
    "result" : true (or false)
}