Inkress SDK Integration Guide

Prerequisites

Installation

npm install @inkress/admin-sdk

Environment Variables

INKRESS_API_KEY

Register as an Organisation.
Generate an API Key with Admin permissions.
Create a Merchant with unique username. We'll call this your Platform Merchant.
Switch to your new Merchant Account using the top right hand side dropdown.
Create a Subscription Plan for your new merchant and copy the link using the actions (You'll need this later).

1

SDK Configuration

Create a centralized service to manage SDK instances. You need to handle two contexts: Platform Context (for managing merchants) and Merchant Context (for acting as a merchant).

lib/inkress.ts TypeScript

import InkressSDK from "@inkress/admin-sdk";

const INKRESS_CONFIG = {
  accessToken: process.env.INKRESS_API_KEY,
  mode: process.env.NODE_ENV === 'production' ? 'live' : 'sandbox',
  platformMerchantId: 'your-platform-username',
};

/**
 * Creates an SDK instance.
 * @param merchantUsername - (Optional) If provided, scopes actions to this sub-merchant.
 */
export async function createInkressSDK(merchantUsername?: string) {
  return new InkressSDK({
    accessToken: INKRESS_CONFIG.accessToken,
    mode: INKRESS_CONFIG.mode,
    username: merchantUsername, 
  });
}

2

Merchant Onboarding

When a new vendor joins, create a corresponding "Merchant" entity in Inkress. This links their account to the payment infrastructure.

services/onboarding.ts

async function onboardMerchant(merchantInfo) {
  const platformSdk = await createInkressSDK(); // No username = Platform Context

  const merchant = await platformSdk.merchants.create({
    name: merchantInfo.business_name,
    email: merchantInfo.email,
    username: merchantInfo.unique_slug,
    business_type: 'service',
    webhook_url: 'https://your-platform.com/api/webhooks/inkress',
    data: {
      internal_id: merchantInfo.id
    }
  });

  return { inkressId: merchant.id, inkressUsername: merchant.username };
}

3

Subscription Management

Important: Use subscriptions.createLink instead of orders.create for recurring billing.

When a merchant selects a plan, create a subscription link using the plan's UID.
You can get your plans UID from API or the last part of your subscription link, which you can copy the from the dashboard.

services/billing.ts

async function subscribeMerchant(merchantUsername, planUid, merchantDetails) {
  const merchantSdk = await createInkressSDK(merchantUsername);

  // Create a subscription link
  const result = await merchantSdk.subscriptions.createLink({
    title: 'Platform Subscription',
    plan_uid: planUid, // Use the UID string, e.g., "plan_abc123"
    customer: {
      first_name: merchantDetails.firstName,
      last_name: merchantDetails.lastName,
      email: merchantDetails.email
    },
    meta_data: {
    return_url: 'https://your-platform.com/dashboard/plans',
      internal_merchant_id: merchantDetails.id
    },
    reference_id: `sub_${merchantDetails.id}_${Date.now()}`
  });

  return result.payment_urls.short_link;
}

4

Making Products

Create Inkress products on-the-fly when they are needed (e.g., at the time of first order). and store the Inkress product ID in your local database for future reference.

services/catalog.ts

async function syncProduct(merchantUsername, serviceItem) {
  const merchantSdk = await createInkressSDK(merchantUsername);

  const product = await merchantSdk.products.create({
    title: serviceItem.name,
    price: serviceItem.price,
    currency_id: 1, // 1=JMD, 2=USD
    permalink: `item-${serviceItem.id}`,
    public: false
  });

  return product.id;
}

5

Order Processing

Handle customer transactions by creating Orders. This supports full payments, deposits, and payment links.

services/orders.ts

async function createTransaction(merchantUsername, orderDetails) {
  const merchantSdk = await createInkressSDK(merchantUsername);
  
  // 1. Resolve Product ID
  let productId = orderDetails.item.inkress_product_id;

  // 2. Create Order
  const order = await merchantSdk.orders.create({
    customer: {
      email: orderDetails.customer.email,
      name: orderDetails.customer.name
    },
    products: [{
      id: productId,
      quantity: 1,
    }],
    kind: 'online',
    meta_data: {
        return_url: 'https://your-platform.com/checkout/complete',
    },
  });

  return order.payment_urls.short_link;
}

6

Webhook Integration

A single webhook endpoint handles updates for all merchants and subscriptions.

api/webhooks.ts

export async function webhookHandler(request) {
  const payload = await request.json();
  const { event, data } = payload;

  switch (event) {
    case 'orders.paid':
      if (data.order.reference) {
        await updateTransactionStatus(data.order.reference, 'paid');
      }
      break;

    case 'subscriptions.activated':
      await updateMerchantAccess(data.customer.email, 'active');
      break;
  }
  
  return { received: true };
}