moncash-sdk

MonCash SDK

A powerful Node.js/TypeScript SDK for integrating MonCash payment services into your applications.

Table of Contents

• Installation
• Prerequisites
• Setup
• Usage
• Error Handling
• Features

Installation

npm install moncash-sdk
# or
yarn add moncash-sdk

Prerequisites

Before using this SDK, make sure you have:

• A MonCash business account
• Client ID and Client Secret from MonCash
• Node.js version 14 or higher

Setup

• Install the package in your project
• Import and initialize the SDK:

import MoncashSDK from "moncash-sdk";

const moncash = new MoncashSDK({
  clientId: "your-client-id",
  clientSecret: "your-client-secret",
  mode: "sandbox", // Use 'live' for production
  maxRetries: 3,
  timeout: 30000, // 30 seconds
});

Usage

Creating a Payment

try {
  const payment = await moncash.createPayment(100, "ORDER123");
  console.log("Payment URL:", payment.redirectUrl);
  console.log("Payment Token:", payment.paymentToken);
} catch (error) {
  console.error("Payment failed:", error.message);
}

Retrieving a Transaction

try {
  const transaction = await moncash.getTransaction("transaction-id");
  console.log("Transaction:", transaction);
} catch (error) {
  console.error("Failed to get transaction:", error.message);
}

Retrieving an Order

try {
  const order = await moncash.getOrder("order-id");
  console.log("Order:", order);
} catch (error) {
  console.error("Failed to get order:", error.message);
}

Making a Transfer

try {
  const transfer = await moncash.transfer(
    100,
    "reference",
    "receiver-id",
    "Payment for services",
  );
  console.log("Transfer:", transfer);
} catch (error) {
  console.error("Transfer failed:", error.message);
}

Customer status

try {
  const customerStatus = await moncash.getCustomerStatus("customerId");
  console.log(customerStatus);
} catch (error) {
  console.error("Customer status failed:", error.message);
}

Prefunded transaction status

try {
  const prefundedTransactionStatus =
    await moncash.getPrefundedTransactionStatus("referenceId");
  console.log(prefundedTransactionStatus);
} catch (error) {
  console.error("Prefunded transaction status failed:", error.message);
}

Prefunded balance

try {
  const prefundedBalance = await moncash.getPrefundedBalance();
  console.log(prefundedBalance);
} catch (error) {
  console.error("Prefunded balance failed:", error.message);
}

Error Handling

The SDK provides several specific error types to help you handle different error cases:

Error Types

• MonCashError: Base error class for all MonCash-related errors

  • statusCode: HTTP status code (if applicable)
  • response: Raw error response from the API

• OrderNotFoundError: Thrown when an order cannot be found (404)

• PaymentNotFoundError: Thrown when a payment/transaction cannot be found (404)

• RequestTimeoutError: Thrown when a request exceeds the timeout limit

Examples

Using async/await:

try {
  const order = await sdk.getOrder("orderId");
  console.log(order);
} catch (error) {
  if (error instanceof OrderNotFoundError) {
    console.log("Order not found:", error.message);
  } else if (error instanceof PaymentNotFoundError) {
    console.log("Payment not found:", error.message);
  } else if (error instanceof RequestTimeoutError) {
    console.log("Request timed out:", error.message);
  } else if (error instanceof MonCashError) {
    console.log("MonCash error:", error.message, error.statusCode);
  } else {
    console.log("Unexpected error:", error);
  }
}

Using Promises:

sdk
  .getOrder("orderId")
  .then((order) => {
    console.log(order);
  })
  .catch((error) => {
    if (error instanceof OrderNotFoundError) {
      console.log("Order not found:", error.message);
    } else if (error instanceof MonCashError) {
      console.log("MonCash error:", error.message, error.statusCode);
    }
  });

Error Status Codes

• 404: Order or Payment not found
• 401: Authentication error
• 408: Request timeout
• Other status codes will be included in the MonCashError instance

Robust Features

1. Token Management

• Automatic token caching
• Smart token refresh
• Expiration handling
• Efficient request management

2. Request Safety

• Timeout handling
• Retry mechanism
• Request validation
• Proper response parsing

3. Security

• Secure credential handling
• Base64 encoding using Buffer
• Proper authorization headers
• Sandbox/Production mode support

4. Type Safety

• Full TypeScript support
• Type definitions for all responses
• Interface definitions for configurations
• Proper type checking

Token Caching

The SDK implements automatic token caching to minimize the number of authentication requests:

• Automatically caches access tokens
• Reuses valid tokens for subsequent requests
• Handles token expiration (59 seconds lifetime)
• Refreshes tokens only when necessary
• No additional configuration required

Example:

const sdk = new MoncashSDK({
  clientId: "your-client-id",
  clientSecret: "your-client-secret",
  mode: "sandbox",
});
// First request - gets new token
await sdk.createPayment(100, "order1");
// Subsequent requests reuse the cached token if still valid
await sdk.getOrder("order1");
await sdk.getTransaction("transaction1");

The SDK will:

• Cache the token after the first request
• Reuse the cached token for ~49 seconds
• Automatically refresh when token expires
• Handle concurrent requests efficiently

This minimizes API calls and improves performance while maintaining security.

Best Practices

• Always use environment variables for credentials
• Implement proper error handling
• Use sandbox mode for testing
• Keep the SDK updated to the latest version

License

MIT License

Support

For support, please open an issue in the GitHub repository or contact our support team.