Login Mitra Bisnis Punya bisnis? Daftar disini.
GenZ Cards

Untuk Developer

Bangun integrasi dengan API Mitra Kami

Integrasikan GenZ Cards dengan POS, aplikasi mobile, atau backend Anda. Gunakan REST untuk membaca dan menulis data, serta webhook untuk event loyalitas real-time.

Baca dokumentasi Dashboard mitra

Semua yang Anda butuhkan untuk integrasi

Tersedia pada paket merchant dengan Akses Developer. Semua lalu lintas data menggunakan format JSON melalui HTTPS.

  • API REST

    Pelanggan, kartu loyalitas, stempel, dan voucher — buat program dan jalankan operasional loyalitas harian dengan JSON di mana saja.

  • Webhook

    Pengiriman HTTPS bertandatangan saat anggota mendapatkan poin, mengumpulkan stempel, atau menukarkan penawaran.

  • Kunci API (API keys)

    Bearer token dengan awalan lpk_. Buat, rotasi, dan cabut akses kunci langsung dari dashboard mitra.

Referensi

Dokumentasi API

Autentikasi, endpoint, webhook, dan penanganan error untuk v1.

Ikhtisar

API Mitra tersedia pada paket langganan yang memiliki Akses Developer. Setiap request dibatasi sesuai dengan ruang lingkup organisasi Anda.

URL Dasar (Base URL)

https://genz.cards/api/v1

Versi v1 · Body JSON · UTF-8

Buat kartu loyalitas, kartu stempel, dan voucher dengan metode POST, atau kelola melalui dasbor mitra. Gunakan rute bersarang (nested routes) untuk mendaftarkan anggota, mengkreditkan poin, memberikan stempel, dan menukarkan voucher.

Mulai cepat

Hanya butuh beberapa menit dari awal hingga request pertama Anda berhasil diautentikasi.

  1. Masuk ke dashboard mitra.
  2. Buka Developer → Kunci API dan buat kunci baru dengan nama tertentu.
  3. Salin kunci tersebut segera — kunci ini hanya ditampilkan sekali dan akan disimpan sebagai hash yang aman.
  4. Kirimkan Authorization: Bearer KUNCI_ANDA pada setiap request.
  5. Opsional: konfigurasikan Webhook untuk menangkap event secara real-time.

Autentikasi

Kunci API menggunakan awalan lpk_. Kunci yang telah dicabut akan mengembalikan status 401. 

# Tampilkan daftar pelanggan
curl -X GET "https://genz.cards/api/v1/customers?per_page=15" \
  -H "Authorization: Bearer lpk_your_secret_key" \
  -H "Accept: application/json"
# Tambah poin dari transaksi pembelian
curl -X POST "https://genz.cards/api/v1/loyalty-cards/12/transactions" \
  -H "Authorization: Bearer lpk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"customer_email":"alex@example.com","reference":"POS-88421","amount":24.50,"currency":"USD"}'

Request

Header, idempotensi, dan pembungkus (envelope) respons.

  • Content-Type — application/json untuk body POST.
  • Accept — application/json untuk respons.
  • Idempotensi — Idempotency-Key pada request POST tulis dan buat baru.
  • Paginasi — data, meta, links.next.
# Pembungkus ketika sukses (Success envelope)
{
  "data": { ... },
  "meta": { "request_id": "9f3c2a1e-..." }
}

Endpoint

Path relatif terhadap https://genz.cards/api/v1

Pelanggan

Cari dan buat data pelanggan yang memenuhi syarat untuk program Anda.

GET /customers

Tampilkan daftar pelanggan

Mendukung parameter ?page=, ?per_page= (maksimal 100), dan ?search= (nama, email, atau nomor telepon).

Contoh request

GET https://genz.cards/api/v1/customers?search=alex&per_page=15

Contoh respons

{
  "data": [
    {
      "id": 1042,
      "name": "Muhammad Al-Hafidz",
      "email": "al-hafidz@contoh.com",
      "phone": "+62822721123",
      "created_at": "2026-08-02T14:30:00+00:00"
    }
  ],
  "meta": {
    "request_id": "9f3c2a1e-8b4d-4e1a-9c2d-1a2b3c4d5e6f",
    "current_page": 1,
    "last_page": 3,
    "per_page": 15,
    "total": 42
  },
  "links": {
    "first": "https://genz.cards/api/v1/customers?page=1",
    "last": "https://genz.cards/api/v1/customers?page=3",
    "prev": null,
    "next": "https://genz.cards/api/v1/customers?page=2"
  }
}
GET /customers/{id}

Ambil data pelanggan

Contoh request

GET https://genz.cards/api/v1/customers/1042

Contoh respons

{
  "data": {
    "id": 1042,
    "name": "Muhammad Al-Hafidz",
    "email": "al-hafidz@contoh.com",
    "phone": "+62822721123",
    "created_at": "2026-08-02T14:30:00+00:00"
  },
  "meta": {
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
POST /customers

Buat baru atau kembalikan data pelanggan yang sudah ada

Jika email sudah terdaftar, profil yang sudah ada akan dikembalikan dengan status HTTP 200.

Contoh request

POST https://genz.cards/api/v1/customers

{
  "email": "al-hafidz@contoh.com",
  "name": "Muhammad Al-Hafidz",
  "phone": "+62822721123"
}

Contoh respons

{
  "data": {
    "id": 1042,
    "name": "Muhammad Al-Hafidz",
    "email": "al-hafidz@contoh.com",
    "phone": "+62822721123",
    "created_at": "2026-08-16T10:00:00+00:00"
  },
  "meta": {
    "request_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  }
}

Kartu loyalitas

Buat dan tampilkan daftar kartu, daftarkan pelanggan, serta kirim transaksi poin.

GET /loyalty-cards

Tampilkan daftar kartu loyalitas

Contoh request

GET https://genz.cards/api/v1/loyalty-cards

Contoh respons

{
  "data": [
    {
      "id": 12,
      "name": "Poin Insider",
      "card_identifier": "CABANG SUDIRMAN",
      "is_active": true,
      "earn_spend_amount": "100.000",
      "earn_points": 1,
      "earn_currency": "IDR",
      "initial_bonus_points": 50,
      "expiry_date": "2027-12-31"
    }
  ],
  "meta": {
    "request_id": "c3d4e5f6-a7b8-9012-cdef-123456789012"
  }
}
POST /loyalty-cards

Buat kartu loyalitas

Kosongkan card_identifier untuk membuat kode dompet digital secara otomatis. Memerlukan ID lokasi mitra dari akun Anda.

Contoh request

POST https://genz.cards/api/v1/loyalty-cards

{
  "name": "Poin Insider",
  "partner_location_id": 2,
  "date_issued": "2026-08-16",
  "earn_spend_amount": 100.000,
  "earn_points": 1,
  "earn_currency": "IDR",
  "initial_bonus_points": 50,
  "is_active": true
}

Contoh respons

{
  "data": {
    "id": 13,
    "name": "Poin Insider",
    "card_identifier": "042-118-307-591",
    "is_active": true,
    "earn_spend_amount": "100.000",
    "earn_points": 1,
    "earn_currency": "IDR",
    "initial_bonus_points": 50,
    "expiry_date": null
  },
  "meta": {
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
GET /loyalty-cards/{id}

Ambil data kartu loyalitas

Contoh request

GET https://genz.cards/api/v1/loyalty-cards/12

Contoh respons

{
  "data": {
    "id": 12,
    "name": "Poin Insider",
    "card_identifier": "CABANG SUDIRMAN",
    "is_active": true,
    "earn_spend_amount": "100.000",
    "earn_points": 1,
    "earn_currency": "IDR",
    "initial_bonus_points": 50,
    "expiry_date": "2027-12-31"
  },
  "meta": {
    "request_id": "d4e5f6a7-b8c9-0123-def0-234567890123"
  }
}
POST /loyalty-cards/{id}/enrollments

Daftarkan pelanggan ke kartu loyalitas

Otomatis memberikan poin bonus awal kartu jika dikonfigurasi.

Contoh request

POST https://genz.cards/api/v1/loyalty-cards/12/enrollments

{
  "customer_email": "al-hafidz@contoh.com"
}

Contoh respons

{
  "data": {
    "enrollment": {
      "id": 88,
      "customer_id": 1042,
      "loyalty_card_id": 12,
      "created_at": "2026-08-16T10:05:00+00:00"
    },
    "initial_bonus_transactions": [
      {
        "id": 501,
        "type": "bonus",
        "customer_id": 1042,
        "loyalty_card_id": 12,
        "points_delta": 50,
        "points_balance_after": 50,
        "purchase_reference": null,
        "occurred_at": "2026-08-16T10:05:00+00:00"
      }
    ]
  },
  "meta": {
    "request_id": "e5f6a7b8-c9d0-1234-ef01-345678901234"
  }
}
POST /loyalty-cards/{id}/transactions

Kreditkan poin dari pembelian atau sesuaikan saldo

Kirim nominal (amount) + mata uang (currency) untuk aturan perolehan berbasis pembelian, atau kirim poin saja untuk penyesuaian manual.

Contoh request

POST https://genz.cards/api/v1/loyalty-cards/12/transactions

{
  "customer_email": "al-hafidz@contoh.com",
  "reference": "POS-88421",
  "amount": 245.000,
  "currency": "IDR",
  "notes": "Counter sale"
}

Contoh respons

{
  "data": {
    "id": 502,
    "type": "earn",
    "customer_id": 1042,
    "loyalty_card_id": 12,
    "points_delta": 2,
    "points_balance_after": 52,
    "purchase_reference": "POS-88421",
    "occurred_at": "2026-08-16T10:12:00+00:00"
  },
  "meta": {
    "request_id": "f6a7b8c9-d0e1-2345-f012-456789012345"
  }
}

Kartu stempel

Buat dan tampilkan daftar kartu stempel, lalu berikan stempel setelah pembelian yang memenuhi syarat.

GET /stamp-cards

Tampilkan daftar kartu stempel

Contoh request

GET https://genz.cards/api/v1/stamp-cards

Contoh respons

{
  "data": [
    {
      "id": 7,
      "name": "KOPI ACEH",
      "is_active": true,
      "stamps_required_for_reward": 10,
      "stamps_per_purchase": 1,
      "valid_from": "2026-01-01",
      "valid_until": "2028-12-31"
    }
  ],
  "meta": {
    "request_id": "a7b8c9d0-e1f2-3456-0123-567890123456"
  }
}
POST /stamp-cards

Buat kartu stempel

Contoh request

POST https://genz.cards/api/v1/stamp-cards

{
  "name": "KOPI ACEH",
  "partner_location_id": 2,
  "valid_from": "2026-01-01",
  "valid_until": "2028-12-31",
  "stamps_required_for_reward": 10,
  "stamps_per_purchase": 1,
  "reward_title": "Gratis Kopi Aceh",
  "is_active": true
}

Contoh respons

{
  "data": {
    "id": 8,
    "name": "KOPI ACEH",
    "is_active": true,
    "stamps_required_for_reward": 10,
    "stamps_per_purchase": 1,
    "valid_from": "2026-01-01",
    "valid_until": "2028-12-31"
  },
  "meta": {
    "request_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  }
}
POST /stamp-cards/{id}/stamps

Berikan stempel kepada pelanggan

Contoh request

POST https://genz.cards/api/v1/stamp-cards/7/stamps

{
  "customer_id": 1042,
  "reference": "POS-88422",
  "amount": 55.000,
  "currency": "IDR",
  "notes": "Pembelian Kopi Aceh"
}

Contoh respons

{
  "data": [
    {
      "id": 301,
      "type": "earn",
      "customer_id": 1042,
      "stamp_card_id": 7,
      "stamps_delta": 1,
      "stamps_balance_after": 4,
      "purchase_reference": "POS-88422",
      "occurred_at": "2026-08-16T10:15:00+00:00"
    }
  ],
  "meta": {
    "request_id": "b8c9d0e1-f2a3-4567-1234-678901234567"
  }
}

Voucher

Buat dan tampilkan daftar voucher, lalu tukarkan untuk pelanggan saat proses pembayaran (checkout).

GET /vouchers

Tampilkan daftar voucher

Contoh request

GET https://genz.cards/api/v1/vouchers

Contoh respons

{
  "data": [
    {
      "id": 3,
      "name": "Promo Merdeka",
      "voucher_code": "MERDEKA",
      "is_active": true,
      "discount_type": "persen",
      "discount_value": "20",
      "valid_from": "2026-03-01",
      "valid_until": "2028-05-31"
    }
  ],
  "meta": {
    "request_id": "c9d0e1f2-a3b4-5678-2345-789012345678"
  }
}
POST /vouchers

Buat voucher

voucher_code harus unik di dalam organisasi Anda (dapat berupa huruf, angka, tanda hubung, garis bawah).

Contoh request

POST https://genz.cards/api/v1/vouchers

{
  "name": "Promo Merdeka",
  "partner_location_id": 2,
  "voucher_code": "MERDEKA",
  "valid_from": "2026-03-01",
  "valid_until": "2028-05-31",
  "discount_type": "persen",
  "discount_value": 20,
  "is_active": true
}

Contoh respons

{
  "data": {
    "id": 4,
    "name": "Promo Merdeka",
    "voucher_code": "MERDEKA",
    "is_active": true,
    "discount_type": "persen",
    "discount_value": "20",
    "valid_from": "2026-03-01",
    "valid_until": "2028-05-31"
  },
  "meta": {
    "request_id": "c3d4e5f6-a7b8-9012-cdef-123456789012"
  }
}
POST /vouchers/{id}/redeem

Tukarkan voucher milik pelanggan

Contoh request

POST https://genz.cards/api/v1/vouchers/3/redeem

{
  "customer_email": "al-hafidz@contoh.com",
  "order_amount": 45.000,
  "order_reference": "POS-88423",
  "partner_location_id": 2,
  "notes": "Beli di toko"
}

Contoh respons

{
  "data": {
    "id": 19,
    "voucher_id": 3,
    "customer_id": 1042,
    "voucher_code": "MERDEKA",
    "order_amount": "45.000",
    "discount_amount": "9.000",
    "order_reference": "POS-88423",
    "redeemed_at": "2026-08-16T10:18:00+00:00"
  },
  "meta": {
    "request_id": "d0e1f2a3-b4c5-6789-3456-890123456789"
  }
}

Webhook

Pengiriman HTTPS bertandatangan saat anggota berinteraksi dengan program Anda.

# Header pengiriman (Delivery headers)
Content-Type: application/json
X-Loyalty-Event: loyalty.points_earned
X-Loyalty-Timestamp: 1715789400
X-Loyalty-Signature: <hmac-sha256-hex>

Verifikasi menggunakan HMAC-SHA256(timestamp + "." + raw_body, signing_secret) 

# Muatan
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "loyalty.points_earned",
  "created_at": "2026-05-16T12:00:00+00:00",
  "data": { ... }
}

Tipe Event

Peristiwa Deskripsi
customer.created Profil pelanggan baru telah dikaitkan dengan organisasi Anda.
customer.updated Profil pelanggan atau detail pendaftaran mengalami perubahan.
loyalty.enrolled Seorang pelanggan mendaftar untuk kartu loyalitas.
loyalty.points_earned Poin dikreditkan dari pembelian atau bonus.
loyalty.points_redeemed Poin digunakan untuk hadiah atau penukaran.
loyalty.reward_claimed Seorang pelanggan mengklaim hadiah loyalitas.
stamp.issued Stempel ditambahkan ke kartu stempel pelanggan.
stamp.reward_fulfilled Hadiah kartu stempel ditandai sebagai telah terpenuhi.
voucher.redeemed Voucher ditukarkan di suatu lokasi.
referral.completed Pencapaian (milestone) program referral telah diselesaikan.

Error

Objek error JSON yang konsisten di seluruh API.

{
  "error": {
    "code": "validation_error",
    "message": "The given data was invalid.",
    "details": { "email": ["The email field is required."] }
  }
}
HTTP Arti
400 Permintaan buruk (Bad request) — Validasi gagal atau struktur JSON salah.
401 Tidak sah (Unauthorized) — Kunci API (API Key) hilang atau tidak valid.
403 Dilarang (Forbidden) — Kunci API valid tetapi tidak diizinkan untuk mengakses sumber daya atau paket ini.
404 Tidak ditemukan (Not found) — Sumber daya tidak ada atau berada di luar organisasi Anda.
429 Terlalu banyak permintaan — Batas kuota terlampaui — silakan coba kembali secara berkala (exponential backoff).
500 Kesalahan server — Kegagalan sistem yang tidak terduga — hubungi tim dukungan jika masalah berlanjut.