paymentsafe-js

Official JavaScript / TypeScript SDK for PaymentSafe — secure escrow payments for African marketplaces.

PaymentSafe is a secure escrow payment platform built for African peer-to-peer marketplaces. Buyers pay into escrow, funds are held safely, and sellers only get paid after delivery is confirmed — protecting both sides of every deal.

Table of Contents

• Installation
• Quick Start
• API Reference
  • Transactions
  • Rates
  • Webhooks
• TypeScript Support
• Transaction Statuses
• Supported Countries & Currencies
• Error Handling
• Related Packages
• Support

Installation

npm install paymentsafe-js

yarn add paymentsafe-js

Quick Start

const { PaymentSafe } = require('paymentsafe-js');

const ps = new PaymentSafe({ apiKey: 'sk_sandbox_your_key_here' });

// Create a secure escrow transaction
const deal = await ps.transactions.create({
  title: 'iPhone 14 Pro Max',
  price: 6500,
  currency: 'GHS',
  buyerPhone: '+233540000001',
  sellerPhone: '+233244000002',
  inspectionDays: 3,
  description: 'Used, excellent condition, with box'
});

console.log(deal.id);              // tx-api-1234567890-abc123
console.log(deal.verificationUrl); // Share this link with buyer and seller

ES Modules / TypeScript:

import { PaymentSafe } from 'paymentsafe-js';

const ps = new PaymentSafe({ apiKey: process.env.PAYMENTSAFE_API_KEY! });

API Reference

Constructor

const ps = new PaymentSafe({
  apiKey: 'sk_sandbox_...',      // required
  environment: 'sandbox',        // 'sandbox' | 'live' (default: 'sandbox')
  baseUrl: 'https://...'         // optional override
});

Transactions

Create a transaction

const txn = await ps.transactions.create({
  title: 'MacBook Pro',          // required — item name
  price: 12000,                  // required — amount as a number
  currency: 'GHS',               // required — 'GHS' | 'USD' | 'EUR'
  buyerPhone: '+233540000001',   // required — international format
  sellerPhone: '+233244000002',  // required — international format
  inspectionDays: 3,             // optional — default 3 days
  description: 'M3 chip, 16GB'  // optional
});

Get a transaction

const txn = await ps.transactions.get('tx-api-1234567890-abc123');
console.log(txn.status); // 'CREATED' | 'FUNDED' | 'DELIVERED' | ...

List transactions

const { transactions, count } = await ps.transactions.list();
// Returns last 50 transactions for your API key

Confirm delivery

// Call after the buyer has received the item
const result = await ps.transactions.confirmDelivery('tx-api-xxx');
console.log(result.status); // 'DELIVERED'

Release funds to seller

// Call after delivery is confirmed — requires sk_* key
const result = await ps.transactions.release('tx-api-xxx');
console.log(result.status); // 'RELEASED'

Open a dispute

// Freezes funds and alerts PaymentSafe staff
const result = await ps.transactions.dispute('tx-api-xxx', 'Item not as described');
console.log(result.status); // 'DISPUTED'

Publicly verify a transaction (no API key needed)

// Safe to call from a public frontend — no secret exposed
const info = await ps.transactions.verify('tx-api-xxx');
console.log(info.verified); // true

Rates

const rates = await ps.rates.get();
console.log(rates.USD_GHS); // e.g. 14.85
console.log(rates.EUR_GHS); // e.g. 16.10

Webhooks

Verify incoming webhook signatures from PaymentSafe using HMAC-SHA512:

const { verifyWebhook } = require('paymentsafe-js/webhooks');

// Express
app.post('/webhooks/escrow', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = verifyWebhook(
      req.body,
      req.headers['x-paymentsafe-signature'],
      process.env.PAYMENTSAFE_WEBHOOK_SECRET
    );
  } catch (err) {
    return res.status(400).send('Webhook signature invalid');
  }

  switch (event.type) {
    case 'escrow.funded':
      // Safe to ship — payment is in escrow
      break;
    case 'escrow.delivered':
      // Buyer confirmed receipt — you can release funds
      break;
    case 'escrow.released':
      // Funds sent to seller
      break;
    case 'escrow.disputed':
      // Dispute opened — do not ship / hold refund
      break;
  }

  res.sendStatus(200);
});

Next.js App Router:

import { verifyWebhook } from 'paymentsafe-js/webhooks';

export async function POST(request: Request) {
  const body = await request.text();
  const event = verifyWebhook(
    body,
    request.headers.get('x-paymentsafe-signature')!,
    process.env.PAYMENTSAFE_WEBHOOK_SECRET!
  );
  return Response.json({ received: true });
}

TypeScript Support

Full TypeScript types are included. No @types/ package needed.

import { PaymentSafe, PaymentSafeError, Transaction, CreateTransactionInput } from 'paymentsafe-js';

const ps = new PaymentSafe({ apiKey: process.env.PAYMENTSAFE_API_KEY! });

const input: CreateTransactionInput = {
  title: 'Freelance website design',
  price: 800,
  currency: 'USD',
  buyerPhone: '+254712345678',  // Kenya
  sellerPhone: '+233244000001', // Ghana
};

try {
  const txn: Transaction = await ps.transactions.create(input);
} catch (err) {
  if (err instanceof PaymentSafeError) {
    console.error(err.code, err.status, err.message);
  }
}

Transaction Statuses

| Status | Meaning | |--------|---------| | CREATED | Transaction created, waiting for buyer to pay | | PART_FUNDED | Partial payment received | | FUNDED | Fully funded — seller can ship | | FULLY_FUNDED | All milestones funded | | SHIPPED | Seller has shipped the item | | DELIVERED | Buyer confirmed receipt | | RELEASED | Funds released to seller | | DISPUTED | Dispute opened — funds frozen | | REFUNDED | Funds returned to buyer |

Supported Countries & Currencies

| Currency | Code | Countries | |----------|------|-----------| | Ghanaian Cedi | GHS | Ghana | | US Dollar | USD | Nigeria, Kenya, Uganda, Tanzania, Rwanda, Zambia, Senegal, Ivory Coast, and more | | Euro | EUR | Cross-border and diaspora payments |

More local currencies coming soon.

Error Handling

All SDK methods throw PaymentSafeError on failure:

const { PaymentSafe, PaymentSafeError } = require('paymentsafe-js');

try {
  const txn = await ps.transactions.get('invalid-id');
} catch (err) {
  if (err instanceof PaymentSafeError) {
    console.log(err.message); // Human-readable message
    console.log(err.code);    // Machine-readable code, e.g. 'not_found'
    console.log(err.status);  // HTTP status code, e.g. 404
  }
}

Related Packages

| Package | Description | |---------|-------------| | paymentsafe-mcp | MCP server — use PaymentSafe from Cursor, Claude Desktop, Windsurf, VS Code Copilot |

Support

• Docs: https://paymentsafe.business/docs
• API keys: https://paymentsafe.business (Developer Portal)
• Email: [email protected]
• Issues: https://github.com/Transoft-Technologies/holdpayment/issues

Made with love by Transoft Technologies, Accra, Ghana