Web SDK (TypeScript / JavaScript)

The official PayKore SDK for Node.js. Provides typed methods for every API endpoint, automatic request signing, and a structured error class.

Installation

npm install @paykore/sdk
# or
yarn add @paykore/sdk

danger

This SDK is for server-side Node.js use only. Never import or bundle it into browser/frontend code, doing so would expose your secret API key to anyone who opens your site's developer tools.

Initialisation

import PayKore from '@paykore/sdk';

const paykore = new PayKore({
  apiKey: process.env.PAYKORE_SECRET_KEY!,
  environment: 'live', // or 'sandbox'
  timeout: 30_000, // optional, default 30s
});

Option	Required	Description
`apiKey`	Yes	Your secret key. Use `sk_live_` with `environment: 'live'`, or `sk_test_` with `environment: 'sandbox'`.
`environment`	Yes	`'live'` or `'sandbox'`. Must match your key's prefix, mismatches return `401 INVALID_API_KEY`.
`timeout`	No	Request timeout in milliseconds. Defaults to 30,000 (30s).

To develop against sandbox, switch both values together:

const paykore = new PayKore({
  apiKey: process.env.PAYKORE_SANDBOX_KEY!, // sk_test_...
  environment: 'sandbox',
});

Wallets

// Create a wallet
const wallet: Wallet = await paykore.wallets.create({
  userRef: 'user_123',
  currency: 'NGN',
});

// Fetch a wallet
const wallet: Wallet = await paykore.wallets.get('wlt_9f3kA2mXpQ');

// List a wallet's transaction history
const page: PaginatedList<Transaction> = await paykore.wallets.listTransactions(
  'wlt_9f3kA2mXpQ',
  { type: 'p2p_transfer', limit: 20 }
);

Method	Returns
`paykore.wallets.create(params)`	`Promise<Wallet>`
`paykore.wallets.get(id)`	`Promise<Wallet>`
`paykore.wallets.listTransactions(id, params)`	`Promise<PaginatedList<Transaction>>`

See the Wallets guide for full field-level documentation.

Transfers

import { randomUUID } from 'crypto';

// P2P transfer: always pass an idempotency key
const transfer: Transaction = await paykore.transfers.p2p({
  sourceWalletId: 'wlt_9f3kA2mXpQ',
  destWalletId: 'wlt_3pRsT7uVwX',
  amountKobo: 500000,
  reference: 'order_789',
  idempotencyKey: randomUUID(),
});

// Bank transfer: requires a bankAccount object
const payout: Transaction = await paykore.transfers.bank({
  sourceWalletId: 'wlt_9f3kA2mXpQ',
  bankAccount: {
    bankCode: '058',
    accountNumber: '0123456789',
    accountName: 'ADEBAYO OLUWASEUN JAMES',
  },
  amountKobo: 1000000,
  reference: 'payout_456',
  idempotencyKey: randomUUID(),
});

Method	Returns
`paykore.transfers.p2p(params)`	`Promise<Transaction>`
`paykore.transfers.bank(params)`	`Promise<Transaction>`

See P2P Transfers and Bank Transfers for full guides, including async lifecycle for bank transfers.

Payments

// Create a QR payment intent (merchant side)
const intent = await paykore.payments.createQRIntent({
  merchantWalletId: 'wlt_mErChAnT456',
  amountKobo: 500000,
  reference: 'order_789',
});

// Pay a QR intent (payer side)
const payment = await paykore.payments.payQRIntent({
  intentId: intent.intentId,
  payerWalletId: 'wlt_9f3kA2mXpQ',
});

// Initiate a USSD payment
const ussdSession = await paykore.payments.initiateUSSD({
  payerWalletId: 'wlt_9f3kA2mXpQ',
  merchantWalletId: 'wlt_mErChAnT456',
  amountKobo: 500000,
  reference: 'order_789',
});

// Split payment
const splitTx = await paykore.payments.split({
  sourceWalletId: 'wlt_buYeR789',
  amountKobo: 1000000,
  reference: 'order_456',
  splitConfig: {
    merchantAccount: 'wlt_seller_123',
    platformFeePercent: 15.0,
    platformAccount: 'wlt_your_platform',
  },
});

Method	Returns
`paykore.payments.createQRIntent(params)`	`Promise<QRIntent>`
`paykore.payments.payQRIntent(params)`	`Promise<Transaction>`
`paykore.payments.initiateUSSD(params)`	`Promise<USSDSession>`
`paykore.payments.split(params)`	`Promise<Transaction>`

See QR Payments, USSD Payments, and Split Payments for full guides.

KYC

// Submit a BVN for verification
const kyc = await paykore.kyc.submitBVN({
  userRef: 'user_123',
  bvn: '22190000000',
});

// Check verification status
const status = await paykore.kyc.getStatus('user_123');
console.log(status.status); // "verified" | "processing" | "failed"

Method	Returns
`paykore.kyc.submitBVN(params)`	`Promise<KYCVerification>`
`paykore.kyc.getStatus(userRef)`	`Promise<KYCVerification>`

See the KYC Verification guide for verification thresholds and failure reasons.

Webhooks

// Register an endpoint
const endpoint = await paykore.webhooks.register({
  url: 'https://yourapp.com/webhooks/paykore',
  events: ['transaction.completed', 'transaction.failed'],
});

// List registered endpoints
const endpoints = await paykore.webhooks.list();

// Delete an endpoint
await paykore.webhooks.delete('wh_5rTuV2wXyZ');

Method	Returns
`paykore.webhooks.register(params)`	`Promise<WebhookEndpoint>`
`paykore.webhooks.list()`	`Promise<WebhookEndpoint[]>`
`paykore.webhooks.delete(id)`	`Promise<void>`

See the Webhooks Overview for delivery behaviour, and Verifying Signatures for handling incoming payloads, signature verification is a separate, manual step the SDK does not currently perform for you on the receiving end.

Error handling

All SDK methods throw a PayKoreError on failure. Catch it and branch on err.code:

import { PayKoreError } from '@paykore/sdk';

try {
  const transfer = await paykore.transfers.p2p({ /* ... */ });
} catch (err) {
  if (err instanceof PayKoreError) {
    switch (err.code) {
      case 'INSUFFICIENT_FUNDS':
        // handle: show the user their balance and the shortfall
        break;
      case 'WALLET_FROZEN':
        // handle: surface a support contact path
        break;
      default:
        // unexpected error, log for investigation
        logger.error('Unexpected paykore error', { code: err.code, requestId: err.requestId });
    }
  } else {
    throw err; // not a paykore error, rethrow
  }
}

PayKoreError exposes three properties you'll use constantly:

Property	Description
`err.code`	The paykore error code (e.g. `INSUFFICIENT_FUNDS`). Stable across SDK versions, branch on this, not on `err.message`.
`err.statusCode`	The underlying HTTP status code (e.g. `422`).
`err.requestId`	The `meta.request_id` value from the API response. Include this when escalating to PayKore support, it lets the team locate the exact request in logs.

TypeScript types

The SDK exports the following types from the package root, so you can import them directly without reaching into internal paths:

import type {
  Wallet,
  Transaction,
  FeeBreakdown,
  LedgerEntry,
  KYCVerification,
  WebhookEndpoint,
  PayKoreError,
} from '@paykore/sdk';

Type	Represents
`Wallet`	A user's wallet, including balance and NUBAN details.
`Transaction`	Any completed/processing/failed business event (transfer, payment, payout).
`FeeBreakdown`	The fee fields attached to a `Transaction`.
`LedgerEntry`	A single immutable debit/credit record underlying a transaction.
`KYCVerification`	The status and metadata of a BVN/NIN verification attempt.
`WebhookEndpoint`	A registered webhook URL and its subscribed events.
`PayKoreError`	The error class thrown by all SDK methods on failure.

SDK changelog

v1.0.0: Initial release. Covers wallets, P2P transfers, bank transfers, QR payments, USSD payments, split payments, KYC (BVN), and webhook management.

Next steps

React Native SDK → The mobile SDK, built on top of this package.
API Reference → The underlying REST endpoints this SDK wraps.

Installation​

Initialisation​

Wallets​

Transfers​

Payments​

KYC​

Webhooks​

Error handling​

TypeScript types​

SDK changelog​

Next steps​