@bayarqrcom/sdk

Official Node.js SDK for BayarQR Payment Hub API.

Current package version: 1.1.3

Install

npm install @bayarqrcom/sdk

Quick Start

const { BayarQR } = require('@bayarqrcom/sdk');

const client = new BayarQR({
    apiKey: 'your-api-key-here',
    environment: 'LIVE' // or 'SANDBOX' for testing
});

// Create a QRIS payment
const tx = await client.transaction.create({
    amount: 50000,              // Amount in Rupiah
    referenceId: 'order_123'    // Your order ID (appears in webhook)
});

console.log(tx.data.qrImageUrl);    // QR image to show buyer
console.log(tx.data.qrDownloadUrl); // Authenticated API path to download PNG
console.log(tx.data.referenceId);   // Track this payment
console.log(tx.data.expiresAt);     // Payment deadline

Note: The SDK automatically maps amount to the API's baseAmount field internally. You always use amount in the SDK.

Features

• Transaction creation (QRIS dynamic QR)
• Payment link management (hosted checkout)
• Static QRIS merchant to dynamic QR with reference, amount, status, and webhook
• Multi-merchant routing for one app/account via default merchant, credentialId, rotation, or configured ecosystemCode
• QR appearance selection per transaction/payment link via qrStyle and finalized qrAssetId
• Authenticated QR PNG download for advanced/API integrations
• Bot commerce (Telegram/WhatsApp)
• Webhook signature verification
• Auto-retry on 429/5xx with exponential backoff
• TypeScript types included
• Zero dependencies (uses native fetch)

API Reference

Transaction

// Create payment
const tx = await client.transaction.create({
    amount: 50000,
    category: 'produk',
    referenceId: 'order_123',
    // Optional: use a specific finalized QR Studio asset for this brand/channel.
    // Copy qrAssetId from Dashboard > Branding (Salin ID API)
    // or QR Studio V3 saved assets (Salin ID).
    qrStyle: 'asset',
    qrAssetId: 'cmxxxxx_finalized_asset_id'
});

// Force a plain QR for a brand or flow that should not use account branding
const plainTx = await client.transaction.create({
    amount: 50000,
    qrStyle: 'plain'
});

// Check status
const status = await client.transaction.getStatus('REF-abc123');

// Download QR PNG later by referenceId.
// Pass the same qrAssetId if you want to force the same finalized brand asset.
const qrPng = await client.transaction.downloadQr('REF-abc123', {
    qrStyle: 'asset',
    qrAssetId: 'cmxxxxx_finalized_asset_id'
});
require('fs').writeFileSync(qrPng.filename || 'bayarqr-qr.png', Buffer.from(qrPng.data));

// List transactions
const list = await client.transaction.list({ page: 1, limit: 20 });

// Manual confirm is intentionally dashboard-only.
// API-key SDK calls are rejected with INTERACTIVE_SESSION_REQUIRED.

Payment Link

// Create hosted checkout page
const link = await client.paymentLink.create({
    title: 'E-book Bisnis Digital',
    amount: 99000,
    category: 'produk',
    successUrl: 'https://yoursite.com/thanks',
    appearanceConfig: {
        requireBuyerEmail: true,
        // Copy qrAssetId from Dashboard > Branding or QR Studio V3.
        qrStyle: 'asset',
        qrAssetId: 'cmxxxxx_finalized_asset_id'
    }
});

console.log(link.data.url); // Share this URL to buyers

// List links
const links = await client.paymentLink.list({ status: 'ACTIVE' });

// Disable/archive
await client.paymentLink.disable('slug-here');
await client.paymentLink.archive('slug-here');

Bot Commerce

// Create payment for Telegram/WhatsApp bot
const payment = await client.bot.createPayment({
    amount: 25000,
    orderId: 'TR-5000X',
    chatId: '3910394012',
    customerId: 'user_7392',
    productLabel: 'Premium Pass 1 Bulan'
});

// Send QR to user in chat
bot.sendPhoto(chatId, payment.data.qrImageUrl);
bot.sendMessage(chatId, payment.data.displayText);

Webhook Verification

const express = require('express');
const app = express();

// IMPORTANT: Use raw body for signature verification
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
    const isValid = client.webhook.verifySignature(
        req.body,                                    // raw body (Buffer)
        req.headers['x-bayarqr-signature'],         // signature header
        process.env.BAYARQR_API_SECRET              // your API secret
    );

    if (!isValid) {
        return res.status(401).send('Invalid signature');
    }

    const event = JSON.parse(req.body);

    switch (event.event) {
        case 'payment.success':
            console.log('Payment received:', event.data.amount);
            console.log('Reference:', event.data.referenceId);
            console.log('Routing code:', event.data.ecosystemCode);
            // Fulfill order...
            break;
        case 'payment.expired':
            // Handle expiry...
            break;
        case 'payment.failed':
            // Handle failure...
            break;
    }

    res.status(200).send('OK');
});

Configuration

| Option | Default | Description | |--------|---------|-------------| | apiKey | (required) | API key from Dashboard | | baseUrl | https://bayarqr.com/api/v1 | API base URL | | environment | 'LIVE' | 'LIVE' or 'SANDBOX' | | timeout | 30000 | Request timeout (ms) | | maxRetries | 3 | Auto-retry on 429/5xx |

Error Handling

const { BayarQR, BayarQRError } = require('@bayarqrcom/sdk');

try {
    const tx = await client.transaction.create({ amount: 50000 });
} catch (err) {
    if (err instanceof BayarQRError) {
        console.error('API Error:', err.message);
        console.error('Code:', err.code);           // e.g., 'INSUFFICIENT_CREDIT'
        console.error('Status:', err.statusCode);   // e.g., 402
        console.error('Request ID:', err.requestId);
    }
}

Requirements

• Node.js >= 18 (uses native fetch)
• For Node.js 16-17, install node-fetch and pass it as global

License

MIT