@crediblemark/buayar 0.6.2 → 0.8.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 (8) hide show
  1. package/README.md +108 -85
  2. package/dist/cli/index.js +21 -11
  3. package/dist/index.d.mts +206 -11
  4. package/dist/index.d.ts +206 -11
  5. package/dist/index.js +640 -230
  6. package/dist/index.mjs +635 -230
  7. package/docs/guide.md +144 -58
  8. package/package.json +1 -1
package/docs/guide.md CHANGED
@@ -16,8 +16,11 @@ Panduan ini adalah **satu-satunya** panduan yang Anda butuhkan untuk mengintegra
16
16
  6. [Webhook Universal](#-webhook-universal)
17
17
  7. [Refund / Saldo / Payout Unified](#-refund--saldo--payout-unified)
18
18
  8. [Zero-Code PG Switch](#-zero-code-pg-switch)
19
- 9. [Fitur Khusus Provider (`<X>Client`)](#-fitur-khusus-provider-xclient)
20
- 10. [Kamus Variabel `.env` per Provider](#-kamus-variabel-env-per-provider)
19
+ 9. [Provider Dinamis & Autodetect](#-provider-dinamis--autodetect)
20
+ 10. [Cek Capability Provider (Portabilitas)](#-cek-capability-provider-portabilitas)
21
+ 11. [Fitur Khusus Provider (`<X>Client`)](#-fitur-khusus-provider-xclient)
22
+ 12. [Panduan Pengisian Variabel Universal (`BUAYAR_*`) per Provider](#-panduan-pengisian-variabel-universal-buayar_-per-provider)
23
+ 13. [Daftar Canonical Payment Methods](#-daftar-canonical-payment-methods)
21
24
 
22
25
  ---
23
26
 
@@ -44,15 +47,20 @@ Semua metode pembayaran memakai **kode canonical universal** (`bca_va`, `qris`,
44
47
 
45
48
  ### 1. Zero-Config (baca dari `.env`) — **Direkomendasikan**
46
49
 
50
+ Cukup isi **variabel universal** yang sama untuk semua provider. SDK otomatis memetakannya ke kredensial yang dibutuhkan provider aktif.
51
+
47
52
  ```env
48
- # Pilih provider aktif: midtrans, duitku, ipaymu, xendit, doku, prismalink,
53
+ # (opsional) Provider aktif: midtrans, duitku, ipaymu, xendit, doku, prismalink,
49
54
  # faspay, finpay, nicepay, oy, stripe, paypal, adyen, checkoutcom,
50
55
  # razorpay, square, payu, braintree, twocheckout
51
- PROVIDER_PG=midtrans
56
+ # Bila dikosongkan, provider AUTO-DIDETEKSI dari kredensial yang terisi.
57
+ BUAYAR_PROVIDER=midtrans
52
58
 
53
59
  # Kredensial Universal (dipetakan otomatis per provider)
54
60
  BUAYAR_API_KEY=your-server-key-atau-secret
55
61
  BUAYAR_MERCHANT_CODE=merchant-id-atau-username
62
+ BUAYAR_CLIENT_KEY=client-atau-public-key # bila provider butuh
63
+ BUAYAR_MERCHANT_ID=merchant-id # bila berbeda dari code
56
64
  BUAYAR_SANDBOX=true
57
65
 
58
66
  # Callback & Return URL
@@ -65,6 +73,8 @@ import { buayar } from "@crediblemark/buayar";
65
73
  // Konfigurasi ter-baca otomatis dari process.env. Selesai.
66
74
  ```
67
75
 
76
+ > **🪄 Autodetect:** Jika `BUAYAR_PROVIDER` dikosongkan, Buayar menebak provider aktif dari kredensial yang terisi di `.env` (mis. `STRIPE_SECRET_KEY` → Stripe, `DUITKU_API_KEY` → Duitku). Anda bahkan bisa **tidak menyebut nama provider sama sekali**.
77
+
68
78
  ### 2. Inisialisasi Manual (programatik)
69
79
 
70
80
  ```typescript
@@ -81,6 +91,23 @@ const buayar = new Buayar({
81
91
 
82
92
  > 💡 Banyak `get<X>Client()` juga bisa dipakai dengan meneruskan `provider` di `configOverride` agar menargetkan provider tertentu dari satu instance `buayar`.
83
93
 
94
+ ### Variable Environment: Universal vs Spesifik
95
+
96
+ Setiap provider punya kredensial yang **berbeda-beda** (`MIDTRANS_SERVER_KEY` vs `DUITKU_API_KEY` vs `FASPAY_PASSWORD`, dst.). Itu sebabnya Buayar menyediakan **variabel universal** yang sama untuk semua provider, jadi Anda tidak perlu menghafal perbedaan tiap PG:
97
+
98
+ | Variabel Universal | Dipakai sebagai |
99
+ | :--- | :--- |
100
+ | `BUAYAR_PROVIDER` | nama provider aktif (opsional → autodetect) |
101
+ | `BUAYAR_API_KEY` | secret / server key / password provider |
102
+ | `BUAYAR_MERCHANT_CODE` | merchant id / va / username / imid / client id |
103
+ | `BUAYAR_CLIENT_KEY` | client / public / publishable key |
104
+ | `BUAYAR_MERCHANT_ID` | merchant id (bila beda dari code) |
105
+ | `BUAYAR_SANDBOX` | mode sandbox (`true`/`false`) |
106
+ | `BUAYAR_CALLBACK_URL` / `BUAYAR_RETURN_URL` | URL webhook & redirect |
107
+ | `BUAYAR_WEBHOOK_SECRET` / `BUAYAR_WEBHOOK_TOKEN` | secret webhook |
108
+
109
+ > 🔧 Variabel spesifik per provider (`MIDTRANS_SERVER_KEY`, `DUITKU_API_KEY`, dll.) **tetap didukung** sebagai fallback. Prioritas konfigurasi: `config` eksplisit → `BUAYAR_*` → variabel spesifik → default.
110
+
84
111
  ---
85
112
 
86
113
  ## 🛠️ Membuat Transaksi
@@ -265,17 +292,74 @@ Beralih provider **tanpa mengubah satu baris pun** di controller/service Anda
265
292
 
266
293
  ```env
267
294
  # Sebelum: Midtrans
268
- PROVIDER_PG=midtrans
269
- MIDTRANS_SERVER_KEY=SB-Mid-server-xxxx
295
+ BUAYAR_PROVIDER=midtrans
296
+ BUAYAR_API_KEY=SB-Mid-server-xxxx
270
297
 
271
298
  # Sesudah: Stripe — kode aplikasi TIDAK berubah
272
- PROVIDER_PG=stripe
273
- STRIPE_SECRET_KEY=sk_test_51...
274
- STRIPE_WEBHOOK_SECRET=whsec_...
299
+ BUAYAR_PROVIDER=stripe
300
+ BUAYAR_API_KEY=sk_test_51...
301
+ BUAYAR_WEBHOOK_SECRET=whsec_...
302
+ ```
303
+
304
+ Bahkan bisa **tanpa `BUAYAR_PROVIDER`** — cukup ganti kredensial, dan provider terdeteksi otomatis:
305
+
306
+ ```env
307
+ # Auto: cukup isi key-nya, provider tertelan
308
+ BUAYAR_API_KEY=sk_test_51... # berubah ke Stripe
275
309
  ```
276
310
 
277
311
  ---
278
312
 
313
+ ## 🌐 Provider Dinamis & Autodetect
314
+
315
+ Registry provider **dinamis**: Anda bisa menambah/mendaftarkan provider kustom tanpa mengedit core SDK, sekaligus memanfaatkan autodetect.
316
+
317
+ ### 1. Autodetect dari `.env`
318
+ Tanpa menyebut `BUAYAR_PROVIDER`, SDK menebak provider dari kredensial yang terisi:
319
+ ```typescript
320
+ const b = new Buayar();
321
+ b.detectProviderFromEnv(process.env); // "stripe" | "duitku" | ... | undefined
322
+ ```
323
+
324
+ ### 2. Autodetect dari payload webhook
325
+ ```typescript
326
+ b.detectProviderFromPayload({
327
+ signature_key: "x", transaction_status: "settlement",
328
+ }); // "midtrans"
329
+ ```
330
+
331
+ ### 3. Daftar provider terdaftar & registrasi kustom
332
+ ```typescript
333
+ b.listProviders(); // ["midtrans","duitku",...]
334
+ b.registerProvider(new MyCustomProvider()); // untuk eksekusi
335
+ b.registerProviderDescriptor({
336
+ name: "mypg",
337
+ envKeys: ["MYPG_SECRET"], // untuk autodetect
338
+ methods: ["qris", "bca_va"], // untuk capability
339
+ operations: { refund: true, checkBalance: true, disburse: true },
340
+ });
341
+ ```
342
+
343
+ ---
344
+
345
+ ## 🔎 Cek Capability Provider (Portabilitas)
346
+
347
+ Jawab pertanyaan "provider ini dukung fitur & metode apa?" secara **runtime** — berguna untuk memutuskan migrasi atau menampilkan channel yang valid.
348
+
349
+ ```typescript
350
+ b.getCapabilities("duitku");
351
+ // { methods: ["bca_va","qris",...], operations: { refund: false, checkBalance: true, disburse: true } }
352
+
353
+ b.supports("xendit", "checkBalance"); // true
354
+ b.supports("doku", "refund"); // false
355
+ b.supportsMethod("qris", "stripe"); // true
356
+ b.getSupportedMethods("midtrans"); // ["bca_va","bni_va",...]
357
+ ```
358
+
359
+ > 💡 Ini berguna untuk skenario **migrasi anti-lock-in**: cek dulu apakah provider target punya metode/op yang Anda butuhkan sebelum pindah. Provider yang tidak mendukung suatu operasi tetap mengembalikan `{ supported: false }` (bukan error), bukan crash.
360
+
361
+ ---
362
+
279
363
  ## 🏦 Fitur Khusus Provider (`<X>Client`)
280
364
 
281
365
  Refund, saldo, dan payout sudah tersedia secara **unified** di atas. Namun untuk **fitur yang benar-benar eksklusif** tiap PG yang tidak masuk interface umum (subscription, payment link, tokenisasi GoPay, billing invoice, dsb.), pakai getter client per provider:
@@ -287,57 +371,59 @@ const balance = await xendit.checkBalance("CASH");
287
371
 
288
372
  Rangkuman kemampuan ekstra tiap provider:
289
373
 
290
- | Provider | Getter | Kemampuan ekstra |
291
- | :--- | :--- | :--- |
292
- | Midtrans | `getMidtransClient()` | cancel/refund/expire/approve/deny/capture, GoPay tokenization, Subscription, Payment Link, IRIS balance |
293
- | Duitku | `getDuitkuClient()` | balance, listBanks, inquiryBankAccount, disburse, checkDisbursementStatus |
294
- | iPaymu | `getIpaymuClient()` | balance, checkTransaction |
295
- | Xendit | `getXenditClient()` | balance, expireInvoice, createDisbursement |
296
- | DOKU | `getDokuClient()` | checkTransaction |
297
- | PrismaLink | `getPrismalinkClient()` | checkTransaction |
298
- | Faspay | `getFaspayClient()` | cancelTransaction, checkTransaction |
299
- | Finpay | `getFinpayClient()` | checkTransaction |
300
- | Nicepay | `getNicepayClient()` | cancelTransaction, checkTransaction |
301
- | OY! Bisnis | `getOyClient()` | checkTransaction, balance, remit (transfer dana) |
302
- | Stripe | `getStripeClient()` | balance, createRefund, retrieveCheckoutSession, retrievePaymentIntent |
303
- | PayPal | `getPaypalClient()` | captureOrder, getOrder, refundCapture, checkBalance, verifyWebhookSignature |
304
- | Adyen | `getAdyenClient()` | capturePayment, cancelPayment, refundPayment, getPaymentDetails, getAvailablePaymentMethods |
305
- | Checkout.com | `getCheckoutComClient()` | balance, refundPayment, voidPayment, getPaymentDetails, listPaymentLinks |
306
- | Razorpay | `getRazorpayClient()` | capturePayment, createRefund, checkBalance, fetchPayment, listPayments |
307
- | Square | `getSquareClient()` | retrieveBalance, refundPayment, cancelPayment, getPayment, listLocations |
308
- | PayU | `getPayuClient()` | cancelOrder, getOrder, refundOrder |
309
- | Braintree | `getBraintreeClient()` | getClientToken, findTransaction, refundTransaction, voidTransaction |
310
- | 2Checkout | `getTwoCheckoutClient()` | getOrder, listOrders, getSubscription, refundOrder |
374
+ | Provider | Status | Getter | Kemampuan ekstra |
375
+ | :--- | :---: | :--- | :--- |
376
+ | Midtrans | Tested | `getMidtransClient()` | cancel/refund/expire/approve/deny/capture, GoPay tokenization, Subscription, Payment Link, IRIS balance |
377
+ | Duitku | Tested | `getDuitkuClient()` | balance, listBanks, inquiryBankAccount, disburse, checkDisbursementStatus |
378
+ | iPaymu | Tested | `getIpaymuClient()` | balance, checkTransaction, getHistory, getBankList, getPaymentMethods, COD logistics (getArea, getRate, getPickup, getAwb, getTracking) |
379
+ | Xendit | Tested | `getXenditClient()` | balance, expireInvoice, createDisbursement |
380
+ | DOKU | Tested | `getDokuClient()` | checkTransaction |
381
+ | PrismaLink | Tested | `getPrismalinkClient()` | checkTransaction |
382
+ | Faspay | Tested | `getFaspayClient()` | cancelTransaction, checkTransaction |
383
+ | Finpay | Tested | `getFinpayClient()` | checkTransaction |
384
+ | Nicepay | Tested | `getNicepayClient()` | cancelTransaction, checkTransaction |
385
+ | OY! Bisnis | Tested | `getOyClient()` | checkTransaction, balance, remit (transfer dana) |
386
+ | Stripe | Tested | `getStripeClient()` | balance, createRefund, retrieveCheckoutSession, retrievePaymentIntent |
387
+ | PayPal | Tested | `getPaypalClient()` | captureOrder, getOrder, refundCapture, checkBalance, verifyWebhookSignature |
388
+ | Adyen | Tested | `getAdyenClient()` | capturePayment, cancelPayment, refundPayment, getPaymentDetails, getAvailablePaymentMethods |
389
+ | Checkout.com | Tested | `getCheckoutComClient()` | balance, refundPayment, voidPayment, getPaymentDetails, listPaymentLinks |
390
+ | Razorpay | Tested | `getRazorpayClient()` | capturePayment, createRefund, checkBalance, fetchPayment, listPayments |
391
+ | Square | Tested | `getSquareClient()` | retrieveBalance, refundPayment, cancelPayment, getPayment, listLocations |
392
+ | PayU | Tested | `getPayuClient()` | cancelOrder, getOrder, refundOrder |
393
+ | Braintree | Tested | `getBraintreeClient()` | getClientToken, findTransaction, refundTransaction, voidTransaction |
394
+ | 2Checkout | Tested | `getTwoCheckoutClient()` | getOrder, listOrders, getSubscription, refundOrder |
311
395
 
312
396
  ---
313
397
 
314
- ## 📚 Kamus Variabel `.env` per Provider
315
-
316
- Anda hanya perlu mengisi kredensial provider yang **sedang aktif**. Gunakan variabel universal (`BUAYAR_*`) bila ingin kode benar-benar provider-agnostic, atau variabel spesifik di bawah.
317
-
318
- | Provider | Variabel `.env` |
319
- | :--- | :--- |
320
- | Midtrans | `MIDTRANS_SERVER_KEY`, `MIDTRANS_CLIENT_KEY` |
321
- | Duitku | `DUITKU_API_KEY`, `DUITKU_MERCHANT_CODE` |
322
- | iPaymu | `IPAYMU_API_KEY`, `IPAYMU_VA` |
323
- | Xendit | `XENDIT_SECRET_KEY`, `XENDIT_WEBHOOK_TOKEN` |
324
- | DOKU | `DOKU_CLIENT_ID`, `DOKU_SECRET_KEY` |
325
- | PrismaLink | `PRISMALINK_MERCHANT_ID`, `PRISMALINK_SECRET_KEY` |
326
- | Faspay | `FASPAY_MERCHANT_ID`, `FASPAY_USER_ID`, `FASPAY_PASSWORD`, `FASPAY_MERCHANT_NAME` |
327
- | Finpay | `FINPAY_MERCHANT_ID`, `FINPAY_MERCHANT_KEY` |
328
- | Nicepay | `NICEPAY_IMID`, `NICEPAY_KEY` |
329
- | OY! Bisnis | `OY_USERNAME`, `OY_API_KEY` |
330
- | Stripe | `STRIPE_SECRET_KEY`, `STRIPE_PUBLIC_KEY`, `STRIPE_WEBHOOK_SECRET` |
331
- | PayPal | `PAYPAL_CLIENT_ID`, `PAYPAL_CLIENT_SECRET`, `PAYPAL_WEBHOOK_ID` |
332
- | Adyen | `ADYEN_API_KEY`, `ADYEN_MERCHANT_ACCOUNT`, `ADYEN_CLIENT_KEY`, `ADYEN_HMAC_KEY`, `ADYEN_LIVE_URL_PREFIX` |
333
- | Checkout.com | `CHECKOUTCOM_SECRET_KEY`, `CHECKOUTCOM_PUBLIC_KEY`, `CHECKOUTCOM_WEBHOOK_SECRET` |
334
- | Razorpay | `RAZORPAY_KEY_ID`, `RAZORPAY_KEY_SECRET`, `RAZORPAY_WEBHOOK_SECRET` |
335
- | Square | `SQUARE_ACCESS_TOKEN`, `SQUARE_APPLICATION_ID`, `SQUARE_LOCATION_ID`, `SQUARE_WEBHOOK_SIGNATURE_KEY` |
336
- | PayU | `PAYU_POS_ID`, `PAYU_MD5_KEY`, `PAYU_OAUTH_CLIENT_ID`, `PAYU_OAUTH_CLIENT_SECRET` |
337
- | Braintree | `BRAINTREE_MERCHANT_ID`, `BRAINTREE_PUBLIC_KEY`, `BRAINTREE_PRIVATE_KEY` |
338
- | 2Checkout | `TWOCHECKOUT_MERCHANT_CODE`, `TWOCHECKOUT_SECRET_KEY`, `TWOCHECKOUT_SECRET_WORD` |
339
-
340
- Sandbox: otomatis terdeteksi dari `BUAYAR_SANDBOX`/`NODE_ENV`, atau set per-provider (mis. `STRIPE_SANDBOX=true`, `MIDTRANS_SANDBOX=true`).
398
+ ## 📚 Panduan Pengisian Variabel Universal (`BUAYAR_*`) per Provider
399
+
400
+ Anda **tidak perlu** membuat nama variabel khusus per provider (seperti `IPAYMU_API_KEY`, `DUITKU_API_KEY`, dsb.). Cukup gunakan set variabel seragam **`BUAYAR_*`**.
401
+
402
+ Tabel berikut menunjukkan data apa dari dashboard masing-masing payment gateway yang perlu Anda masukkan ke variabel `BUAYAR_*`:
403
+
404
+ | Provider | `BUAYAR_PROVIDER` | `BUAYAR_API_KEY` | `BUAYAR_MERCHANT_CODE` | `BUAYAR_CLIENT_KEY` / Tambahan |
405
+ | :--- | :--- | :--- | :--- | :--- |
406
+ | **Midtrans** | `midtrans` | Server Key | *(opsional)* | Client Key |
407
+ | **Duitku** | `duitku` | API Key | Merchant Code | *(tidak perlu)* |
408
+ | **iPaymu** | `ipaymu` | API Key | Nomor Virtual Account (VA) | *(tidak perlu)* |
409
+ | **Xendit** | `xendit` | Secret Key | *(opsional)* | Webhook Verification Token (`BUAYAR_WEBHOOK_SECRET`) |
410
+ | **DOKU Jokul** | `doku` | Secret Key | Client ID / Merchant ID | Client ID |
411
+ | **PrismaLink** | `prismalink` | Secret Key | Merchant ID | *(tidak perlu)* |
412
+ | **Faspay** | `faspay` | Password | Merchant ID | User ID |
413
+ | **Finpay** | `finpay` | Merchant Key | Merchant ID | *(tidak perlu)* |
414
+ | **Nicepay** | `nicepay` | Server Key (Secret) | I-MID (Merchant ID) | *(tidak perlu)* |
415
+ | **OY! Bisnis** | `oy` | API Key | Username | Username |
416
+ | **Stripe** | `stripe` | Secret Key (`sk_...`) | *(tidak perlu)* | Publishable Key (`pk_...`) / Webhook Secret |
417
+ | **PayPal** | `paypal` | Client Secret | Client ID | Client ID |
418
+ | **Adyen** | `adyen` | API Key | Merchant Account Name | Client Key / HMAC Key (`BUAYAR_WEBHOOK_SECRET`) |
419
+ | **Checkout.com** | `checkoutcom` | Secret Key (`sk_...`) | *(tidak perlu)* | Public Key (`pk_...`) / Webhook Secret |
420
+ | **Razorpay** | `razorpay` | Key Secret | Key ID | Key ID |
421
+ | **Square** | `square` | Access Token | Application ID | Location ID (`BUAYAR_PROJECT_ID`) |
422
+ | **PayU** | `payu` | MD5 Key / Secret | POS ID | POS ID |
423
+ | **Braintree** | `braintree` | Private Key | Merchant ID | Public Key |
424
+ | **2Checkout** | `twocheckout` | Secret Key | Merchant Code | Secret Word (`BUAYAR_WEBHOOK_SECRET`) |
425
+
426
+ > 💡 **Mode Sandbox:** Cukup tambahkan `BUAYAR_SANDBOX=true` (atau `false` saat production), SDK otomatis menyesuaikan URL endpoint API seluruh provider di atas tanpa perlu konfigurasi tambahan.
341
427
 
342
428
  ---
343
429
 
@@ -345,7 +431,7 @@ Sandbox: otomatis terdeteksi dari `BUAYAR_SANDBOX`/`NODE_ENV`, atau set per-prov
345
431
 
346
432
  | Kategori | Canonical Code |
347
433
  | :--- | :--- |
348
- | **Virtual Account** | `bca_va`, `mandiri_va`, `bni_va`, `bri_va`, `permata_va`, `cimb_va`, `danamon_va`, `bsi_va`, `seabank_va` |
434
+ | **Virtual Account** | `bca_va`, `mandiri_va`, `bni_va`, `bri_va`, `permata_va`, `cimb_va`, `danamon_va`, `bsi_va`, `seabank_va`, `bag_va`, `muamalat_va` |
349
435
  | **QRIS** | `qris`, `gopay_qris`, `shopeepay_qris`, `nobu_qris` |
350
436
  | **E-Wallet** | `gopay`, `shopeepay`, `ovo`, `dana`, `linkaja`, `jenius` |
351
437
  | **Retail** | `alfamart`, `indomaret`, `pos` |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crediblemark/buayar",
3
- "version": "0.6.2",
3
+ "version": "0.8.0",
4
4
  "description": "Unified Payment Gateway SDK for Node.js & TypeScript — 19 providers (Midtrans, Xendit, Duitku, Stripe, PayPal, Adyen, Razorpay, Square, Checkout.com, PayU, Braintree, 2Checkout, DOKU, iPaymu, PrismaLink, Faspay, Finpay, Nicepay, OY!) with zero-code switching via .env",
5
5
  "main": "./dist/index.js",
6
6
  "module": "./dist/index.mjs",