Payram TypeScript SDK

This document is for engineers who need to integrate Payram into their applications. It shows how to install the SDK, configure a client, call each API, and wire webhooks with the smallest set of concepts you need to ship to production.

What You Need

• A Payram API key and the base URL for the environment you are targeting.
• Node.js 18 or newer (for built-in fetch).
• A package manager such as npm, pnpm, or Yarn.

If you run in browsers or edge runtimes, ensure fetch is available; server-only options like httpAgent are ignored there.

Install

npm install payram

Switch to yarn add payram or pnpm add payram if those match your stack.

Note: The published build is a native Node 18+ ES module (with a matching CommonJS entry). import { Payram } from 'payram' works out of the box in ESM projects, and const { Payram } = require('payram') continues to work in CommonJS without experimental flags.

Create a Client

import { Payram } from 'payram';

const payram = new Payram({
  apiKey: process.env.PAYRAM_API_KEY!,
  baseUrl: 'https://api.payram.com',
  config: {
    timeoutMs: 10_000,
    maxRetries: 2,
    // allowInsecureHttp: true,
  },
});

apiKey and baseUrl are required. The optional config block sets retry and timeout defaults that apply to every request. Override them per call with the second argument shown later.

HTTPS URLs are mandatory unless you set config.allowInsecureHttp = true for trusted local development endpoints.

Call the Payments API

const checkout = await payram.payments.initiatePayment({
  customerEmail: '[email protected]',
  customerId: 'cust_123',
  amountInUSD: 49.99,
});

console.log(checkout.referenceId, checkout.checkoutUrl);

const paymentRequest = await payram.payments.getPaymentRequest(checkout.referenceId);
console.log(paymentRequest.paymentState);

All methods accept an optional second argument for per-request overrides:

await payram.payments.initiatePayment(payload, {
  config: { maxRetries: 5 },
  signal: abortController.signal,
  apiKeyOverride: 'temporary-key',
});

Need a shortcut? The same methods are exposed directly on the client:

await payram.initiatePayment(payload);
const payment = await payram.getPaymentRequest('ref-123');

Call the Referrals API

await payram.referrals.authenticateReferrer({
  email: '[email protected]',
  referenceID: 'program-1',
});

await payram.referrals.linkReferee({
  email: '[email protected]',
  referrerCode: 'REF-CODE',
  referenceID: 'program-1',
});

await payram.referrals.logReferralEvent({
  eventKey: 'conversion',
  referenceID: 'program-1',
  amount: 25,
});

Top-level aliases exist as payram.authenticateReferrer, payram.linkReferee, and payram.logReferralEvent.

Call the Payouts API

await payram.payouts.createPayout({
  email: '[email protected]',
  blockchainCode: 'ETH',
  currencyCode: 'USDT',
  amount: '125.50',
  toAddress: '0xfeedfacecafebeefdeadbeefdeadbeefdeadbeef',
});

const payout = await payram.payouts.getPayoutById(42);

console.log(payout.status, payout.transferHash);

The same helpers exist on the client root as payram.createPayout and payram.getPayoutById, each returning a typed MerchantPayout record. The currency payload must be one of USDC or USDT, and the allowed blockchain codes are ETH, TRX, BTC, or BASE. When creating payouts, Payram currently supports:

• USDT on the TRX or ETH networks.
• USDC on the BASE or ETH networks.

All calls support the usual per-request overrides via the second argument.

Handle Webhooks

import { Payram } from 'payram';

const payram = new Payram({ apiKey, baseUrl });

app.post(
  '/payram/webhook',
  payram.webhooks.expressWebhook(async (payload, req) => {
    console.log(payload.reference_id);
  }),
);

The SDK provides adapters for Express, Fastify, and both Next.js routers. All adapters verify the Payram API key header and return the correct acknowledgement payloads for you.

Need to validate headers manually?

import { verifyApiKey } from 'payram';

if (!verifyApiKey(req.headers, expectedApiKey)) {
  return res.status(401).json({ error: 'invalid-key' });
}

Handle Errors and Retries

Every failure is normalized to PayramSDKError so you can branch on status or retry hints.

import { isPayramSDKError } from 'payram';

try {
  await payram.initiatePayment(payload);
} catch (error) {
  if (isPayramSDKError(error)) {
    if (error.isRetryable) {
      // build your own retry loop or alerting
    }
    console.error('Payram request failed', error.status, error.error, error.requestId);
  }
}

Retries use exponential backoff by default. Adjust the strategy with config.maxRetries, config.retryPolicy, or an abort signal when initializing the client or issuing a request.

TypeScript Tips

• Payram ships with TSDoc comments for inline IntelliSense.
• Structural types such as PayramAPI and PayramInstance help with dependency injection or mocking in tests.
• Request/response types live under sdk/types/public if you need direct imports—PaymentRequest is available for getPaymentRequest responses.

Need Help?

• Run yarn test to execute the SDK’s unit and contract tests if you contribute back.
• Open an issue or pull request in the Payram SDK repository when you hit bugs or need enhancements.

Q: How do I test webhook handlers locally?

A: Use the provided adapters with a mocked request/response object. For integration tests, rely on the fixtures bundled under tests/helpers/ which demonstrates how to drive Prism and assert webhook behavior.

Q: What happens when a request times out?

A: The SDK races the request with withTimeout. On expiry, it aborts the underlying fetch, marks the resulting PayramSDKError with isTimeout = true, and respects retry policies.