@crediblemark/buayar 0.1.9 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +260 -100
  2. package/dist/index.d.mts +859 -40
  3. package/dist/index.d.ts +859 -40
  4. package/dist/index.js +5591 -485
  5. package/dist/index.mjs +5518 -484
  6. package/package.json +5 -1
package/README.md CHANGED
@@ -3,151 +3,311 @@
3
3
  [![npm version](https://img.shields.io/npm/v/@crediblemark/buayar.svg?style=flat-square&color=amber)](https://www.npmjs.com/package/@crediblemark/buayar)
4
4
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
5
5
 
6
- **`@crediblemark/buayar`** adalah Unified Payment Gateway SDK untuk Node.js dan TypeScript yang dirancang untuk mempermudah integrasi berbagai gerbang pembayaran (Payment Gateway) di Indonesia menggunakan satu struktur API yang seragam.
6
+ **`@crediblemark/buayar`** adalah **Unified Payment Gateway SDK** untuk Node.js dan TypeScript yang dirancang untuk mempermudah integrasi berbagai Payment Gateway di Indonesia menggunakan satu arsitektur API yang seragam.
7
7
 
8
- Dengan SDK ini, Anda cukup menulis kode satu kali menggunakan struktur API yang konsisten untuk mengelola pembuatan transaksi, pengecekan status transaksi, query metode pembayaran, serta verifikasi callback webhook dari berbagai penyedia layanan payment gateway.
8
+ > 💡 **Zero-Code PG Switcher:** Berganti provider payment gateway (misal dari Midtrans ke Duitku atau sebaliknya) **tanpa perlu merombak kode controller/service aplikasi**. Cukup ubah kredensial di file `.env`!
9
9
 
10
10
  ---
11
11
 
12
12
  ## 🚀 Fitur Utama
13
13
 
14
- - 🔄 **Unified API**: Satu antarmuka (interface) terpadu untuk semua provider payment gateway.
15
- - ⚡ **Direct Payment Support**: Otomatis mendeteksi `paymentMethod` dan beralih ke Direct Inquiry API Duitku atau Core API Midtrans untuk mengembalikan `vaNumber`, `qrString` (EMVCo), dan `paymentCode` secara instan tanpa redirect eksternal.
16
- - 🏷️ **Pre-Categorization (Accordion Ready)**: Menyediakan pengelompokan pembayaran bawaan (`Virtual Account`, `QRIS`, `E-Wallet`, `Retail / Gerai`, `Kartu Kredit`, `Paylater / Cicilan`, `Lainnya`) langsung dari API response untuk memudahkan implementasi UI accordion.
17
- - 🎨 **Headless SDK Philosophy**: Dirancang murni sebagai core logic & data manager tanpa overhead UI/styling. Memberikan kebebasan penuh bagi pengembang untuk mendesain UI/Tailwind/dark mode di tingkat aplikasi.
18
- - 🛡️ **Tipe Data Kuat (TypeScript)**: Dilengkapi dengan deklarasi tipe data lengkap untuk mencegah *runtime error*.
19
- - ⚙️ **Modular & Dapat Diperluas**: Memungkinkan penambahan provider baru dengan mewarisi kelas base yang disediakan.
20
- - 🔒 **Otomatisasi Signature**: Keamanan transaksi terjamin dengan pembuatan *hash* signature (MD5, SHA-256, SHA-512) otomatis secara internal.
14
+ - 🔄 **Zero-Code PG Switcher**: Ubah provider dan kredensial langsung via environment variable (`.env`).
15
+ - ⚡ **Dukungan Spektrum Integrasi Penuh**:
16
+ - 🟡 **Semi Integrasi (Redirect/Hosted)**: Menghasilkan `paymentUrl` atau `snap_token` siap redirect/popup.
17
+ - 🟢 **Full Integrasi (Custom Native UI / Direct API)**: Mengembalikan data mentah (`vaNumber`, `qrString` EMVCo, `paymentCode`, `deeplink`) untuk dirender langsung di UI custom aplikasi/web Anda.
18
+ - 🏷️ **Canonical Payment Method Mapping**: Gunakan kode universal (`bca_va`, `mandiri_va`, `qris`, `gopay`, `shopeepay`, `alfamart`, `indomaret`), SDK otomatis memetakannya ke format internal provider aktif.
19
+ - 📂 **Pre-Categorization (Accordion Ready)**: Pengelompokan channel pembayaran bawaan (`Virtual Account`, `QRIS`, `E-Wallet`, `Retail / Gerai`, `Kartu Kredit`, `Paylater / Cicilan`) lengkap dengan fee dan icon URL untuk mempermudah pembuatan UI accordion.
20
+ - 🪝 **Universal Webhook Verifier**: Endpoint webhook tunggal untuk memverifikasi signature (SHA-512 Midtrans / MD5 Duitku) dan menormalisasi status (`isPaid`, `isPending`, `isFailed`, `isExpired`).
21
+ - 🛡️ **Tipe Data Kuat (TypeScript)**: Tipe data deklaratif dan ketat untuk mencegah *runtime error*.
21
22
 
22
23
  ---
23
24
 
24
25
  ## 📦 Provider yang Didukung
25
26
 
26
- SDK ini mendukung beberapa provider payment gateway terkemuka di Indonesia. Silakan merujuk ke dokumentasi detail untuk masing-masing provider:
27
-
28
- * 🏛️ **[Integrasi Duitku (docs/duitku.md)](file:///media/rasyiqi/PROJECT/credibuild-project/buayar/docs/duitku.md)**
29
- * Mendukung Redirect Checkout & Direct Inquiry (VA, QRIS, Retail Code langsung).
30
- * Verifikasi callback otomatis (signature MD5).
31
- * Penelusuran status transaksi & query metode pembayaran dinamis.
32
-
33
- * 🏛️ **[Integrasi Midtrans (docs/midtrans.md)](file:///media/rasyiqi/PROJECT/credibuild-project/buayar/docs/midtrans.md)**
34
- * Mendukung Snap API (Redirect Checkout) & Core API (Direct Charge VA, QRIS, E-Wallet, Retail, Kartu Kredit, Paylater).
35
- * Verifikasi callback otomatis (signature SHA-512).
36
- * Dilengkapi ekstensi `MidtransClient` untuk fitur transaksi pasca-bayar (refund, cancel, subscription recurring, balance check, payment link, gopay tokenization, invoicing).
27
+ * 🏛️ **[Integrasi Midtrans (docs/midtrans.md)](file:///media/rasyiqi/7653717A1C07B131/Buayar/docs/midtrans.md)**
28
+ * Snap API (Redirect Checkout / Popup JS Modal).
29
+ * Core API Direct Charge (BCA, BNI, BRI, Mandiri Bill, Permata, CIMB, QRIS Gopay/ShopeePay, E-Wallet deeplinks, Kartu Kredit 3DS, Alfamart/Indomaret, Paylater).
30
+ * Verifikasi callback otomatis (SHA-512).
31
+ * Ekstensi `MidtransClient` (Refund, Cancel, Subscription, Recurring, Payment Link).
32
+
33
+ * 🏛️ **[Integrasi Duitku (docs/duitku.md)](file:///media/rasyiqi/7653717A1C07B131/Buayar/docs/duitku.md)**
34
+ * Redirect Checkout (Duitku Hosted Page).
35
+ * Direct Inquiry API (VA BCA, Mandiri, BNI, BRI, Permata, QRIS ShopeePay/Nobu, Gerai Retail).
36
+ * Dynamic Payment Methods API (Query channel aktif + dynamic fee).
37
+ * Verifikasi callback otomatis (MD5).
38
+ * Ekstensi `DuitkuClient` (Disbursement / Payout, Inquiry Rekening Bank, Saldo Merchant).
39
+
40
+ * 🏛️ **[Integrasi iPaymu (docs/ipaymu.md)](file:///media/rasyiqi/7653717A1C07B131/Buayar/docs/ipaymu.md)**
41
+ * Redirect Checkout (iPaymu Hosted Page).
42
+ * Direct Payment API (VA BCA, Mandiri, BNI, BRI, CIMB, Permata, Danamon, BSI, QRIS, Alfamart, Indomaret, CC, Akulaku).
43
+ * Verifikasi callback otomatis & signature HMAC-SHA256.
44
+ * Ekstensi `IpaymuClient` (Cek Saldo, Cek Status Transaksi).
45
+
46
+ * 🏛️ **[Integrasi Xendit (docs/xendit.md)](file:///media/rasyiqi/7653717A1C07B131/Buayar/docs/xendit.md)**
47
+ * Invoice v2 API (Redirect Checkout).
48
+ * Payment Requests API v3 Direct Charge (VA BCA, Mandiri, BNI, BRI, Permata, CIMB, Danamon, BSI, QRIS, OVO, DANA, ShopeePay, LinkAja, Alfamart, Indomaret).
49
+ * Verifikasi webhook callback token.
50
+ * Ekstensi `XenditClient` (Cek Saldo, Expire Invoice, Disbursement / Payout).
51
+
52
+ * 🏛️ **[Integrasi DOKU Jokul (docs/doku.md)](file:///media/rasyiqi/7653717A1C07B131/Buayar/docs/doku.md)**
53
+ * Jokul Checkout v1 (Redirect Payment Page).
54
+ * Direct Payment API v2 (VA BCA, Mandiri, BNI, BRI, Permata, CIMB, Danamon, BSI, QRIS, Alfamart, Indomaret, OVO, DANA, ShopeePay).
55
+ * Verifikasi signature HMAC-SHA256 & Digest otomatis.
56
+ * Ekstensi `DokuClient` (Cek Status Pesanan).
57
+
58
+ * 🏛️ **[Integrasi PrismaLink (docs/prismalink.md)](file:///media/rasyiqi/7653717A1C07B131/Buayar/docs/prismalink.md)**
59
+ * Checkout Payment Page (Redirect).
60
+ * Direct Payment API (VA BCA, Mandiri, BNI, BRI, Permata, CIMB, Danamon, BSI, QRIS, Alfamart, Indomaret, E-Wallet, CC).
61
+ * Verifikasi signature SHA-256 otomatis.
62
+ * Ekstensi `PrismalinkClient` (Cek Status Transaksi).
63
+
64
+ * 🏛️ **[Integrasi Faspay (docs/faspay.md)](file:///media/rasyiqi/7653717A1C07B131/Buayar/docs/faspay.md)**
65
+ * Post Data Transaction (Payment Page & Direct VA/QRIS/Retail).
66
+ * Channel lengkap (VA BCA, Mandiri, BNI, BRI, Permata, CIMB, Danamon, BSI, QRIS, Alfamart, Indomaret, OVO, DANA, ShopeePay, LinkAja, Kredivo, Akulaku, CC).
67
+ * Verifikasi signature SHA1(MD5()) otomatis.
68
+ * Ekstensi `FaspayClient` (Inquiry Status & Cancel Transaction).
69
+
70
+ * 🏛️ **[Integrasi Finpay (docs/finpay.md)](file:///media/rasyiqi/7653717A1C07B131/Buayar/docs/finpay.md)**
71
+ * Payment Initiate & Checkout Link (Redirect).
72
+ * Direct Payment API (VA BCA, Mandiri, BNI, BRI, Permata, CIMB, Danamon, BSI, QRIS, Pos Indonesia, Alfamart, Indomaret, E-Wallet, CC).
73
+ * Verifikasi signature HMAC-SHA512 otomatis.
74
+ * Ekstensi `FinpayClient` (Inquiry Status Pembayaran).
75
+
76
+ * 🏛️ **[Integrasi Nicepay (docs/nicepay.md)](file:///media/rasyiqi/7653717A1C07B131/Buayar/docs/nicepay.md)**
77
+ * Order Regist & Hosted Checkout (Redirect).
78
+ * Direct One-Step API (VA BCA BBBB, Mandiri BMRI, BNI BNIN, BRI BRIN, Permata BBBA, CIMB BNIA, Danamon BDIN, BSI BBSI, QRIS, Alfamart, Indomaret, E-Wallet, Paylater, CC).
79
+ * Verifikasi merchantToken SHA-256 otomatis.
80
+ * Ekstensi `NicepayClient` (Inquiry Status & Cancel Transaction).
81
+
82
+ * 🏛️ **[Integrasi OY! Bisnis (docs/oy.md)](file:///media/rasyiqi/7653717A1C07B131/Buayar/docs/oy.md)**
83
+ * Payment Checkout v2 (Payment Link / Redirect).
84
+ * Direct API (Static/Dynamic VA BCA 014, Mandiri 008, BNI 009, BRI 002, Permata 013, CIMB 022, Danamon 011, BSI 451, QRIS, E-Wallet).
85
+ * Verifikasi Header & Webhook otomatis.
86
+ * Ekstensi `OyClient` (Inquiry Status, Saldo Merchant & Kirim Uang/Disbursement).
37
87
 
38
88
  ---
39
89
 
40
- ## ⚙️ Instalasi
41
-
42
- Instal package menggunakan manajer paket pilihan Anda:
90
+ ## ⚙️ Konfigurasi Environment Variables (`.env`)
43
91
 
44
- ```bash
45
- # Menggunakan Bun (Sangat Direkomendasikan)
46
- bun add @crediblemark/buayar
92
+ SDK `Buayar` membaca konfigurasi secara otomatis dari `process.env`. Anda dapat menggunakan variabel universal ataupun variabel spesifik provider:
47
93
 
48
- # Menggunakan NPM
49
- npm install @crediblemark/buayar
94
+ ### 1. Standar Universal (Direkomendasikan)
95
+ ```env
96
+ # Provider aktif: 'midtrans' | 'duitku' | 'ipaymu' | 'xendit' | 'doku' | 'prismalink' | 'faspay' | 'finpay' | 'nicepay' | 'oy'
97
+ PROVIDER_PG=oy
50
98
 
51
- # Menggunakan Yarn
52
- yarn add @crediblemark/buayar
99
+ # Kredensial Universal
100
+ BUAYAR_MERCHANT_CODE=myusername # Username OY! Bisnis
101
+ BUAYAR_API_KEY=oy-secret-key-xxxxxxxxxxxxxxxx # API Key OY! Bisnis
102
+ BUAYAR_SANDBOX=true
53
103
 
54
- # Menggunakan PNPM
55
- pnpm add @crediblemark/buayar
104
+ # Callback & Return URL (Opsional)
105
+ BUAYAR_CALLBACK_URL=https://myapp.com/api/payment/webhook
106
+ BUAYAR_RETURN_URL=https://myapp.com/payment/finish
56
107
  ```
57
108
 
58
- ### Instalasi dari GitHub Packages (Alternatif)
109
+ ### 2. Kamus Variabel Lengkap & Spesifik Provider
110
+
111
+ | Variabel `.env` | Provider | Keterangan |
112
+ | :--- | :--- | :--- |
113
+ | `PROVIDER_PG` / `PG_PROVIDER` / `BUAYAR_PROVIDER` / `PAYMENT_PROVIDER` | Semua | Nama provider yang aktif (`midtrans`, `duitku`, `ipaymu`, `xendit`, `doku`, `prismalink`, `faspay`, `finpay`, `nicepay`, `oy`). |
114
+ | `BUAYAR_API_KEY` / `PG_API_KEY` | Semua | Kunci API universal (Server Key Midtrans / API Key Duitku / API Key iPaymu / Secret Key Xendit / Secret Key DOKU / Secret Key PrismaLink / Password Faspay / Merchant Key Finpay / Key Nicepay / API Key OY!). |
115
+ | `BUAYAR_MERCHANT_CODE` / `PG_MERCHANT_CODE` | Semua | Kode Merchant Duitku / Nomor VA iPaymu / Client ID DOKU / Merchant ID PrismaLink / Merchant ID Faspay / Merchant ID Finpay / iMid Nicepay / Username OY!. |
116
+ | `BUAYAR_SANDBOX` / `PG_SANDBOX` | Semua | Mode sandbox / development (`true` atau `false`). |
117
+ | `MIDTRANS_SERVER_KEY` | Midtrans | Midtrans Server Key spesifik. |
118
+ | `MIDTRANS_CLIENT_KEY` | Midtrans | Midtrans Client Key spesifik. |
119
+ | `DUITKU_API_KEY` | Duitku | API Key Duitku spesifik. |
120
+ | `DUITKU_MERCHANT_CODE` | Duitku | Merchant Code Duitku spesifik. |
121
+ | `IPAYMU_API_KEY` | iPaymu | API Key iPaymu spesifik. |
122
+ | `IPAYMU_VA` | iPaymu | Nomor Virtual Account merchant iPaymu. |
123
+ | `XENDIT_SECRET_KEY` | Xendit | Secret Key Xendit (`xnd_development_...` / `xnd_production_...`). |
124
+ | `XENDIT_WEBHOOK_TOKEN` | Xendit | Verification Token Webhook Xendit. |
125
+ | `DOKU_CLIENT_ID` | DOKU | Client ID merchant DOKU Jokul. |
126
+ | `DOKU_SECRET_KEY` | DOKU | Secret Key merchant DOKU Jokul. |
127
+ | `PRISMALINK_MERCHANT_ID` | PrismaLink | Merchant ID merchant PrismaLink. |
128
+ | `PRISMALINK_SECRET_KEY` | PrismaLink | Secret Key merchant PrismaLink. |
129
+ | `FASPAY_MERCHANT_ID` | Faspay | Merchant ID merchant Faspay (misal: `31112`). |
130
+ | `FASPAY_USER_ID` | Faspay | User ID API Faspay (misal: `db31112`). |
131
+ | `FASPAY_PASSWORD` | Faspay | Password API Faspay. |
132
+ | `FASPAY_MERCHANT_NAME` | Faspay | Nama display merchant di Faspay. |
133
+ | `FINPAY_MERCHANT_ID` | Finpay | Merchant ID merchant Finpay. |
134
+ | `FINPAY_MERCHANT_KEY` | Finpay | Merchant Key / Secret Key Finpay. |
135
+ | `NICEPAY_IMID` | Nicepay | Merchant ID (iMid) Nicepay (misal: `IONPAYTEST`). |
136
+ | `NICEPAY_KEY` | Nicepay | Merchant Key rahasia Nicepay. |
137
+ | `OY_USERNAME` | OY! Bisnis | Username akun OY! Bisnis. |
138
+ | `OY_API_KEY` | OY! Bisnis | API Key OY! Bisnis. |
139
+ | `BUAYAR_API_KEY` / `PG_API_KEY` / `PAYMENT_API_KEY` | Semua | API Key / Server Key universal. |
140
+ | `BUAYAR_MERCHANT_CODE` / `PG_MERCHANT_CODE` | Duitku / Umum | Kode merchant dari dashboard payment gateway. |
141
+ | `BUAYAR_SANDBOX` / `PG_SANDBOX` / `PAYMENT_SANDBOX` | Semua | Mode sandbox (`true` / `false`). |
142
+ | `MIDTRANS_SERVER_KEY` | Midtrans | Server key rahasia Midtrans. |
143
+ | `MIDTRANS_CLIENT_KEY` | Midtrans | Client key publik Midtrans. |
144
+ | `MIDTRANS_MERCHANT_ID` | Midtrans | Merchant ID Midtrans (opsional). |
145
+ | `MIDTRANS_IS_PRODUCTION` | Midtrans | `true` untuk production, `false` untuk sandbox. |
146
+ | `DUITKU_API_KEY` | Duitku | API Key merchant Duitku. |
147
+ | `DUITKU_MERCHANT_CODE` | Duitku | Kode Merchant Duitku (misal: `D1234`). |
148
+ | `DUITKU_SANDBOX` | Duitku | `true` untuk sandbox Duitku. |
149
+ | `BUAYAR_PROJECT_ID` / `PG_PROJECT_ID` | Custom / Extra | Project ID untuk provider masa depan yang membutuhkan project scoping. |
150
+ | `BUAYAR_PUBLIC_KEY` / `BUAYAR_PRIVATE_KEY` | Custom / Extra | Public / Private asymmetric key jika dibutuhkan. |
59
151
 
60
- Package ini juga tersedia di [GitHub Packages](https://github.com/crediblemark-official/Buayar/packages). Buat file `.npmrc` di root project Anda:
152
+ ---
61
153
 
62
- ```ini
63
- @crediblemark:registry=https://npm.pkg.github.com/
64
- //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
65
- ```
154
+ ## 📖 Panduan Penggunaan
66
155
 
67
- Kemudian install seperti biasa:
156
+ ### 1. Inisialisasi Klien (Zero-Config)
157
+ ```typescript
158
+ import { buayar } from "@crediblemark/buayar";
68
159
 
69
- ```bash
70
- bun add @crediblemark/buayar
160
+ // Otomatis membaca konfigurasi dari process.env
71
161
  ```
72
162
 
73
- > **Catatan:** Anda memerlukan GitHub Personal Access Token (PAT) dengan scope `read:packages` yang di-set sebagai environment variable `GITHUB_TOKEN`.
74
-
75
163
  ---
76
164
 
77
- ## 🗺️ Alur Proses Pembayaran
78
-
79
- ```mermaid
80
- sequenceDiagram
81
- autonumber
82
- actor Customer as 👤 Pelanggan
83
- participant App as 💻 Aplikasi Anda (Backend)
84
- participant SDK as 💳 @crediblemark/buayar
85
- participant PG as 🏛️ Payment Gateway (Duitku / Midtrans)
86
-
87
- Customer->>App: 1. Checkout Order
88
- App->>SDK: 2. createInvoice(provider, params, config)
89
- SDK->>SDK: 3. signature Generation & Calculation
90
- SDK->>PG: 4. Inquiry / Charge Request (API)
91
- PG-->>SDK: 5. Kembalikan Payment URL / VA / QRIS / Ref
92
- SDK-->>App: 6. Response (InvoiceResponse)
93
- App-->>Customer: 7. Tampilkan Detail VA/QRIS atau Redirect ke Payment URL
94
- Customer->>PG: 8. Selesaikan Pembayaran
95
- PG->>App: 9. Webhook Callback (Notifikasi Pembayaran)
96
- App->>SDK: 10. verifyCallback(provider, body, config)
97
- SDK-->>App: 11. Kembalikan Status Terverifikasi (paid/failed)
98
- App-->>PG: 12. Response OK ke Payment Gateway
165
+ ### 2. Mode Semi Integrasi (Redirect / Hosted Checkout)
166
+ Jika Anda ingin menyerahkan antarmuka pembayaran kepada halaman checkout bawaan Payment Gateway, cukup kosongkan parameter `paymentMethod`:
167
+
168
+ ```typescript
169
+ import { buayar } from "@crediblemark/buayar";
170
+
171
+ const invoice = await buayar.createInvoice({
172
+ orderId: "ORDER-1001",
173
+ amount: 150000,
174
+ productDetails: "Langganan Paket Pro 1 Bulan",
175
+ customer: {
176
+ name: "Budi Santoso",
177
+ email: "budi@example.com",
178
+ phone: "081234567890",
179
+ },
180
+ returnUrl: "https://myapp.com/orders/ORDER-1001",
181
+ });
182
+
183
+ if (invoice.success) {
184
+ // Arahkan pelanggan ke URL ini:
185
+ console.log("Redirect URL:", invoice.paymentUrl);
186
+ }
99
187
  ```
100
188
 
101
189
  ---
102
190
 
103
- ## 📐 Spesifikasi Interface (TypeScript)
191
+ ### 3. Mode Full Integrasi (Custom Native UI / Direct API)
192
+ Jika Anda ingin membangun halaman checkout sendiri di dalam aplikasi tanpa redirect ke halaman luar:
104
193
 
105
- ### `CreateInvoiceParams`
194
+ #### Langkah A: Ambil Daftar Metode Pembayaran (Accordion-Ready)
106
195
  ```typescript
107
- interface CreateInvoiceParams {
108
- orderId: string;
109
- amount: number;
110
- productDetails: string;
111
- customer: {
112
- name: string;
113
- email: string;
114
- phone?: string;
115
- };
116
- returnUrl: string;
117
- callbackUrl: string;
118
- paymentMethod?: string; // Opsional: Kode pembayaran untuk direct charge (contoh: "BCA", "bca_va", "qris")
119
- providerParams?: any; // Opsional: Parameter tambahan spesifik provider
196
+ const result = await buayar.getPaymentMethods({ amount: 150000 });
197
+
198
+ // Akses daftar terkelompok untuk render komponen Accordion UI:
199
+ console.log(result.categories);
200
+ /*
201
+ {
202
+ "Virtual Account": [
203
+ { code: "bca_va", paymentName: "BCA Virtual Account", paymentImage: "...", totalFee: "IDR 4,000" },
204
+ { code: "mandiri_va", paymentName: "Mandiri Bill Payment", ... }
205
+ ],
206
+ "QRIS": [
207
+ { code: "qris", paymentName: "QRIS Universal", paymentImage: "...", totalFee: "0.7%" }
208
+ ],
209
+ "E-Wallet": [
210
+ { code: "gopay", paymentName: "GoPay", ... },
211
+ { code: "shopeepay", paymentName: "ShopeePay", ... }
212
+ ]
120
213
  }
214
+ */
121
215
  ```
122
216
 
123
- ### `InvoiceResponse`
217
+ #### Langkah B: Direct Charge saat Pelanggan Memilih Metode
124
218
  ```typescript
125
- interface InvoiceResponse {
126
- success: boolean;
127
- paymentUrl?: string; // URL checkout halaman pembayaran (jika menggunakan redirect)
128
- reference?: string; // ID Referensi transaksi / token Snap dari gateway
129
- vaNumber?: string; // Nomor Virtual Account jika menggunakan VA instan
130
- qrString?: string; // Data string QRIS mentah (EMVCo) untuk scan QR langsung
131
- qrCodeUrl?: string; // URL gambar QR Code
132
- paymentCode?: string; // Kode pembayaran retail (Indomaret/Alfamart)
133
- rawResponse: any; // Payload respons mentah dari API gateway
134
- error?: string; // Pesan kegagalan jika success = false
135
- }
219
+ // Contoh 1: Direct Virtual Account (BCA)
220
+ const vaInvoice = await buayar.createInvoice({
221
+ orderId: "ORDER-1002",
222
+ amount: 150000,
223
+ paymentMethod: "bca_va", // Canonical ID
224
+ productDetails: "Topup Saldo",
225
+ customer: { name: "Budi", email: "budi@example.com" },
226
+ });
227
+
228
+ console.log("Nomor VA:", vaInvoice.vaNumber); // Contoh: "123456789012"
229
+ console.log("Bank:", vaInvoice.vaBank); // "bca"
230
+ console.log("Batas Bayar:", vaInvoice.expiresAt);
231
+
232
+ // Contoh 2: Direct QRIS (Render ke Canvas / SVG QR)
233
+ const qrisInvoice = await buayar.createInvoice({
234
+ orderId: "ORDER-1003",
235
+ amount: 50000,
236
+ paymentMethod: "qris", // Canonical ID
237
+ productDetails: "Kopi Kenangan",
238
+ customer: { name: "Budi", email: "budi@example.com" },
239
+ });
240
+
241
+ console.log("Raw QRIS String (EMVCo):", qrisInvoice.qrString);
242
+ console.log("URL Gambar QR:", qrisInvoice.qrCodeUrl);
243
+
244
+ // Contoh 3: Gerai Retail (Indomaret / Alfamart)
245
+ const retailInvoice = await buayar.createInvoice({
246
+ orderId: "ORDER-1004",
247
+ amount: 100000,
248
+ paymentMethod: "indomaret",
249
+ productDetails: "Voucher Game",
250
+ customer: { name: "Budi", email: "budi@example.com" },
251
+ });
252
+
253
+ console.log("Kode Bayar Kasir:", retailInvoice.paymentCode);
136
254
  ```
137
255
 
138
- ### `PaymentMethod`
256
+ ---
257
+
258
+ ### 4. Universal Webhook Handler
259
+ Tangani callback notifikasi dari PG manapun hanya dengan 1 endpoint universal:
260
+
139
261
  ```typescript
140
- interface PaymentMethod {
141
- paymentMethod: string;
142
- paymentName: string;
143
- paymentImage: string;
144
- totalFee: string;
145
- category: "Virtual Account" | "QRIS" | "E-Wallet" | "Retail / Gerai" | "Kartu Kredit" | "Paylater / Cicilan" | "Lainnya";
146
- }
262
+ // Contoh implementasi di Express / Elysia / Next.js API Route
263
+ app.post("/api/payment/webhook", async (req, res) => {
264
+ const result = await buayar.verifyWebhook(req.body, req.headers);
265
+
266
+ if (!result.isValid) {
267
+ return res.status(400).json({ error: "Invalid signature" });
268
+ }
269
+
270
+ if (result.isPaid) {
271
+ console.log(`✅ Order ${result.orderId} senilai Rp${result.amount} telah LUNAS!`);
272
+ // Jalankan logika aktivasi langganan / kirim produk
273
+ } else if (result.isExpired) {
274
+ console.log(`⏰ Order ${result.orderId} telah kedaluwarsa.`);
275
+ }
276
+
277
+ // Balas respons OK ke gateway
278
+ return res.status(200).json({ status: "OK" });
279
+ });
147
280
  ```
148
281
 
149
282
  ---
150
283
 
284
+ ## 🏷️ Daftar Canonical Payment Methods
285
+
286
+ | Kategori | Canonical Code | Duitku Mapped Code | Midtrans Core Mapped Type |
287
+ | :--- | :--- | :--- | :--- |
288
+ | **Virtual Account** | `bca_va` | `BC` | `bank_transfer (bca)` |
289
+ | | `mandiri_va` | `M2` | `echannel` |
290
+ | | `bni_va` | `I1` | `bank_transfer (bni)` |
291
+ | | `bri_va` | `BR` | `bank_transfer (bri)` |
292
+ | | `permata_va` | `BT` | `bank_transfer (permata)` |
293
+ | | `cimb_va` | `B1` | `bank_transfer (cimb)` |
294
+ | | `danamon_va` | `DM` | `bank_transfer (danamon)` |
295
+ | | `bsi_va` | `BS` | `bank_transfer (bsi)` |
296
+ | | `seabank_va` | `S1` | `bank_transfer (seabank)` |
297
+ | **QRIS** | `qris` | `SP` / `NQ` | `qris` |
298
+ | **E-Wallet** | `gopay` | `GP` | `gopay` |
299
+ | | `shopeepay` | `SA` | `shopeepay` |
300
+ | | `ovo` | `OV` | `ovo` |
301
+ | | `dana` | `DA` | `dana` |
302
+ | | `linkaja` | `LA` | `linkaja` |
303
+ | **Retail** | `alfamart` | `AL` | `cstore (alfamart)` |
304
+ | | `indomaret` | `IR` | `cstore (indomaret)` |
305
+ | **Kartu** | `credit_card` | `VC` | `credit_card` |
306
+ | **Paylater** | `kredivo` | `KV` | `kredivo` |
307
+ | | `akulaku` | `AT` | `akulaku` |
308
+
309
+ ---
310
+
151
311
  ## 📄 Lisensi
152
312
 
153
313
  Proyek ini dilisensikan di bawah **MIT License**. Hak Cipta © 2026 Rasyiqi Crediblemark.