Kobara Node.js SDK

Official Node.js library for integrating the Kobara API. This SDK enables quick integration of secure MonCash payments, payment links, webhooks, and manual withdrawal requests.

Installation

Install the package via npm:

npm install kobara

Or via yarn:

yarn add kobara

Configuration

Initialize the client with your secret API key. Never expose your secret key on the client side.

import { Kobara } from "kobara";

const kobara = new Kobara({
  secretKey: process.env.KOBARA_SECRET_KEY,
});

To configure a different base URL (for example, for testing environment):

const kobara = new Kobara({
  secretKey: process.env.KOBARA_SECRET_KEY,
  baseUrl: "https://api.kobara.app/api/v1" // Optional
});

Usage Examples

1. Payments

Create a Payment

Create a new payment transaction with optional metadata and a custom idempotency key to prevent double charging.

try {
  const payment = await kobara.payments.create({
    amount: 2500,
    currency: "HTG",
    description: "Order #89457",
    customer: {
      name: "Jean Exemple",
      email: "[email protected]",
      phone: "50900000000"
    },
    metadata: {
      internal_order_id: "ORD-89457"
    },
    success_url: "https://monsite.com/success",
    error_url: "https://monsite.com/error",
    webhook_url: "https://monsite.com/webhooks/kobara"
  }, {
    idempotencyKey: "unique-idempotency-key-value" // Optional
  });

  console.log("Checkout URL:", payment.checkout_url);
} catch (error) {
  console.error("Payment creation failed:", error.message);
}

Retrieve a Payment

Get the status and details of a specific payment transaction by its ID:

const payment = await kobara.payments.retrieve("payment_id");
console.log("Payment status:", payment.status);

List Payments

List recent payment transactions with optional limit and filter by status:

const response = await kobara.payments.list({
  limit: 10,
  status: "succeeded"
});

console.log("Total payments fetched:", response.data.length);

2. Payment Links

Create a Payment Link

Generate reusable, shareable payment links:

const link = await kobara.paymentLinks.create({
  title: "Ebook Tailwind CSS",
  description: "Ebook premium en format PDF",
  amount: 500,
  currency: "HTG"
});

console.log("Payment Link URL:", link.url);

List Payment Links

const response = await kobara.paymentLinks.list({
  limit: 5
});

3. Withdrawals

Request a Withdrawal

Request a manual payout to your MonCash or Bank account:

const withdrawal = await kobara.withdrawals.create({
  amount: 5000,
  method: "moncash",
  reference: "50937012345"
});

console.log("Withdrawal ID:", withdrawal.id);

Retrieve a Withdrawal

const withdrawal = await kobara.withdrawals.retrieve("withdrawal_id");

4. Webhooks Verification

Securely verify that incoming webhook requests are genuinely sent by Kobara using HMAC SHA-256 validation.

import express from "express";
import { Kobara } from "kobara";

const app = express();
const kobara = new Kobara({ secretKey: process.env.KOBARA_SECRET_KEY });

// webhook route must receive raw body string
app.post("/webhooks/kobara", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["kobara-signature"];
  const secret = process.env.KOBARA_WEBHOOK_SECRET;

  try {
    const event = kobara.webhooks.constructEvent(
      req.body.toString(),
      signature,
      secret
    );

    console.log("Verified Event:", event.type);
    
    if (event.type === "payment.succeeded") {
      const payment = event.data.payment;
      // Deliver services
    }

    res.status(200).send({ received: true });
  } catch (err) {
    console.error("Webhook signature verification failed:", err.message);
    res.status(400).send(`Webhook Error: ${err.message}`);
  }
});

Error Handling

This SDK throws subclasses of KobaraError to help you identify failures quickly:

• KobaraAPIError: For errors returned by the Kobara API endpoints (HTTP response statuses 4xx, 5xx).
• KobaraSignatureVerificationError: Thrown by webhooks.constructEvent() when signature verification fails.

import { KobaraAPIError } from "kobara";

try {
  await kobara.payments.retrieve("non-existent-id");
} catch (error) {
  if (error instanceof KobaraAPIError) {
    console.error("API error status:", error.statusCode); // e.g. 404
  } else {
    console.error("Generic network error:", error.message);
  }
}

License

MIT License. See LICENSE for details.