Tinker Payments Node SDK

Node.js SDK for the standardized Tinker Payments API (/v1) with automatic authentication, sandbox/production environment routing, payment initiate/query, subscriptions, and webhook verification.

The SDK is authored in TypeScript and published as compiled CommonJS JavaScript with generated type declarations. It works in both JavaScript and TypeScript projects.

Installation

npm install tinker-payments-node-sdk

JavaScript Usage

const { TinkerPayments } = require('tinker-payments-node-sdk');

const client = new TinkerPayments('pk_test_xxx', 'sk_test_xxx');

// Payment initiate
const payment = await client.transactions().initiate({
  amount: 1200,
  currency: 'KES',
  gateway: 'mpesa',
  merchantReference: 'ORDER-1001',
  returnUrl: 'https://merchant.example/callback',
  customerEmail: '[email protected]',
  customerPhone: '+254712345678',
  transactionDesc: 'Payment for order ORDER-1001'
});

// Payment query
const result = await client.transactions().query({
  reference: 'TP-REF-123',
  gateway: 'mpesa'
});

TypeScript Usage

import { TinkerPayments, type PaymentInitiateRequest } from 'tinker-payments-node-sdk';

const client = new TinkerPayments('pk_test_xxx', 'sk_test_xxx');

const request: PaymentInitiateRequest = {
  amount: 1200,
  currency: 'KES',
  gateway: 'mpesa',
  merchantReference: 'ORDER-1001',
  returnUrl: 'https://merchant.example/callback',
  customerEmail: '[email protected]',
  customerPhone: '+254712345678',
  transactionDesc: 'Payment for order ORDER-1001'
};

const payment = await client.transactions().initiate(request);

Error Handling

import { TinkerPayments, errors } from 'tinker-payments-node-sdk';

const client = new TinkerPayments('pk_test_xxx', 'sk_test_xxx');

try {
  await client.transactions().initiate({
    amount: 1200,
    currency: 'KES',
    gateway: 'mpesa',
    merchantReference: 'ORDER-1001',
    returnUrl: 'https://merchant.example/callback',
    customerPhone: '+254712345678',
    transactionDesc: 'Payment for order ORDER-1001'
  });
} catch (error) {
  if (error instanceof errors.TinkerError) {
    console.error(error.getError());
  }
}

Environment Resolution

• Uses https://sandbox-api.tinkerpayments.com/v1/ when keys start with pk_test_ or sk_test_.
• Uses https://api.tinkerpayments.com/v1/ for live keys.
• Override with new TinkerPayments(pk, sk, { baseUrl: 'https://custom-host/v1' }).

Standard API Envelope

All standardized endpoints are expected to return:

{
  "success": true,
  "data": {},
  "error": null,
  "meta": {
    "request_id": "5b5b3526-8dc1-4f7b-9bb8-cdbfc8df4984",
    "timestamp": "2026-02-11T22:52:45Z",
    "environment": "production"
  }
}

The SDK stores the latest auth envelope meta via client.getLastAuthMeta().

Subscriptions

const subscriptions = client.subscriptions();

await subscriptions.createPlan({
  name: 'Pro',
  amount: 1000,
  currency: 'KES',
  intervals: ['monthly'],
  description: 'Pro plan',
  is_active: true
});

await subscriptions.listPlans();
await subscriptions.create({
  plan_id: 'plan_123',
  gateway: 'stripe',
  customer: {
    external_customer_id: 'cust_123',
    email: '[email protected]'
  }
});
await subscriptions.list('plan_123', 'cust_123');
await subscriptions.cancel('sub_123');

Webhooks

const event = client.webhooks().handle(rawBody);

const ok = client.webhooks().verifySignature(event, process.env.TINKER_WEBHOOK_SECRET);
if (!ok) {
  throw new Error('Invalid signature');
}

Signature verification uses HMAC-SHA256 on JSON payload fields: id, type, source, timestamp, data, and meta.

Development

npm install
npm run build
npm test

The TypeScript source lives in src/. npm run build emits runtime JavaScript and .d.ts files into dist/, and package.json points consumers at:

{
  "main": "dist/index.js",
  "types": "dist/index.d.ts"
}

Before publishing, run:

npm test
npm pack --dry-run