쿠폰 검증 API (v2)

쿠폰 검증 API는 쿠폰 사용 처리 전에 해당 쿠폰이 유효한지 확인하는 기능을 제공합니다.

단순 사용 가능 여부뿐 아니라 할인 정보, 사용 조건, 사용자 데이터까지 함께 반환되어 다양한 비즈니스 로직에 활용할 수 있습니다.

이 API는 퍼스널 요금제 이상에서만 사용할 수 있습니다.

API Version

GET

/api/coupon/v2/validate?cpnNo={cpnNo}

Request
Response


GET /api/coupon/v2/validate
     ?cpnNo=ZJLF0399WQBEQZJM
     &processStoreIdx=22

Request Parameters

cpnNo string required: 쿠폰 번호.
processStoreIdx integer: 이 요청이 실제로 처리되는 매장 IDX. 보내면 조직 소유·활성 상태·권한을 서버가 확인한 뒤 처리 이력에 기록합니다.
처리 지점은 요청으로 받지 않고 이 매장에서 서버가 확인합니다. 발행 매장(storeIdx)과는 다른 값입니다.

{
    "code": 0,
    "message": "",
    "result": {
        "cpnNo": "ZJLF0399WQBEQZJM",
        "domain": "https://vvd.bz",
        "nm": "$100 off cake coupon",
        "grpIdx": 271,
        "grpNm": "Birthday coupon",
        "discTypeIdx": 457,
        "discCurrency": "USD",
        "formatDiscCurrency": "$60",
        "disc": 60.0,
        "strtYmd": "2025-01-01",
        "endYmd": "2025-12-31",
        "useLimit": 1,
        "imgUrl": "https://file.vivoldi.com/coupon/2024/11/08/lmTFkqLQdCzeBuPdONKG.webp",
        "onsiteYn": "Y",
        "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
        "onsiteTokenExpiresIn": 180,
        "memo": "60% off cake with coupon at the venue",
        "url": "",
        "userId": "user08",
        "userNm": "Emily",
        "userPhnno": "202-555-0173",
        "userEml": "test@gmail.com",
        "userEtc1": "",
        "userEtc2": "",
        "useCnt": 0,
        "regYmdt": "2024-11-17 17:29:25",
        "branchIdx": 11,
        "branchNm": "Gangnam Branch",
        "storeIdx": 22,
        "storeNm": "Gangnam Station Store",
        "issueScope": "BRANCH",
        "useScope": "BRANCH",
        "useBranchIdx": 11,
        "useBranchNm": "Gangnam Branch"
    }
}

Response Parameters

code integer: 응답 코드: 0 = 성공, 그 외 값 = 오류
message string: 응답 메시지입니다. 응답 코드가 0이 아니면, 오류 관련 메시지가 반환됩니다.
result object: 검증 성공 시: 응답 값에 쿠폰 정보가 반환됩니다.
검증 실패 시: 응답 값은 null이며, 오류 메시지를 통해 확인할 수 있습니다.

현장 인증 토큰 (onsiteToken)

v2 검증 API 응답에는 현장 비밀번호 평문(onsitePwd)이 포함되지 않습니다. 대신 180초 동안 유효한 onsiteToken을 반환합니다.

목적은 인증 강도를 높이는 것이 아니라 평문 비밀번호 노출을 최소화하는 것입니다. 검증 API는 비밀번호 자체를 확인하지 않으므로, 이 토큰이 새로운 인증 요소를 추가하는 것은 아닙니다. 대신 짧은 유효 시간, 1회 사용, 컨텍스트 바인딩을 통해 토큰의 재사용 범위를 제한합니다.

항목	값
유효 시간	180초. 유효 시간은 `onsiteTokenExpiresIn`으로 함께 반환됩니다.
사용 횟수	1회. 사용 후에는 동일한 `Idempotency-Key`로 재시도하는 경우에만 최초 처리 결과를 반환합니다.
바인딩	조직, API 키 계정, 리소스, 행위, 검증 시 확인한 처리 매장
적용 대상	쿠폰 사용 처리, 스탬프 혜택 사용 처리, 스탬프 수정의 `useYn = Y`

현장 인증을 사용하지 않는 리소스(onsiteYn = N)에는 토큰을 발급하지 않습니다. v1 검증 API는 기존과 동일하게 onsitePwd 평문을 반환합니다.

처리 매장 지정

파라미터	의미	설명
`processStoreIdx`	처리 매장	이 요청이 실제로 처리되는 매장입니다. 선택 항목이며, 보내면 조직 소유·활성 상태·권한을 서버가 확인한 뒤 처리 이력에 기록합니다.

처리 지점은 요청으로 받지 않습니다. 지정한 매장이 속한 지점을 서버가 확인해 기록합니다.

사용 가능 범위가 BRANCH인 경우, 확인된 처리 매장의 지점이 사용 가능 지점과 같거나 해당 지점의 현장 비밀번호로 인증해야 처리됩니다. 둘 다 없으면 거부됩니다.

사용할 수 없는 파라미터 — branchIdx(발행 지점), storeIdx(발행 매장), useScope(사용 가능 범위), useBranchIdx(사용 가능 지점)는 이미 저장된 발행 정책이라 이 API로 바꿀 수 없습니다. 함께 보내면 400(오류 코드 1227)으로 거부됩니다.

검증 결과로 무엇을 판단할 수 있나요?

이 API는 단순히 “사용 가능 / 불가”를 확인하는 것을 넘어,
쿠폰에 포함된 상세 정보를 기반으로 개발자가 직접 판단 로직을 구성할 수 있도록 설계되어 있습니다.

응답 데이터(result)를 활용하면 다음과 같은 판단이 가능합니다.

할인 적용 가능 여부 및 할인 금액 계산
특정 사용자 대상 쿠폰인지 여부 확인 (userId, userEml)
사용 횟수 제한 초과 여부 (useCnt, useLimit)
쿠폰 만료 여부 (strtYmd, endYmd)
특정 조건(온/오프라인 등) 충족 여부 (onsiteYn)
쿠폰 적용 후 이동 URL 확인 (url)

즉, 서버에서 단순 결과를 주는 것이 아니라
애플리케이션 레벨에서 자유롭게 로직을 구성할 수 있는 데이터 기반 API입니다.

쿠폰 검증 방식

쿠폰 번호(cpNo)를 기준으로 다양한 상태를 종합적으로 검증합니다.

존재 여부
유효 기간
사용 제한
사용자 조건
적용 가능 환경

검증 결과는 단순 Boolean이 아닌 구조화된 데이터 형태로 반환됩니다.

응답 데이터 활용 방법

응답의 result 객체에는 쿠폰의 모든 핵심 정보가 포함됩니다.

개발자는 이 데이터를 기반으로 다음과 같은 처리를 할 수 있습니다.

프론트엔드에서 할인 금액 즉시 계산 및 표시
특정 사용자만 쿠폰 적용 가능하도록 제한
결제 금액 조건에 따라 쿠폰 적용 여부 분기
쿠폰 상태에 따른 UI 메시지 처리 (만료, 사용 완료 등)

활용 예시

결제 전 유효성 확인: 사용자가 쿠폰 번호를 입력하면 검증 API를 먼저 호출해 유효 여부를 확인하고, 유효한 경우에만 할인을 적용합니다.
사용 전 안내 메시지: 만료되었거나 이미 사용된 쿠폰인 경우, 검증 결과에 따라 사용자에게 적절한 안내 메시지를 표시합니다.
결제 금액 기반 할인 계산: 검증 API 응답의 할인 정보(disc, discType)를 이용해 최종 결제 금액을 계산합니다.

쿠폰이 삭제되어도 동일한 쿠폰 번호로 다시 생성하여 복구할 수 있습니다.

사용 시 주의사항

검증 결과는 조회 시점 기준이며, 실제 사용 시 상태가 변경될 수 있습니다.
반드시 검증 → 쿠폰 사용(Redeem) 호출 구조로 구성해야 합니다.
클라이언트에서만 검증 결과를 신뢰하는 것은 보안상 위험합니다.
할인 계산은 서버에서 한 번 더 검증하는 것이 안전합니다.