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

• Response Sample

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

{
    "result" : true
}