@crediblemark/buayar 0.1.5 → 0.1.7

package/README.md

@@ -10,13 +10,16 @@ Dengan SDK ini, Anda cukup menulis kode satu kali menggunakan struktur API yang
 ---
 
 ## 🚀 Fitur Utama
-
+ 
 - 🔄 **Unified API**: Satu antarmuka (interface) terpadu untuk semua provider payment gateway.
+- ⚡ **Direct Payment Support**: Otomatis mendeteksi `paymentMethod` dan beralih ke Direct Inquiry API (v2/inquiry) Duitku untuk mengembalikan `vaNumber`, `qrString` (EMVCo), dan `paymentCode` secara instan tanpa redirect eksternal.
+- 🏷️ **Pre-Categorization (Accordion Ready)**: Menyediakan pengelompokan pembayaran bawaan (`Virtual Account`, `QRIS`, `E-Wallet`, `Retail / Gerai`, `Lainnya`) langsung dari API response untuk memudahkan implementasi UI accordion.
+- 🎨 **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.
 - 🛡️ **Tipe Data Kuat (TypeScript)**: Dilengkapi dengan deklarasi tipe data lengkap untuk mencegah *runtime error*.
 - 🇮🇩 **Dukungan Lokal**: Siap digunakan untuk transaksi di Indonesia (seperti Duitku).
 - ⚙️ **Modular & Dapat Diperluas**: Memungkinkan penambahan provider baru dengan mewarisi kelas base yang disediakan.
 - 🔒 **Otomatisasi Signature**: Keamanan transaksi terjamin dengan pembuatan *hash* signature (MD5, SHA-256) otomatis secara internal.
-
+ 
 ---
 
 ## 📦 Instalasi
@@ -218,11 +221,26 @@ interface InvoiceResponse {
   success: boolean;
   paymentUrl?: string;
   reference?: string;
+  vaNumber?: string;       // Nomor Virtual Account (untuk metode Bank VA)
+  qrString?: string;       // EMVCo QRIS payload mentah (untuk scan langsung)
+  qrCodeUrl?: string;      // Image URL QRIS dari Duitku
+  paymentCode?: string;    // Kode pembayaran retail (Indomaret/Alfamart)
   rawResponse: any;
   error?: string;
 }
 ```
 
+### `PaymentMethod`
+```typescript
+interface PaymentMethod {
+  paymentMethod: string;
+  paymentName: string;
+  paymentImage: string;
+  totalFee: string;
+  category: "Virtual Account" | "QRIS" | "E-Wallet" | "Retail / Gerai" | "Lainnya";
+}
+```
+
 ### `VerifyCallbackResult`
 ```typescript
 interface VerifyCallbackResult {
@@ -236,6 +254,19 @@ interface VerifyCallbackResult {
 
 ---
 
+## 🛠️ Utilitas Tambahan
+
+### `getPaymentMethodCategory(code, name)`
+Mengkategorikan kode dan nama metode pembayaran Duitku ke kategori terstandarisasi untuk UI Accordion.
+```typescript
+import { getPaymentMethodCategory } from "@crediblemark/buayar";
+
+const cat = getPaymentMethodCategory("BT", "Permata VA"); 
+// Output: "Virtual Account"
+```
+
+---
+
 ## 📄 Lisensi
 
 Proyek ini dilisensikan di bawah **MIT License**. Hak Cipta © 2026 Rasyiqi Crediblemark.

package/dist/index.d.mts

@@ -9,11 +9,23 @@ interface CreateInvoiceParams {
     };
     returnUrl: string;
     callbackUrl: string;
+    /** Specific Duitku payment method code (e.g. "BCA", "I1", "OV"). If omitted, all methods are available via Duitku's redirect page. */
+    paymentMethod?: string;
+    /** Provider-specific parameters (e.g., token_id, billing details, custom headers/fields) */
+    providerParams?: any;
 }
 interface InvoiceResponse {
     success: boolean;
     paymentUrl?: string;
     reference?: string;
+    /** Virtual Account number (for bank VA methods) */
+    vaNumber?: string;
+    /** QRIS string for display in a QR code */
+    qrString?: string;
+    /** Duitku-hosted QR code image URL */
+    qrCodeUrl?: string;
+    /** Generic payment code (for retail/minimarket methods like Indomaret) */
+    paymentCode?: string;
     rawResponse: any;
     error?: string;
 }
@@ -29,27 +41,149 @@ interface ProviderConfig {
     apiKey: string;
     sandbox: boolean;
 }
+interface GetPaymentMethodsParams {
+    /** Transaction amount (integer, no decimal) */
+    amount: number;
+}
+interface PaymentMethod {
+    /** Provider-specific method code, e.g. "BT", "I1", "OL" */
+    paymentMethod: string;
+    /** Human-readable name, e.g. "BCA Virtual Account" */
+    paymentName: string;
+    /** URL to payment method logo/image */
+    paymentImage: string;
+    /** Total transaction fee in IDR (string from API) */
+    totalFee: string;
+    /** Categorized payment channel (Virtual Account, QRIS, E-Wallet, Retail / Gerai, Kartu Kredit, Paylater / Cicilan, Lainnya) */
+    category: "Virtual Account" | "QRIS" | "E-Wallet" | "Retail / Gerai" | "Kartu Kredit" | "Paylater / Cicilan" | "Lainnya";
+}
+interface GetPaymentMethodsResult {
+    success: boolean;
+    methods: PaymentMethod[];
+    error?: string;
+    rawResponse: any;
+}
+interface CheckTransactionParams {
+    /** The merchant order ID used when creating the invoice */
+    merchantOrderId: string;
+}
+interface CheckTransactionResult {
+    success: boolean;
+    orderId: string;
+    reference: string;
+    amount: number;
+    /** "00" = success/paid, "01" = pending, "02" = failed/expired */
+    statusCode: string;
+    status: "paid" | "pending" | "failed";
+    statusMessage: string;
+    error?: string;
+    rawResponse: any;
+}
 
 declare abstract class BasePaymentProvider {
     abstract readonly name: string;
     abstract createInvoice(params: CreateInvoiceParams, config: ProviderConfig): Promise<InvoiceResponse>;
     abstract verifyCallback(body: any, config: ProviderConfig): Promise<VerifyCallbackResult>;
+    abstract getPaymentMethods(params: GetPaymentMethodsParams, config: ProviderConfig): Promise<GetPaymentMethodsResult>;
+    abstract checkTransaction(params: CheckTransactionParams, config: ProviderConfig): Promise<CheckTransactionResult>;
+    /** Probe/discover which payment methods are actually enabled/active for the merchant */
+    probePaymentMethods?(config: ProviderConfig): Promise<{
+        success: boolean;
+        enabled: string[];
+        error?: string;
+    }>;
+}
+
+declare class MidtransClient {
+    private apiKey;
+    private sandbox;
+    constructor(config: {
+        apiKey: string;
+        sandbox: boolean;
+    } | ProviderConfig);
+    private getApiBaseUrl;
+    private request;
+    cancelTransaction(orderId: string): Promise<any>;
+    refundTransaction(orderId: string, payload: {
+        refund_key?: string;
+        amount?: number;
+        reason?: string;
+    }): Promise<any>;
+    expireTransaction(orderId: string): Promise<any>;
+    approveTransaction(orderId: string): Promise<any>;
+    denyTransaction(orderId: string): Promise<any>;
+    captureTransaction(transactionId: string, amount?: number): Promise<any>;
+    linkPayAccount(payload: any): Promise<any>;
+    getPayAccount(accountId: string): Promise<any>;
+    unbindPayAccount(accountId: string): Promise<any>;
+    getGoPayPromo(accountId: string, grossAmount: number, currency?: string): Promise<any>;
+    createSubscription(payload: any): Promise<any>;
+    getSubscription(subscriptionId: string): Promise<any>;
+    updateSubscription(subscriptionId: string, payload: any): Promise<any>;
+    disableSubscription(subscriptionId: string): Promise<any>;
+    enableSubscription(subscriptionId: string): Promise<any>;
+    createPaymentLink(payload: any): Promise<any>;
+    getPaymentLink(paymentLinkId: string): Promise<any>;
+    deletePaymentLink(paymentLinkId: string): Promise<any>;
+    getBalance(): Promise<any>;
+    createBillingInvoice(payload: any): Promise<any>;
+    getBillingInvoice(invoiceId: string): Promise<any>;
+    voidBillingInvoice(invoiceId: string): Promise<any>;
+    convertBillingInvoice(invoiceId: string): Promise<any>;
+}
+
+declare class MidtransProvider extends BasePaymentProvider {
+    readonly name = "midtrans";
+    private getSnapBaseUrl;
+    private getApiBaseUrl;
+    createInvoice(params: CreateInvoiceParams, config: ProviderConfig): Promise<InvoiceResponse>;
+    verifyCallback(body: any, config: ProviderConfig): Promise<VerifyCallbackResult>;
+    getPaymentMethods(params: GetPaymentMethodsParams, config: ProviderConfig): Promise<GetPaymentMethodsResult>;
+    checkTransaction(params: CheckTransactionParams, config: ProviderConfig): Promise<CheckTransactionResult>;
+    /**
+     * Get an instance of MidtransClient to perform transaction actions, subscriptions, invoicing, etc.
+     */
+    getClient(config: ProviderConfig): MidtransClient;
+    probePaymentMethods(config: ProviderConfig): Promise<{
+        success: boolean;
+        enabled: string[];
+        error?: string;
+    }>;
 }
 
 declare class DuitkuProvider extends BasePaymentProvider {
     readonly name = "duitku";
+    private getBaseUrl;
     createInvoice(params: CreateInvoiceParams, config: ProviderConfig): Promise<InvoiceResponse>;
     verifyCallback(body: any, config: ProviderConfig): Promise<VerifyCallbackResult>;
+    getPaymentMethods(params: GetPaymentMethodsParams, config: ProviderConfig): Promise<GetPaymentMethodsResult>;
+    checkTransaction(params: CheckTransactionParams, config: ProviderConfig): Promise<CheckTransactionResult>;
+    probePaymentMethods(config: ProviderConfig): Promise<{
+        success: boolean;
+        enabled: string[];
+        error?: string;
+    }>;
 }
 
+declare function getPaymentMethodCategory(code: string, name?: string): "Virtual Account" | "QRIS" | "E-Wallet" | "Retail / Gerai" | "Kartu Kredit" | "Paylater / Cicilan" | "Lainnya";
+
 declare class PaymentManager {
     private providers;
     constructor();
     registerProvider(provider: BasePaymentProvider): void;
     getProvider(name: string): BasePaymentProvider;
+    getMidtransProvider(): MidtransProvider;
+    getMidtransClient(config: ProviderConfig): MidtransClient;
     createInvoice(providerName: string, params: CreateInvoiceParams, config: ProviderConfig): Promise<InvoiceResponse>;
     verifyCallback(providerName: string, body: any, config: ProviderConfig): Promise<VerifyCallbackResult>;
+    getPaymentMethods(providerName: string, params: GetPaymentMethodsParams, config: ProviderConfig): Promise<GetPaymentMethodsResult>;
+    checkTransaction(providerName: string, params: CheckTransactionParams, config: ProviderConfig): Promise<CheckTransactionResult>;
+    probePaymentMethods(providerName: string, config: ProviderConfig): Promise<{
+        success: boolean;
+        enabled: string[];
+        error?: string;
+    }>;
 }
 declare const paymentManager: PaymentManager;
 
-export { BasePaymentProvider, type CreateInvoiceParams, DuitkuProvider, type InvoiceResponse, PaymentManager, type ProviderConfig, type VerifyCallbackResult, paymentManager };
+export { BasePaymentProvider, type CheckTransactionParams, type CheckTransactionResult, type CreateInvoiceParams, DuitkuProvider, type GetPaymentMethodsParams, type GetPaymentMethodsResult, type InvoiceResponse, MidtransClient, MidtransProvider, PaymentManager, type PaymentMethod, type ProviderConfig, type VerifyCallbackResult, getPaymentMethodCategory, paymentManager };

package/dist/index.d.ts

@@ -9,11 +9,23 @@ interface CreateInvoiceParams {
     };
     returnUrl: string;
     callbackUrl: string;
+    /** Specific Duitku payment method code (e.g. "BCA", "I1", "OV"). If omitted, all methods are available via Duitku's redirect page. */
+    paymentMethod?: string;
+    /** Provider-specific parameters (e.g., token_id, billing details, custom headers/fields) */
+    providerParams?: any;
 }
 interface InvoiceResponse {
     success: boolean;
     paymentUrl?: string;
     reference?: string;
+    /** Virtual Account number (for bank VA methods) */
+    vaNumber?: string;
+    /** QRIS string for display in a QR code */
+    qrString?: string;
+    /** Duitku-hosted QR code image URL */
+    qrCodeUrl?: string;
+    /** Generic payment code (for retail/minimarket methods like Indomaret) */
+    paymentCode?: string;
     rawResponse: any;
     error?: string;
 }
@@ -29,27 +41,149 @@ interface ProviderConfig {
     apiKey: string;
     sandbox: boolean;
 }
+interface GetPaymentMethodsParams {
+    /** Transaction amount (integer, no decimal) */
+    amount: number;
+}
+interface PaymentMethod {
+    /** Provider-specific method code, e.g. "BT", "I1", "OL" */
+    paymentMethod: string;
+    /** Human-readable name, e.g. "BCA Virtual Account" */
+    paymentName: string;
+    /** URL to payment method logo/image */
+    paymentImage: string;
+    /** Total transaction fee in IDR (string from API) */
+    totalFee: string;
+    /** Categorized payment channel (Virtual Account, QRIS, E-Wallet, Retail / Gerai, Kartu Kredit, Paylater / Cicilan, Lainnya) */
+    category: "Virtual Account" | "QRIS" | "E-Wallet" | "Retail / Gerai" | "Kartu Kredit" | "Paylater / Cicilan" | "Lainnya";
+}
+interface GetPaymentMethodsResult {
+    success: boolean;
+    methods: PaymentMethod[];
+    error?: string;
+    rawResponse: any;
+}
+interface CheckTransactionParams {
+    /** The merchant order ID used when creating the invoice */
+    merchantOrderId: string;
+}
+interface CheckTransactionResult {
+    success: boolean;
+    orderId: string;
+    reference: string;
+    amount: number;
+    /** "00" = success/paid, "01" = pending, "02" = failed/expired */
+    statusCode: string;
+    status: "paid" | "pending" | "failed";
+    statusMessage: string;
+    error?: string;
+    rawResponse: any;
+}
 
 declare abstract class BasePaymentProvider {
     abstract readonly name: string;
     abstract createInvoice(params: CreateInvoiceParams, config: ProviderConfig): Promise<InvoiceResponse>;
     abstract verifyCallback(body: any, config: ProviderConfig): Promise<VerifyCallbackResult>;
+    abstract getPaymentMethods(params: GetPaymentMethodsParams, config: ProviderConfig): Promise<GetPaymentMethodsResult>;
+    abstract checkTransaction(params: CheckTransactionParams, config: ProviderConfig): Promise<CheckTransactionResult>;
+    /** Probe/discover which payment methods are actually enabled/active for the merchant */
+    probePaymentMethods?(config: ProviderConfig): Promise<{
+        success: boolean;
+        enabled: string[];
+        error?: string;
+    }>;
+}
+
+declare class MidtransClient {
+    private apiKey;
+    private sandbox;
+    constructor(config: {
+        apiKey: string;
+        sandbox: boolean;
+    } | ProviderConfig);
+    private getApiBaseUrl;
+    private request;
+    cancelTransaction(orderId: string): Promise<any>;
+    refundTransaction(orderId: string, payload: {
+        refund_key?: string;
+        amount?: number;
+        reason?: string;
+    }): Promise<any>;
+    expireTransaction(orderId: string): Promise<any>;
+    approveTransaction(orderId: string): Promise<any>;
+    denyTransaction(orderId: string): Promise<any>;
+    captureTransaction(transactionId: string, amount?: number): Promise<any>;
+    linkPayAccount(payload: any): Promise<any>;
+    getPayAccount(accountId: string): Promise<any>;
+    unbindPayAccount(accountId: string): Promise<any>;
+    getGoPayPromo(accountId: string, grossAmount: number, currency?: string): Promise<any>;
+    createSubscription(payload: any): Promise<any>;
+    getSubscription(subscriptionId: string): Promise<any>;
+    updateSubscription(subscriptionId: string, payload: any): Promise<any>;
+    disableSubscription(subscriptionId: string): Promise<any>;
+    enableSubscription(subscriptionId: string): Promise<any>;
+    createPaymentLink(payload: any): Promise<any>;
+    getPaymentLink(paymentLinkId: string): Promise<any>;
+    deletePaymentLink(paymentLinkId: string): Promise<any>;
+    getBalance(): Promise<any>;
+    createBillingInvoice(payload: any): Promise<any>;
+    getBillingInvoice(invoiceId: string): Promise<any>;
+    voidBillingInvoice(invoiceId: string): Promise<any>;
+    convertBillingInvoice(invoiceId: string): Promise<any>;
+}
+
+declare class MidtransProvider extends BasePaymentProvider {
+    readonly name = "midtrans";
+    private getSnapBaseUrl;
+    private getApiBaseUrl;
+    createInvoice(params: CreateInvoiceParams, config: ProviderConfig): Promise<InvoiceResponse>;
+    verifyCallback(body: any, config: ProviderConfig): Promise<VerifyCallbackResult>;
+    getPaymentMethods(params: GetPaymentMethodsParams, config: ProviderConfig): Promise<GetPaymentMethodsResult>;
+    checkTransaction(params: CheckTransactionParams, config: ProviderConfig): Promise<CheckTransactionResult>;
+    /**
+     * Get an instance of MidtransClient to perform transaction actions, subscriptions, invoicing, etc.
+     */
+    getClient(config: ProviderConfig): MidtransClient;
+    probePaymentMethods(config: ProviderConfig): Promise<{
+        success: boolean;
+        enabled: string[];
+        error?: string;
+    }>;
 }
 
 declare class DuitkuProvider extends BasePaymentProvider {
     readonly name = "duitku";
+    private getBaseUrl;
     createInvoice(params: CreateInvoiceParams, config: ProviderConfig): Promise<InvoiceResponse>;
     verifyCallback(body: any, config: ProviderConfig): Promise<VerifyCallbackResult>;
+    getPaymentMethods(params: GetPaymentMethodsParams, config: ProviderConfig): Promise<GetPaymentMethodsResult>;
+    checkTransaction(params: CheckTransactionParams, config: ProviderConfig): Promise<CheckTransactionResult>;
+    probePaymentMethods(config: ProviderConfig): Promise<{
+        success: boolean;
+        enabled: string[];
+        error?: string;
+    }>;
 }
 
+declare function getPaymentMethodCategory(code: string, name?: string): "Virtual Account" | "QRIS" | "E-Wallet" | "Retail / Gerai" | "Kartu Kredit" | "Paylater / Cicilan" | "Lainnya";
+
 declare class PaymentManager {
     private providers;
     constructor();
     registerProvider(provider: BasePaymentProvider): void;
     getProvider(name: string): BasePaymentProvider;
+    getMidtransProvider(): MidtransProvider;
+    getMidtransClient(config: ProviderConfig): MidtransClient;
     createInvoice(providerName: string, params: CreateInvoiceParams, config: ProviderConfig): Promise<InvoiceResponse>;
     verifyCallback(providerName: string, body: any, config: ProviderConfig): Promise<VerifyCallbackResult>;
+    getPaymentMethods(providerName: string, params: GetPaymentMethodsParams, config: ProviderConfig): Promise<GetPaymentMethodsResult>;
+    checkTransaction(providerName: string, params: CheckTransactionParams, config: ProviderConfig): Promise<CheckTransactionResult>;
+    probePaymentMethods(providerName: string, config: ProviderConfig): Promise<{
+        success: boolean;
+        enabled: string[];
+        error?: string;
+    }>;
 }
 declare const paymentManager: PaymentManager;
 
-export { BasePaymentProvider, type CreateInvoiceParams, DuitkuProvider, type InvoiceResponse, PaymentManager, type ProviderConfig, type VerifyCallbackResult, paymentManager };
+export { BasePaymentProvider, type CheckTransactionParams, type CheckTransactionResult, type CreateInvoiceParams, DuitkuProvider, type GetPaymentMethodsParams, type GetPaymentMethodsResult, type InvoiceResponse, MidtransClient, MidtransProvider, PaymentManager, type PaymentMethod, type ProviderConfig, type VerifyCallbackResult, getPaymentMethodCategory, paymentManager };