Prestmit Partners API Client

A TypeScript/JavaScript client library for interacting with the Prestmit Partners API. This SDK provides a convenient way to integrate with Prestmit's gift card trading, wallet management, and other services in your Node.js applications.

Features

• Gift Card Trading: Buy and sell gift cards programmatically
• Wallet Management: Check balances and transaction history
• Bank Account Integration: Manage Naira and Cedis bank accounts
• TypeScript Support: Full type definitions for better development experience
• Promise-based API: Modern async/await support
• Environment Support: Switch between production and sandbox environments

Installation

npm install prestmit-partners-api
# or
yarn add prestmit-partners-api

Prerequisites

• Node.js 14.x or later
• Prestmit Partner API credentials (API Key and Secret Key)

Quickstart

import dotenv from "dotenv";

dotenv.config();
import { PrestmitService } from "prestmit-partners-api";

const { API_KEY, SECRETE_KEY } = process.env;

const service = new PrestmitService({
  environment: "sandbox", // or 'production'
  apiKey: API_KEY as string,
  secretKey: SECRETE_KEY as string,
});

const status = await service.checkServiceStatus();
console.log(status);

Configuration

PrestmitServiceOptions

new PrestmitService(options: PrestmitServiceOptions)

| Parameter | Type | Required | Description | | ----------- | ------------------------- | -------- | ---------------------------------- | | environment | 'production' | 'sandbox' | No | The API environment to use | | apiKey | string | Yes | Your Prestmit Partner API key | | secretKey | string | Yes | Your Prestmit Partner secret key | | version | string | No | API version (default: 'v1') | | debug | boolean | No | Enable debug logs (default: false) |

Debug Logging

Enable debug logging when troubleshooting:

const service = new PrestmitService({
  environment: "sandbox",
  apiKey: "your-api-key",
  secretKey: "your-secret-key",
  debug: true,
});

When enabled, the SDK logs:

• Requests: method, full URL, params, masked headers, safe payload summary
• Responses: status and response body
• Errors: status and response body

IP Whitelisting (Common)

Prestmit may restrict API keys to specific IP addresses. Prestmit validates the public/egress IP of the server making the request.

If you see:

Unauthorized. Ip address is not allowed.

Whitelist your public IP in Prestmit (or route traffic through a static egress IP).

Request Signing (HMAC)

This SDK automatically signs every request using an API-Hash header.

The hash is generated as:

payload = "<API-KEY>:<normalized_request_body>"
API-Hash = HMAC_SHA256(payload, <SECRET_KEY>)

How the request body is normalized

To ensure the hash matches Prestmit's expectation, the SDK normalizes the request body before hashing:

• JSON requests (typical POST/PUT/PATCH)

  • Excludes attachments and attachments[] fields from the hashed body.
  • Excludes streams/buffers and any values that are undefined, "undefined", or empty strings.

• Form-data requests (file uploads)

  • Detects form-data (Node) payloads and extracts only the non-file fields.
  • Skips file parts and excludes attachments / attachments[] from the hashed body.
  • Important: attachments/files are still sent in the request. They are only excluded from the hash.

• GET requests / query params

  • Hashes a normalized representation of query parameters.
  • Excludes invalid/empty values and excludes attachments / attachments[].

Usage

Basic Setup

import { PrestmitService } from "prestmit-partners-api";

// Initialize the service with your API credentials
const service = new PrestmitService({
  environment: "sandbox", // or 'production'
  apiKey: "your-api-key",
  secretKey: "your-secret-key",
  debug: false,
});

Example: Fetching Gift Card Categories

async function getGiftCardCategories() {
  try {
    const categories = await service.fetchGiftcardCategories();
    console.log("Available categories:", categories);
    return categories;
  } catch (error) {
    console.error("Error fetching categories:", error);
    throw error;
  }
}

Example: Selling a Gift Card

async function sellGiftCard(cardDetails) {
  try {
    const result = await service.sellGiftcard({
      categoryID: cardDetails.categoryId,
      subCategoryID: cardDetails.subCategoryId,
      amount: cardDetails.amount,
      rate: cardDetails.rate,
      payoutMethod: cardDetails.payoutMethod,
      attachments: [cardDetails.receiptImagePath],
      // ... other required fields
    });
    console.log("Gift card sold successfully:", result);
    return result;
  } catch (error) {
    console.error("Error selling gift card:", error);
    throw error;
  }
}

API Reference

PrestmitService

The main class for interacting with the Prestmit API.

Available Methods

Gift Card Operations

• fetchGiftcardCategories(): Get list of available gift card categories
• fetchGiftcardSubcategories(params): Get subcategories for a category
• fetchGiftcardOrderHistory(page): Get gift card order history
• sellGiftcard(data): Sell a gift card

Wallet Operations

• fetchFiatWalletDetails(wallet): Get fiat wallet details
• fetchFiatWithdrawalHistory(page, wallet): Get withdrawal history
• fetchWithdrawalReceipt(id): Get withdrawal receipt

Bank Account Operations

• addNairaBankAccount(data): Add a Naira bank account
• fetchNairaBankAccounts(page): List Naira bank accounts
• removeNairaBankAccount(id): Remove a Naira bank account
• addCedisBankAccount(data): Add a Cedis bank account
• fetchCedisBankAccounts(page): List Cedis bank accounts
• removeCedisBankAccount(id): Remove a Cedis bank account

Error Handling

The SDK throws PrestmitError for API-related errors. Depending on the HTTP status code, a more specific error class may be thrown:

• PrestmitAuthError (401/403)
• PrestmitValidationError (422)
• PrestmitRateLimitError (429)
• PrestmitServerError (5xx)
• PrestmitNetworkError (no response / connection issues)

Always wrap API calls in try/catch blocks:

try {
  const result = await service.someMethod();
} catch (error) {
  console.error("API Error:", error.message);
  console.error("Status Code:", error.status);
  console.error("Error Details:", error.details);
}

You can also catch specific errors:

import {
  PrestmitAuthError,
  PrestmitRateLimitError,
  PrestmitValidationError,
} from "prestmit-partners-api";

try {
  const result = await service.someMethod();
} catch (error) {
  if (error instanceof PrestmitAuthError) {
    // handle auth/ip whitelist issues
  }
  if (error instanceof PrestmitValidationError) {
    // handle validation issues
  }
  if (error instanceof PrestmitRateLimitError) {
    // handle rate limiting
  }
  throw error;
}

Development

Prerequisites

• Node.js 14+
• npm or yarn

Setup

1. Clone the repository
2. Install dependencies:

   npm install
   # or
   yarn

3. Create a .env file with your test credentials:

   SECRETE_KEY=your_test_secret_key
   API_KEY=your_test_api_key

Building

# Build the project
npm run build

# Watch for changes and rebuild
npm run build:watch

Testing

# Run tests
npm test

# Run in development mode with hot-reload
npm run dev

Common Issues

1. Connection Issues:

   • Ensure you have a stable internet connection
   • Check if the Prestmit API is accessible from your network
   • Verify the API endpoint URLs in src/core/clients.ts

2. Authentication Errors:

   • Double-check your API key and secret key
   • Ensure you're using the correct environment (sandbox vs production)
   • Verify that your account has the necessary permissions

3. Rate Limiting:

   • The API might have rate limits
   • Add delays between requests if you encounter rate limit errors

4. TypeScript Errors:

   • Run npm run build to check for TypeScript compilation errors
   • Make sure all required environment variables are properly typed

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, please contact Prestmit support at [email protected]

Acknowledgements

• Prestmit for their API
• All contributors who have helped improve this library