One-Time Password(OTP) API¶

One-Time Password(OTP) 인증 시스템은 게임에 OTP 인증을 적용할 수 있도록 OTP 발송과 OTP 검증으로 구성된 API를 제공합니다.

환경별 접근 URL¶

인증 방식¶

OTP 발송 시스템이 제공하는 API를 사용하려면 먼저 인증 토큰(API KEY)을 발급받아야 합니다. 인증 토큰은 앱 센터에 게임이 등록되면 자동으로 생성됩니다. 인증 토큰은 JSON Web Token(JWT) 명세를 따르며, 만료 시간이 없어 고정적으로 사용할 수 있습니다.

OTP 발송¶

OTP Short Message Service(SMS) 발송¶

• Basic Info

• Request Header

• OTP SMS를 앱 개발사가 직접 발송 시 콜백

  OTP에서 OTP SMS를 직접 발송하는 것이 아니라 앱 개발사가 직접 발송하는 경우, 발송에 필요한 정보를 콜백으로 받을 수 있습니다. 하이브 콘솔 > 노티피케이션 > SMS OTP > 발송 정보 설정에서 직접 발송을 선택하면, 등록한 콜백 URL로 아래 데이터가 Request Body에 JSON 형태로 전달됩니다. 설정 방법은 직접 발송을 참고하세요. 콜백 요청 예시와 전달하는 데이터를 함께 확인하세요.

• Request Body

• Response Header

• Response Body

• Request Sample

다음 예시는 Topic 헤더와 수신자 정보를 포함해 OTP SMS 발송 API를 호출할 때 사용합니다.

//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 SMS 발송 요청이 정상 처리되면 다음과 같은 응답 본문을 받습니다.

{
    "otp" : "123456",
    "provider" : "YOUR_SMS_PROVIDER",
    "expiry" : "2026-03-23T11:00:48.533695818+09:00",
    "expiryTimestamp" : 1774231248
}

콜백 예시¶

앱 개발사가 직접 발송하도록 설정한 경우 등록한 콜백 URL은 다음과 같은 요청 본문을 받습니다.

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
}'

콜백 데이터 정보¶

오류 응답 코드¶

Topic 값이 유효하지 않은 경우¶

요청 헤더의 Topic 값이 하이브 콘솔에 등록한 발송 ID와 일치하지 않으면 이 오류가 발생합니다. Topic 헤더 값과 하이브 콘솔 > 노티피케이션 > SMS OTP > 발송 정보 설정에 등록한 발송 ID를 확인하세요.

{
    "id" : 42202,
    "error" : "NO_TOPIC",
    "reason" : "No such 'Topic' Data"
}

동일한 OTP가 중복 생성된 경우¶

같은 요청을 같은 구간 안에서 두 번 보내면 동일한 OTP가 생성됩니다. 이때 첫 번째 요청은 성공하고 두 번째 요청은 DUPLICATE_OTP_EXISTS로 실패합니다. 현재 구간이 끝난 뒤 다음 구간에서 같은 요청을 다시 보내세요.

{
    "id" : 40902,
    "error" : "DUPLICATE_OTP_EXISTS",
    "reason" : "Already sent OTP to this phone number."
}

24시간 발송 한도를 초과한 경우¶

같은 전화번호로 24시간 동안 허용된 발송 횟수를 넘기면 이 오류가 발생합니다. 이 한도는 고정값이 아닙니다. 아래 예시의 응답 메시지에 포함된 횟수는 설정한 한도 값을 보여주는 예시입니다. 하이브 콘솔 > 노티피케이션 > SMS OTP > 발송 정보 설정에서 일일 발송 한도를 확인하세요.

{
    "id" : 42903,
    "error" : "SMS_LIMIT_EXCEEDED",
    "reason" : "Too many requests in 24 hours. (Can not exceed 10 times)"
}

OTP 검증¶

• Request Header

• Request Body

• Response Header

• Response Body

• Request Sample 1

다음 예시는 수신 전화번호와 OTP 번호를 전달해 OTP를 검증할 때 사용합니다.

// 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" : "01012345678",
    "otp" : "123456"
}'

• Response Sample

OTP가 일치한 경우 응답 본문은 다음과 같습니다.

{
    "result" : true
}