@sensenpay/sdk

Official Node.js SDK for the SenSen Payment Gateway.

Installation

npm install @sensenpay/sdk

Quick Start

import { SenSenClient } from '@sensenpay/sdk';

const sensen = new SenSenClient({
  secretKey: 'sk_live_your_secret_key',
});

Create a Checkout Session

const session = await sensen.sessions.create({
  amount: 49.99,
  currency: 'SGD',
  orderId: 'order_123',
  description: 'Premium Plan',
  customerEmail: '[email protected]',
  successUrl: 'https://mysite.com/success',
  cancelUrl: 'https://mysite.com/cancel',
});

// Redirect your customer to:
console.log(session.checkoutUrl);

List Payments

const { data, pagination } = await sensen.payments.list({
  status: 'Succeeded',
  page: 1,
  limit: 20,
});

for (const payment of data) {
  console.log(`${payment.orderId}: ${payment.currency} ${payment.amount}`);
}

Get Payment Details

const payment = await sensen.payments.retrieve('pay_abc123');
console.log(payment.status); // 'Succeeded'
console.log(payment.refunds); // []
console.log(payment.disputes); // []

Refund a Payment

// Full refund
const refund = await sensen.refunds.create('pay_abc123');

// Partial refund
const refund = await sensen.refunds.create('pay_abc123', {
  amount: 10.00,
  reason: 'Customer request',
});

Check Balance

const balance = await sensen.balance.retrieve();
console.log(`Unsettled: ${balance.unsettledAmount}`);
console.log(`Pending payments: ${balance.unsettledCount}`);

Cancel a Session

await sensen.sessions.cancel('session_abc123');

Webhook Verification

Verify incoming webhooks from SenSen to ensure they're authentic:

import { verifyWebhookSignature } from '@sensenpay/sdk';

// Express.js example
app.post('/webhooks/sensen', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const event = verifyWebhookSignature(
      req.body.toString(),
      req.headers['x-sensen-signature'] as string,
      process.env.SENSEN_WEBHOOK_SECRET!,
    );

    switch (event.type) {
      case 'payment.succeeded':
        const { paymentId, amount, currency } = event.data;
        // Fulfill the order
        break;

      case 'payment.failed':
        // Notify customer
        break;

      case 'payment.refunded':
        // Update order status
        break;

      case 'payment.disputed':
        // Flag for review
        break;

      case 'settlement.completed':
        // Record settlement
        break;
    }

    res.sendStatus(200);
  } catch (err) {
    console.error('Webhook verification failed:', err);
    res.sendStatus(400);
  }
});

Webhook Event Types

| Event | Description | |-------|-------------| | payment.succeeded | Payment completed successfully | | payment.failed | Payment attempt failed | | payment.refunded | Refund issued on a payment | | payment.disputed | Chargeback/dispute opened | | settlement.completed | Batch settlement processed |

Webhook Headers

Every webhook includes these headers:

| Header | Description | |--------|-------------| | X-Sensen-Signature | HMAC-SHA256 signature for verification | | X-Sensen-Event-Id | Unique event ID (for deduplication) | | X-Sensen-Event-Type | Event type string |

Error Handling

try {
  const session = await sensen.sessions.create({ amount: 100, currency: 'SGD' });
} catch (err) {
  // err.status  - HTTP status code (401, 400, 500, etc.)
  // err.message - Human-readable error message
  // err.code    - Machine-readable error code (if available)
  console.error(`Error ${err.status}: ${err.message}`);
}

Configuration

const sensen = new SenSenClient({
  secretKey: 'sk_live_xxx',     // Required
  baseUrl: 'https://app.sensenpay.com', // Optional (default)
  timeout: 30000,                // Optional (default: 30s)
});

Test Mode

Use your test API key for development:

const sensen = new SenSenClient({
  secretKey: 'sk_test_your_test_key',
});

Test mode creates real checkout sessions but uses Stripe test mode for card payments and Sepolia testnet for stablecoin payments. No real money is moved.

Supported Payment Methods

| Mode | Methods | |------|---------| | Card | Visa, Mastercard, Amex, UnionPay | | E-Wallet | Alipay, WeChat Pay, PayNow | | Stablecoin | USDC, USDT (Ethereum, Polygon, Base) |

API Reference

Full API documentation is available in your SenSen merchant portal under API and SDK > Documentation.