API Redeem Kupon Online Instan

API Version

PUT

/api/coupon/v2/redeem

Request
Response

{
    "cpnNo": "ZJLF0399WQBEQZJM",
    "onsiteToken": "QsBkV0ryiCkxiV4KUNJBSWQcR8MzSlvez4ntLh2Tt2M",
    "userId": "x77hu",
    "memo": "IP Address: 210.123.111.222, Request Page: https://example.com/shop/bags/p112233",
    "processStoreIdx": 22
}

Request Parameters

cpnNo string required: Nomor kupon.
onsiteToken string: Token pertukaran berjangka pendek. v2 tidak menerima kata sandi teks biasa (onsitePwd).
Jika sumber daya memiliki onsiteYn = Y, kirim onsiteToken dari respons API validasi apa adanya.
Idempotency-Key wajib untuk permintaan yang memakai token. Percobaan ulang dengan kunci yang sama memutar ulang hasil pertama; memakai token yang sama dengan kunci berbeda ditolak dengan 400 (kode kesalahan 1228).
Jika toko pemroses ditentukan saat validasi, permintaan ini harus memakai toko yang sama.
userId string: ID pengguna. Digunakan untuk mengidentifikasi penerbit/pengguna kupon.
Harus diisi jika batas penggunaan kupon ditetapkan antara 2–5.
memo string: Catatan referensi internal. Dapat digunakan untuk mencatat IP pengguna, lokasi penggunaan kupon, atau informasi lainnya.
Jika penggunaan kupon tidak terbatas, catatan ini dapat digunakan sebagai pengganti userId untuk membedakan pengguna.
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": null
}

Response Parameters

code integer: Kode respons: 0 = Berhasil, nilai lainnya = Error
message string: Pesan respons. Jika kode bukan 0, pesan error akan dikembalikan.
result null

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).

Idempotency-Key

Untuk mencoba ulang dengan aman saat respons hilang karena kesalahan jaringan, kirim nilai unik per permintaan pada header Idempotency-Key. Anda juga dapat mengirimnya sebagai requestId di body; jika keduanya dikirim dengan nilai berbeda, permintaan ditolak. Format yang diizinkan adalah 8–64 karakter berupa huruf, angka, dan . _ : -.

Jika Anda mengirim ulang permintaan yang sama dengan key yang sama, hasil pertama dikembalikan tanpa diproses ulang. Tidak ada yang diproses dua kali dan webhook tidak dikirim ulang.

Gunakan key yang sama hanya untuk percobaan ulang operasi logis yang sama. Selalu gunakan key baru untuk operasi yang berbeda. Menggunakan key yang sama dengan isi permintaan lain atau untuk operasi lain dapat ditolak dengan 409.

Cara menggunakan dengan API validasi

Karena API penggunaan kupon mengubah status, disarankan untuk memverifikasi terlebih dahulu menggunakan API validasi sebelum memanggilnya.

Dengan memastikan kupon valid sebelumnya, Anda dapat menghindari pemrosesan yang tidak perlu pada kupon yang sudah kedaluwarsa atau telah digunakan.

Alur standar adalah: validasi → penggunaan.

Kapan menggunakan API ini

Gunakan API ini saat Anda perlu menerapkan kupon setelah validasi.

Menandai kupon sebagai digunakan setelah pembayaran berhasil
Mencatat penggunaan diskon saat pesanan dikonfirmasi
Menangani penggunaan di toko atau secara offline
Memperbarui status untuk mencegah penggunaan ganda

Dengan kata lain, ini adalah tahap akhir saat kupon benar-benar digunakan.

Alur penggunaan kupon

Kupon ditandai sebagai telah digunakan berdasarkan kode (cpnNo).

Jumlah penggunaan langsung berkurang saat digunakan
Kupon berubah menjadi tidak dapat digunakan kembali
Penggunaan dicatat berdasarkan data pengguna (userId)
Log tambahan dapat disimpan melalui memo

Proses ini bukan sekadar perubahan status, tetapi transaksi penting yang terkait dengan proses pembayaran.

Identifikasi pengguna dan penggunaan memo

userId digunakan untuk mengidentifikasi pengguna yang menggunakan kupon.

Jika kupon memiliki batas penggunaan 2–5 kali, nilai ini wajib diisi dan mencegah penggunaan ganda oleh pengguna yang sama.

Field memo dapat digunakan untuk mencatat informasi internal seperti IP pengguna, lokasi penggunaan, atau sumber permintaan.
Jika tidak ada batas penggunaan, memo juga dapat digunakan sebagai alternatif userId untuk membedakan pengguna.

Token verifikasi di toko (onsiteToken)

v2 tidak menerima kata sandi toko dalam bentuk teks biasa (onsitePwd). Kirim onsiteToken yang dikembalikan oleh API Validasi tanpa perubahan. Mengirim onsitePwd saja atau bersama onsiteToken akan ditolak dengan 400 (kode kesalahan 1227).

Idempotency-Key wajib untuk permintaan yang menggunakan token. Percobaan ulang dengan Idempotency-Key yang sama akan mengembalikan hasil pemrosesan awal. Menggunakan kembali token yang sama dengan Idempotency-Key berbeda akan ditolak dengan 400 (kode kesalahan 1228).

Toko yang digunakan saat validasi harus sama dengan toko tempat pemrosesan dilakukan. Jika processStoreIdx ditentukan saat validasi, permintaan ini harus menggunakan toko yang sama. Token yang divalidasi tanpa toko tidak dapat dikaitkan dengan toko setelahnya.

Token yang kedaluwarsa, dimanipulasi, sudah digunakan, atau tidak cocok dengan pengikatannya semuanya mengembalikan 1228. Penyebab tersebut sengaja tidak dibedakan agar pihak lain tidak dapat menebak status internal menggunakan token lain.

Token tidak diperlukan untuk sumber daya yang tidak menggunakan verifikasi di toko (onsiteYn = N). v1 tetap menerima onsitePwd dalam bentuk teks biasa.

Contoh penggunaan

Integrasi e-commerce: Panggil API saat pembayaran selesai untuk otomatis menerapkan kupon dan mencatat diskon
Penggunaan di toko: Staf memindai QR, mendapatkan kode kupon, lalu menggunakan API untuk memprosesnya secara instan
Pelacakan penggunaan: Simpan IP dan sumber permintaan di memo untuk analisis penyalahgunaan
Kontrol penggunaan ganda: Gunakan userId untuk mencegah pengguna yang sama melebihi batas penggunaan

Kode kupon yang sama dapat digunakan kembali untuk membuat kupon baru setelah dihapus.

Hal yang perlu diperhatikan

Selalu panggil API ini setelah validasi untuk memastikan keamanan.
Setelah digunakan, kupon tidak dapat digunakan kembali.
Strategi rollback mungkin diperlukan jika pembayaran gagal.
Implementasikan mekanisme untuk mencegah penggunaan ganda akibat permintaan berulang.

API Penggunaan Kupon (Redeem) (v2)