Getting started with the PayRam TypeScript / JavaScript SDK

1. Install and initialise

The official SDK is a TypeScript library for your backend. You can use it from JavaScript projects too.

npm install payram
# or
yarn add payram
pnpm add payram

You need two things: a project API key and a base URL. The base URL is the address you use to open the dashboard, shown under Settings → Site URL. For PayRamHost merchants it is the address of the dashboard. The official documentation is worded for self-hosted servers. The principle is the same for a hosted service: just use your dashboard address as the base URL.

import { Payram } from 'payram';

const payram = new Payram({
  apiKey: process.env.PAYRAM_API_KEY!,     // required
  baseUrl: process.env.PAYRAM_BASE_URL!,   // required, for example https://pay.payramhost.com
  config: {
    timeoutMs: 10_000,   // optional: request timeout
    maxRetries: 2,       // optional: maximum retries
    retryPolicy: 'safe', // optional: retry policy
  },
});

Keep the key and address in environment variables, not in your repository. For the defaults of each config option, see the official documentation.

2. Create a payment

const checkout = await payram.payments.initiatePayment({
  customerEmail: 'customer@example.com',
  customerId: 'cust_123',
  amountInUSD: 49.99,
});

console.log(checkout.reference_id); // unique ID of the payment: store it with the order
console.log(checkout.url);          // redirect the customer here to pay

The three required fields are the customer's email, the customer ID and the amount in US dollars. The returned url is a ready-made payment page and reference_id is used later for lookups and reconciliation. All fields are described in the API integration guide.

3. Check payment status

const payment = await payram.payments.getPaymentRequest(checkout.reference_id);
console.log(payment.paymentState); // OPEN / FILLED / PARTIALLY_FILLED / OVER_FILLED / CANCELLED

What each state means and how to handle it is in payment statuses.

The SDK also has payout methods (payouts.createPayout and payouts.getPayoutById). Payouts involve approvals and limits, and whether they are enabled depends on your dashboard. The flow is covered in refunds and payouts.

4. Receive webhooks

The SDK provides ready-made handlers for common frameworks: Express, Fastify, and the Next.js App Router and Pages Router. They check the request header, parse and validate the payload, and send back the right response so PayRam knows you received it.

import express from 'express';
import { Payram } from 'payram';

const app = express();
const payram = new Payram({
  apiKey: process.env.PAYRAM_API_KEY!,
  baseUrl: process.env.PAYRAM_BASE_URL!,
});

app.post(
  '/payram/webhook',
  payram.webhooks.expressWebhook(async (payload, req) => {
    // Handle the event here, and remember to make it idempotent
    console.log('PayRam event:', payload.reference_id);
  }),
);

app.listen(3000);

For Fastify use fastifyWebhook and for the Next.js App Router use nextAppRouterWebhook. Usage is the same: pass an async handler.

5. Add signature verification

In the official documentation the SDK's handlers check the API-Key header. The webhook documentation, however, recommends X-Payram-Signature: an HMAC-SHA256 of the raw request body keyed with the project API key. The signature also proves the body was not altered.

So if you want signature verification, skip the SDK's webhook handlers and write your own: take the raw bytes, verify them as shown in the webhook guide, then handle the event. Keep using the rest of the SDK (creating payments and checking status) as usual.

6. FAQ

Can I use the SDK in browser front-end code?

No, and you should not. It needs your API key, and the key must stay on your server. The front end only sends the customer to the url that your backend returns.

Can I use it without TypeScript?

Yes. Call the REST endpoints directly. The API integration guide has curl, Node.js and Python examples.

What if my account has several projects?

Each project has its own API key. Create one client instance per project, each with its own key. See multiple projects.

Related reading

• Create payments via API: Add crypto payments to your own site with the PayRam API: create a payment and get a payment link, send the customer to the payment page, confirm receipt with webhooks and the status endpoint, and reconcile by order number. With curl, Node.js and Python examples.
• Webhook guide: How to receive PayRam webhooks: register an endpoint, verify X-Payram-Signature, understand retry rules and payment states, handle duplicates, with Node.js and Python examples.
• Payment statuses: What PayRam's five payment statuses mean, how to handle underpaid (PARTIALLY_FILLED), overpaid (OVER_FILLED) and expired (CANCELLED) payments, and how to keep your order status in sync using webhooks and the status endpoint.