할인 쿠폰 검증
할인 쿠폰을 사용할 수 있는지 검증할때 사용하는 API입니다.
Note
식별자 정책은 다음을 참고하세요.
Request information¶
| 항목 | 설명 |
|---|---|
| 상용 URL | https://coupon.withhive.com/tp/coupon/discount_coupon_verify |
| Sandbox URL | https://sandbox-coupon.withhive.com/tp/coupon/discount_coupon_verify |
| Method | POST |
| Response Format | JSON |
Request header¶
| 항목 | 설명 | 타입 | 필수여부 | 비고 |
|---|---|---|---|---|
| Content-Type | application/json | String | Y | |
| Authorization | Bearer | String | Y | Hive 인증키 확인 방법: 앱센터 > 프로젝트 관리 > 게임 상세 > 기본 정보 > Hive 인증키 |
Request parameters¶
| 명칭 | 타입 | 필수 여부 (필수: M, 옵션: O) | 설명 |
|---|---|---|---|
| game_index | Integer | M | 앱센터 게임 Index |
| coupon | String | M | 쿠폰번호 |
| cs_code | String | M | 게임 내 사용자 CS CODE |
| language | String | O | 응답 메세지 노출 언어코드 (기본값 영어) 메시지를 화면에 그대로 노출할 경우 사용 |
| discount_type | String | O | 할인 타입 ('percent'으로 고정) |
Response¶
| 명칭 | 타입 | 필수 여부 (필수: M, 옵션: O) | 설명 |
|---|---|---|---|
| code | Integer | M | 응답 코드 (103: 사용 가능) |
| message | String | M | 응답 코드에 따른 결과 메시지 |
| info | Object | O | 사용 가능 일 경우 하위 항목인 percent에 할인 쿠폰 비율 응답 |
| info > percent | Integer | O | 할인 쿠폰 비율 |
Request example¶
curl -L -v
-d '{"game_index": 539,"coupon": "HIVESDKTEST","cs_code": "123456789","language": "ko","discount_type":"percent"}'
-H "Content-Type: text/html"
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY"
https://sandbox-coupon.withhive.com/tp/coupon/api
>> POST /tp/coupon/discount_coupon_verify HTTP/2
> Host: sandbox-coupon.withhive.com
> user-agent: curl/7.68.0
> Content-Type: application/json
> Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY
> Accept: */*
> Content-Length: 105
Response example¶
< HTTP/2 200
< server: nginx
< date: Wed, 27 Aug 2025 12:22:34 GMT
< content-type: application/json; charset=utf-8
{"code":103,"message":"결제를 완료하기 전에는 쿠폰이 사용되지 않습니다.","info": {"percent": 30}}
Response codes¶
| 코드 | 설명 | 메시지 |
|---|---|---|
| 103 | 사용 가능 | 결제를 완료하기 전에는 쿠폰이 사용되지 않습니다. |
| 200 | 요청 파라미터 오류 | 파라미터가 일부 없거나, 파라미터 명이 잘못 되었습니다. |
| 202 | 해당 계정의 사용한도 초과 | 사용 가능한 쿠폰 횟수를 초과 하였습니다. |
| 203 | 그룹 쿠폰의 사용제한 초과 | 사용 가능한 쿠폰 횟수를 초과 하였습니다! |
| 204 | 발급된 쿠폰과 게임정보 미일치 | 해당 게임의 이벤트 쿠폰 교환소에서만 이용하실수 있습니다. |
| 205 | 사용 불가 쿠폰 | 사용할 수 없는 쿠폰입니다. |
| 206 | 할인 쿠폰은 쿠폰 교환소에서 사용 불가 | 입력하신 쿠폰은 웹 상점에서 사용할 수 있습니다. |
| 300 | 쿠폰 번호 자리수가 잘못됨 | 쿠폰 번호가 정확하지 않습니다. 다시 입력해 주세요. |
| 302 | 존재하지 않는 쿠폰 | 존재하지 않는 쿠폰번호 입니다. 다시 확인해 주세요. |
| 303 | 사용 진행 중인 쿠폰 | 이미 사용된 쿠폰입니다. |
| 304 | 사용 완료된 쿠폰 | 이미 사용된 쿠폰입니다. |
| 305 | 쿠폰 사용한도 초과 (모두 사용된 고유 쿠폰) | 발급된 쿠폰이 모두 사용됐습니다. |
| 306 | 사용기간이 만료된 쿠폰 | 사용 기간이 만료된 쿠폰 입니다. |
| 311 | 사용 중지된 쿠폰 | 사용이 중지된 쿠폰입니다. |
| 312 | 사용 기간 이전 쿠폰 | 아직 쿠폰 사용 기간 전입니다. (테스트 쿠폰은 검증 제외) |
| 400 | 아이템 전송 오류 (전체 실패) | 쿠폰 사용이 실패하였습니다. 계속 실패 시 고객센터로 문의해 주세요. |
| 401 | 아이템 전송 오류 (부분 실패) | 쿠폰 사용이 일부 실패하였습니다. 고객센터로 문의해 주세요. |
| 500 | DB 통신 오류 | 쿠폰 사용이 실패하였습니다. 계속 실패 시 고객센터로 문의해 주세요. |
| 501 | 서버 통신 실패 | 쿠폰 사용이 실패하였습니다. 계속 실패 시 고객센터로 문의해 주세요. |