SValePay Node.js SDK

Official SDK untuk integrasi SValePay Core API. Cepat, ringan (Zero Dependency), dan mendukung penuh TypeScript & JavaScript.

🚀 Fitur Utama

• Core API Focus: Hanya fitur esensial (createPayment & getStatus).
• TypeScript Support: Definisi tipe data lengkap untuk kenyamanan coding.
• White Label Error: Pesan error otomatis disesuaikan dengan brand SValePay.
• Node.js 18+ Ready: Menggunakan standar fetch modern.

📦 Instalasi

Gunakan npm atau yarn untuk menginstal:

npm install @starvale-sdk/svalepay
# atau
yarn add @starvale-sdk/svalepay

🛠️ Penggunaan (Usage)

1. Inisialisasi Client

Anda membutuhkan Business ID dan Secret Key yang bisa didapatkan dari Dashboard Merchant SValePay.

JavaScript (CommonJS):

const { SValePay } = require('@starvale-sdk/svalepay');

const svale = new SValePay({
  businessId: 'SVP-XXXXX', // Business ID Anda
  secretKey: 'svp_live_xxxx', // Secret Key Anda
  timeout: 10000 // Opsional: default 10 detik
});

TypeScript (ES Modules):

import { SValePay } from '@starvale-sdk/svalepay';

const svale = new SValePay({
  businessId: 'SVP-XXXXX',
  secretKey: 'svp_live_xxxx'
});

2. Membuat Pembayaran (Create Payment)

Gunakan fungsi ini untuk menginisialisasi transaksi baru. Jika Anda mengisi payment_method dengan QRIS, Anda akan langsung mendapatkan kode QR (QR String).

async function handleCreatePayment() {
  try {
    const response = await svale.createPayment({
      amount: 25000,
      customer_email: '[email protected]',
      description: 'Pembayaran Order #123',
      payment_method: 'QRIS', // Opsional: Isi 'QRIS' untuk mendapatkan kode QR langsung
      external_id: 'ORDER-123' // ID unik dari sistem Anda (Invoice ID)
    });

    console.log('Transaction ID:', response.data.trx_id);
    console.log('Checkout URL:', response.data.checkout_url);
    
    // Jika menggunakan QRIS, gunakan payment_code untuk generate QR
    if (response.data.payment_code) {
      console.log('QRIS String:', response.data.payment_code);
    }
  } catch (error) {
    console.error('Error:', error.message);
  }
}

Parameter Request (CreatePaymentRequest): | Field | Tipe | Wajib | Deskripsi | | :--- | :--- | :--- | :--- | | amount | number | Ya | Nominal pembayaran dalam IDR. | | customer_email | string | Ya | Alamat email pelanggan. | | external_id | string | Tidak | ID unik dari sistem Anda (direkomendasikan). | | description | string | Tidak | Deskripsi transaksi. | | payment_method | string | Tidak | Contoh: QRIS atau OVO. | | success_url | string | Tidak | URL pengalihan saat sukses (untuk Payment Link). |

3. Cek Status Pembayaran (Check Status)

Gunakan fungsi ini untuk memverifikasi apakah pelanggan sudah membayar.

async function checkStatus(trx_id) {
  try {
    const status = await svale.getStatus(trx_id);
    
    if (status.data.status === 'success') {
      console.log('Pembayaran Lunas!');
    } else {
      console.log('Status Saat Ini:', status.data.status); // 'pending', 'expired', dsb.
    }
  } catch (error) {
    console.error('Gagal Cek Status:', error.message);
  }
}

🛡️ Penanganan Error (Error Handling)

SDK ini menggunakan class SValePayError. Jika terjadi kesalahan pada API, pesan error akan otomatis disesuaikan agar tetap menjaga brand SValePay (White Label).

try {
  await svale.createPayment({...});
} catch (err) {
  console.log(err.name); // 'SValePayError'
  console.log(err.code); // Kode status HTTP (401, 400, 500, dsb.)
  console.log(err.message); // Pesan error yang sudah disanitasi
}

📄 Lisensi

MIT License - © 2024 StarVale Technology.