Skip to main content

Node.js SDK

Use the official Node.js SDK when your server uses Node.js or TypeScript and you are integrating virtual accounts, virtual cards, or bill payments. It is a server-side library: never expose its key in a browser or mobile application.

What the SDK supports​

ProductSDK supportStart here
Virtual accountsStatic, dynamic, payment confirmation, sandbox simulationThis guide
Virtual cardsCreate, fund, withdraw, controls, and transactionsThis guide
Bill paymentsAirtime, data, electricity, cable, and moreThis guide
Transfers and payoutsNot yet exposed by this SDKREST payout guide

Install and configure​

npm install @payscribe/sdk

Store a dashboard-issued sandbox API key in your server environment:

export PAYSCRIBE_API_KEY="ps_pk_test_your_api_key"

Create one client for your application service:

import {Payscribe} from '@payscribe/sdk';

export const payscribe = new Payscribe({
  // `secretKey` is the SDK option name. Supply the dashboard-issued API key.
  secretKey: process.env.PAYSCRIBE_API_KEY!,
  environment: 'sandbox',
});

Use production only after completing the go-live checklist. Keep the value in a secret manager, not in source control.

First integration: create a dynamic virtual account​

A dynamic account is a useful first integration because the SDK creates a customer payment instruction in one call. Persist your own order ID as the reference before making this request.

const account = await payscribe.virtualAccounts.createDynamic({
  reference: 'order_10021',
  amount: 2500,
  amountType: 'EXACT',
  description: 'Payment for order_10021',
  currency: 'NGN',
  expiresIn: {duration: 1, type: 'hours'},
  customer: {
    name: 'Ada Lovelace',
    email: 'ada@example.com',
    phone: '08099228833',
  },
});

// Persist only the fields your application needs, such as the account number,
// bank details, Payscribe ID, and your original reference.
console.log(account);

Do not mark the order paid from this response. Verify the signed event and reconcile the final transaction state using the Webhooks guide and Virtual accounts guide.

Cards​

Create a card only after you have a Payscribe customer ID. Use a durable, unique reference for each value-changing operation.

const card = await payscribe.virtualCards.create({
  customerId: 'cus_abc123',
  currency: 'USD',
  brand: 'VISA',
  amount: 50,
  type: 'virtual',
  reference: 'card_issue_order_10021',
});

await payscribe.virtualCards.topUp(card.id, {
  amount: 10,
  reference: 'card_topup_order_10021',
});

Treat the returned card ID as an internal identifier. Follow the Card issuance guide for safe handling of card data and confirmed-state reconciliation.

Bill payments​

Discover or validate a product before you vend it. Persist a unique reference and reconcile an uncertain outcome rather than submitting a second payment.

const plans = await payscribe.bills.data.lookup({
  network: 'mtn',
  category: 'sme',
});

const payment = await payscribe.bills.data.vend({
  network: 'mtn',
  plan: 'PSPLAN_177', // Use the plan returned by lookup().
  recipient: '08030000000',
  reference: 'data_order_10021',
});

console.log({plans, payment});

See Bill payments for the required validation and fulfilment flow.

Handle errors and webhooks​

The SDK throws PayscribeApiError for API failures. Log a safe correlation value such as your reference, response status, and transaction ID—never the authorization header or API key.

import {PayscribeApiError} from '@payscribe/sdk';

try {
  await payscribe.virtualAccounts.get('5031240100');
} catch (error) {
  if (error instanceof PayscribeApiError) {
    console.error({status: error.statusCode, message: error.message});
  }
  throw error;
}

For webhook verification, use the canonical Webhooks & Events reference. It documents the current signed headers, raw-body requirement, timestamp, event ID, and replay protection.

Continue​

Was this page helpful?

Report a docs issue →