API Validasi Kupon Online Instan

API Version

GET

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

Request
Response


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

Request Parameters

cpnNostringrequired: Nomor kupon.
processStoreIdx integer: IDX toko tempat permintaan ini benar-benar diproses. Jika dikirim, server memverifikasi kepemilikan organisasi, status aktif, dan izin sebelum mencatatnya dalam riwayat pemrosesan.
Cabang pemrosesan tidak diambil dari permintaan; server menentukannya dari toko ini. Nilai ini berbeda dari toko penerbit (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

codeinteger: Kode respons: 0 = Berhasil, nilai lain = Error
messagestring: Pesan respons. Jika kode tidak sama dengan 0, pesan kesalahan akan dikembalikan.
resultobject: Berhasil diverifikasi: Respons mengembalikan informasi kupon.
Gagal diverifikasi: Respons bernilai null dan dapat dilihat melalui pesan kesalahan.

Token verifikasi di toko (onsiteToken)

Respons API Validasi v2 tidak menyertakan kata sandi toko dalam bentuk teks biasa (onsitePwd). Sebagai gantinya, API mengembalikan onsiteToken yang berlaku selama 180 detik.

Tujuannya adalah meminimalkan paparan kata sandi dalam teks biasa, bukan memperkuat autentikasi. API Validasi tidak memverifikasi kata sandi itu sendiri, sehingga token ini tidak menambahkan faktor autentikasi baru. Masa berlaku yang singkat, penggunaan satu kali, dan pengikatan konteks membatasi penggunaan ulang token.

Item	Nilai
Masa berlaku	180 detik. Masa berlaku juga dikembalikan melalui `onsiteTokenExpiresIn`.
Jumlah penggunaan	Satu kali. Setelah token digunakan, hanya percobaan ulang dengan `Idempotency-Key` yang sama yang mengembalikan hasil awal.
Pengikatan	Organisasi, akun kunci API, sumber daya, tindakan, dan toko pemroses yang dikonfirmasi saat validasi
Digunakan untuk	Penukaran kupon, penukaran hadiah stempel, dan pembaruan stempel dengan `useYn = Y`

Token tidak diterbitkan untuk sumber daya yang tidak menggunakan verifikasi di toko (onsiteYn = N). API Validasi v1 tetap mengembalikan onsitePwd dalam bentuk teks biasa.

Menentukan toko pemroses

Parameter	Arti	Deskripsi
`processStoreIdx`	Toko pemroses	Toko tempat permintaan ini benar-benar diproses. Opsional; jika dikirim, server memverifikasi kepemilikan organisasi, status aktif, dan izin sebelum mencatatnya dalam riwayat pemrosesan.

Cabang pemroses tidak diterima dari permintaan. Server menentukannya dari toko yang Anda tentukan dan mencatatnya.

Jika cakupan penggunaan adalah BRANCH, permintaan hanya diproses bila cabang toko pemroses yang terverifikasi sama dengan cabang penggunaan, atau bila Anda melakukan autentikasi dengan kata sandi di tempat cabang tersebut. Tanpa keduanya, permintaan ditolak.

Parameter yang tidak dapat digunakan — branchIdx (cabang penerbit), storeIdx (toko penerbit), useScope (cakupan penggunaan), dan useBranchIdx (cabang penggunaan) adalah kebijakan penerbitan yang sudah tersimpan dan tidak dapat diubah melalui API ini. Jika dikirim, akan ditolak dengan 400 (kode kesalahan 1227).

Apa yang dapat ditentukan dari hasil validasi?

API ini tidak hanya sekadar memeriksa “valid / tidak valid”.
Dirancang agar developer dapat membangun logika keputusan sendiri berdasarkan data kupon yang detail.

Dengan respons (result), Anda dapat menentukan:

Apakah diskon dapat diterapkan dan menghitung nilainya
Apakah kupon hanya berlaku untuk pengguna tertentu (userId, userEml)
Apakah batas penggunaan telah terlampaui (useCnt, useLimit)
Apakah kupon sudah kedaluwarsa atau belum aktif (strtYmd, endYmd)
Apakah kondisi tertentu terpenuhi (online/offline, dll.) (onsiteYn)
URL tujuan setelah kupon diterapkan (url)

Artinya, ini bukan sekadar hasil sederhana,
melainkan API berbasis data untuk logika fleksibel di level aplikasi.

Metode validasi

Validasi dilakukan berdasarkan kode kupon (cpNo) dengan mempertimbangkan berbagai kriteria.

Ketersediaan
Masa berlaku
Batas penggunaan
Syarat pengguna
Lingkungan penggunaan

Hasil dikembalikan dalam bentuk data terstruktur, bukan hanya nilai boolean sederhana.

Cara menggunakan data respons

Objek result berisi semua informasi utama kupon.

Developer dapat menggunakan data ini untuk:

Menghitung dan menampilkan diskon secara real-time di frontend
Membatasi penggunaan kupon hanya untuk pengguna tertentu
Menerapkan logika berdasarkan jumlah pembayaran
Menampilkan pesan UI sesuai status kupon (kedaluwarsa, sudah digunakan, dll.)

Contoh penggunaan

Validasi sebelum pembayaran: Validasi kupon terlebih dahulu dan terapkan hanya jika valid
Pesan pengguna: Tampilkan pesan sesuai hasil validasi (kedaluwarsa atau sudah digunakan)
Perhitungan diskon: Gunakan (disc, discType) untuk menghitung total pembayaran

Kode kupon yang sama dapat digunakan kembali setelah dihapus.

Hal yang perlu diperhatikan

Hasil validasi mencerminkan kondisi saat permintaan dan dapat berubah sebelum digunakan.
Selalu gunakan alur: validasi → penggunaan (Redeem).
Mengandalkan hanya validasi di sisi klien berisiko terhadap keamanan.
Lakukan verifikasi ulang perhitungan diskon di server untuk memastikan akurasi dan keamanan.

API Validasi Kupon (v2)