Cashify SDK

SDK TypeScript ringan untuk integrasi Cashify Payment Gateway di Node.js & Bun. Mendukung QRIS Dinamis, Statis, dan E-Wallet monitoring.

📦 Installation

npm install cashify-js
# or
pnpm add cashify-js
# or
bun add cashify-js

⚡ Quick Start

import { Cashify } from 'cashify-js';

const cashify = new Cashify({
  licenseKey: 'YOUR_LICENSE_KEY_FROM_DASHBOARD',
});

// Generate Dynamic QRIS
const transaction = await cashify.generateQRISv2({
  qr_id: 'YOUR_QRIS_ID',
  amount: 10000,
  useUniqueCode: true,
  packageIds: ['id.dana'],
  paymentMethod: 'qris',
  qrType: 'dynamic',
  useQris: true,
});

console.log('Scan QR ini:', transaction.data.qr_string);

📚 Features

• QRIS v1 & v2: Support generate QRIS statis dan dinamis.
• E-Wallet Monitoring: Tanpa QR, hanya monitoring saldo masuk.
• Complete Management: Cek status, cancel, history, dan delete transaksi.
• TypeScript Support: Full typing untuk request & response.

📖 API Reference

Configuration

Inisialisasi Cashify dengan license key dari dashboard.

const cashify = new Cashify({
  licenseKey: 'xyz...',
});

Generate QRIS (v2)

Method paling lengkap untuk membuat transaksi.

const response = await cashify.generateQRISv2({
  qr_id: '...', // Wajib untuk QRIS
  amount: 50000,
  useUniqueCode: true, // Tambah kode unik (misal Rp50.003)
  packageIds: ['id.dana', 'id.ovo'], // App yang dimonitor
  expiredInMinutes: 30,
  paymentMethod: 'qris', // 'qris' atau 'ewallet'
  qrType: 'dynamic', // 'dynamic' atau 'static'
  useQris: true, // Return QR string?
});

E-Wallet (Tanpa QR)

Mode ini untuk monitoring transfer manual (tanpa scan QR).

const ewallet = await cashify.generateQRISv2({
  amount: 50000,
  useUniqueCode: true, // Wajib ON agar nominal unik
  packageIds: ['id.dana'],
  paymentMethod: 'ewallet',
  useQris: false, // Tidak perlu QR
});

// Tampilkan instruksi transfer manual ke user sesuai 'ewallet.data.totalAmount'

Wallet Shortcuts 🚀

Cara cepat generate QRIS untuk e-wallet tertentu.

// Monitor GoPay
const gopay = await cashify.generateQRGopay(50000, { qr_id: 'QR_ID' });

// Monitor DANA
const dana = await cashify.generateQRDana(20000, { qr_id: 'QR_ID' });

// Monitor ShopeePay
const shopee = await cashify.generateQRShopee(15000, { qr_id: 'QR_ID' });

// Monitor Bank (BCA, Mandiri, BNI, BRI, CIMB)
const bca = await cashify.generateQRBca(100000);
const mandiri = await cashify.generateQRMandiri(100000);

Check Payment Status

Cek status transaksi (pending/paid/expired).

const status = await cashify.checkStatus('transaction-id-uuid');
console.log(status.data.status); // 'paid'

Cancel Transaction

Batalkan transaksi yang masih pending.

await cashify.cancelPayment('transaction-id-uuid');

Watch Payment (Real-time)

Monitoring status pembayaran secara otomatis (real-time). SDK akan melakukan polling berkala.

cashify.watchPayment('transaction-id-uuid', {
  interval: 3000, // Cek setiap 3 detik
  timeout: 600000, // Stop otomatis setelah 10 menit
  onStatusChange: (status, response) => {
    console.log('Status berubah:', status);

    if (status === 'paid') {
      console.log('Pembayaran Berhasil! Nominal:', response.data.amount);
    }
  },
  onError: (error) => console.error('Error:', error),
});

Wait For Payment (Async/Await) 🆕

Cara modern (Promise-based) untuk menunggu pembayaran tanpa callback.

try {
  console.log('Menunggu user membayar...');
  const successResponse = await cashify.waitForPayment('transaction-id');
  console.log('PEMBAYARAN LUNAS! ✅');
} catch (err) {
  console.log('Gagal/Timeout/Expired ❌');
}

Stop Watching

Berhenti memonitor transaksi manual.

cashify.stopWatch('transaction-id-uuid');

List Payments

Lihat history transaksi dengan filter & pagination.

const history = await cashify.listPayments({
  page: 1,
  limit: 10,
  status: 'success', // Opsional
  sort: 'newest',
});

Delete Payment History

Hapus riwayat transaksi.

// Hapus satu
await cashify.deletePayment({ transactionId: 'transaction-id-uuid' });

// Hapus banyak
await cashify.deletePayment({ transactionIds: ['id-1', 'id-2'] });

// Hapus SEMUA history (Hati-hati!)
await cashify.deletePayment({ clearAll: true });

QR Generator Utility

Helper untuk membuat link gambar QR Code yang stylish.

const qrUrl = cashify.getQRImageURL({
  data: 'https://cashify.my.id', // String / URL konten QR
  size: '500x500', // Ukuran
  style: 2, // Style: 1, 2, atau 3
  color: 'ea580c', // Warna (Hex tanpa #)
});

console.log(qrUrl);
// Output: https://larabert-qrgen.hf.space/v1/create-qr-code?...

💡 Best Practices

Alur integrasi yang direkomendasikan:

1. Backend Apps: Server kamu create transaksi via cashify.generateQRISv2().
2. Database: Simpan transactionId + totalAmount di database kamu.
3. Frontend: Tampilkan QR/instruksi bayar sesuai totalAmount (termasuk kode unik jika ada).
4. Monitoring: Lakukan polling watchPayment di client atau server side (background job).
5. Completion: Set order jadi "PAID" ketika status berubah menjadi paid atau success.

[!IMPORTANT] Jangan pernah menaruh LICENSE_KEY di frontend (React/Vue/Next.js Client Component). Selalu gunakan SDK ini di sisi Server (Node.js/Bun).

🤝 Contributing

Contributions are welcome!

1. Fork repo
2. Create feature branch
3. Commit changes
4. Push & PR

📄 License

MIT License