Pakaidonk SNAP Client SDK

Module Node.js modular untuk mempermudah integrasi dengan API Gateway Pakaidonk SNAP standard (QRIS, E-Money Payment, Customer Topup, Settlement Status, dan Balance Inquiry).

1. Prasyarat & Kebutuhan

Sebelum memulai, pastikan Anda telah menyiapkan komponen berikut di project Anda:

A. Dependencies (Instalasi NPM)

SDK ini menggunakan axios untuk HTTP request dan dotenv untuk pembacaan kredensial.

npm install axios dotenv

B. Pasangan Kunci RSA (RSA Key Pair)

Siapkan pasangan kunci RSA Anda dalam format .pem dan letakkan di dalam folder Key/ di root project Anda:

• Key/private_key.pem (Kunci privat untuk membuat asimetrik signature)
• Key/public_key.pem (Kunci publik)

C. Konfigurasi .env

Buat file .env di root project Anda dengan kredensial sandbox dari Pakaidonk:

PartnerID=
AccountNo=
ClientKey=
Secret=
QRIS_merchant_ID=
StoreID=
URL_SANDBOX=

2. Cara Penggunaan (Quick Start)

A. Inisialisasi Client

Secara default, client akan membaca kredensial langsung dari .env dan memuat kunci RSA dari folder ./Key/ secara otomatis:

require('dotenv').config();
const PakaidonkClient = require('./pakaidonk');

// Inisialisasi otomatis menggunakan .env & folder Key/
const client = new PakaidonkClient();

Anda juga bisa mengirimkan konfigurasi & path kunci secara manual saat instansiasi:

const client = new PakaidonkClient({
  partnerId: 'DEV000026',
  clientKey: 'client-key-26',
  secret: 'signature-dev-26',
  urlSandbox: 'https://rising-dev.pakailink.id',
  privateKeyPath: './custom_keys/private.pem',
  publicKeyPath: './custom_keys/public.pem'
});

3. Dokumentasi Fungsi (API Reference)

1. Cek Saldo Merchant (Balance Inquiry)

Mengambil informasi saldo merchant sandbox Anda.

const balance = await client.checkBalance();
console.log('Saldo:', balance.accountInfo[0].activeBalance.value);

2. Cek Profil Merchant (Merchant Profile Inquiry)

Mengambil informasi lengkap profil pemilik credential key (Partner ID, Client Key, Account No, dan Nama Merchant Terdaftar).

const profile = await client.getMerchantProfile();
console.log('Nama Merchant:', profile.merchantName); // Output: BKS
console.log('Status Akun:', profile.status); // Output: ACTIVE

3. Generate QRIS MPM

Membuat QRIS Dinamis untuk pembayaran masuk.

// Parameter: (amount, type, validityPeriod, callbackUrl)
const qris = await client.generateQRIS(10000, 'DINAMIS', '', 'https://domain-anda.com/callback/qris');
console.log('QRIS String:', qris.qrContent);
console.log('ID Transaksi:', qris.referenceNo);

4. Buat Tagihan E-Money (E-Money Payment Request)

Membuat tagihan e-money (seperti OVO, DANA) di mana pelanggan akan melakukan pembayaran melalui URL payment.

// Parameter: (productCode, phone, customerName, amount, email, callbackUrl)
const payment = await client.createEmoneyPayment(
  'PAYDANA', 
  '08123456789', 
  'Budi Santoso', 
  10000, 
  '[email protected]', 
  'https://domain-anda.com/callback/emoney'
);
console.log('Simulasi Bayar URL:', payment.emoneyData.additionalInfo.urlPayment);

5. Cek Profile E-Wallet Pelanggan (Check Customer Profile)

Berguna untuk memverifikasi nama pelanggan/pemilik e-wallet sebelum melakukan transaksi.

// Parameter: (productCode, customerPhone)
const profile = await client.checkCustomerProfile('DANA', '08989177565');
console.log('Nama Akun Pelanggan:', profile.customerName); // Output: Fathan Devani

6. Deposit / Topup E-Wallet Pelanggan

Melakukan transfer saldo merchant Anda ke e-wallet pelanggan (misal DANA, OVO). Memiliki 2 tahap wajib:

Tahap A: Inquiry (Cek Akun & Rekening Tujuan)

// Parameter: (productCode, customerPhone, amount)
const inquiry = await client.inquiryCustomerTopup('DANA', '08989177565', 10000);
console.log('Nama Akun E-Wallet:', inquiry.customerName);
console.log('Session ID Konfirmasi:', inquiry.sessionId);

Tahap B: Execute (Konfirmasi & Kirim Dana)

// Parameter: (productCode, customerPhone, amount, sessionId, callbackUrl)
const topupResult = await client.executeCustomerTopup(
  'DANA', 
  '08989177565', 
  10000, 
  inquiry.sessionId, 
  'https://domain-anda.com/callback/topup'
);
console.log('Transaksi Topup Sukses:', topupResult.responseCode === '2003800');

Tahap C: Cek Status Topup

const status = await client.checkTopupStatus('PARTNER-REF-NO-TOPUP');
console.log('Status Detail:', status);

7. Cek Status Pembayaran (Settlement Inquiry Status)

Digunakan untuk memeriksa apakah suatu transaksi masuk (QRIS/E-Money Payment/VA) sudah terbayar (settled) atau belum ke sistem Pakaidonk.

// Parameter: (trxId / referenceNo)
const settlement = await client.checkSettlementStatus('QRA175869717210285...');
console.log('Status Settlement:', settlement.additionalInfo.settlementStatus); // SUCCESS / PENDING

8. Verifikasi Signature Callback (Webhook)

Gunakan fungsi ini di controller endpoint callback Anda untuk memverifikasi keaslian signature yang dikirimkan oleh server Pakaidonk:

// Express JS Callback Handler
app.post('/callback/qris', (req, res) => {
  const headers = req.headers;
  const body = req.body;
  const relativeUrl = '/callback/qris'; // URL relatif endpoint Anda

  const verification = client.verifyCallbackSignature(headers, body, relativeUrl);
  if (verification.verified) {
    console.log('Signature valid!');
    // Proses sukseskan order di database Anda
    res.status(200).json({ responseCode: '2004700', responseMessage: 'Successful' });
  } else {
    console.error('Signature TIDAK valid:', verification.reason);
    res.status(400).send('Invalid Signature');
  }
});

4. Error Handling

Jika terjadi kegagalan transaksi, API akan melempar error standard axios. Tangkap detail errornya menggunakan block try-catch:

try {
  const result = await client.checkBalance();
} catch (error) {
  console.error('Pesan Error:', error.message);
  if (error.response) {
    // Detail respon kesalahan dari API Gateway Pakaidonk
    console.error('Detail Error SNAP:', error.response.data);
  }
}