PaymentSafe API

What is PaymentSafe?

PaymentSafe is an escrow service for African peer-to-peer marketplaces. When a buyer and seller agree on a deal, the buyer pays into a secure vault. Funds are held safely until the buyer confirms delivery — then the seller is paid. Neither party can be scammed.

PaymentSafe is not a payment gateway — it sits on top of Paystack and adds the escrow trust layer. Your app collects buyer and seller phone numbers, creates an escrow via the API, and PaymentSafe handles the rest.

Create your first escrow in 2 minutes

Step 1 — Get an API key

Sign up at paymentsafe.business → Developer Portal → My Apps → create a new app. You receive a sandbox key (sk_sandbox_...) immediately.

Step 2 — Create an escrow

# Create a GHS 6,500 escrow for an iPhone 14
curl -X POST "https://api.paymentsafe.business/v1/transactions" \
  -H "Authorization: Bearer sk_sandbox_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "iPhone 14 Pro Max",
    "price": 6500,
    "currency": "GHS",
    "buyerPhone": "+233540000001",
    "sellerPhone": "+233244000002",
    "inspectionDays": 3
  }'

Step 3 — Response

{
  "id": "tx-api-1234567890-abc123",
  "title": "iPhone 14 Pro Max",
  "status": "CREATED",
  "currency": "GHS",
  "price": 6500,
  "fee": 195,
  "sandbox": true,
  "verificationUrl": "https://paymentsafe.business/verify/tx-api-1234567890-abc123",
  "createdAt": "2026-07-07T12:00:00.000Z"
}

Share the verificationUrl with both buyer and seller so they can track the deal in real time.

API Keys

All authenticated requests require an Authorization header:

Authorization: Bearer sk_sandbox_your_key_here

Sandbox vs Live

How to get your Live API Keys

When you are ready to go to production, you need two keys: a public key (pk_live_...) for your frontend, and a secret key (sk_live_...) for your backend. Here is the exact step-by-step process to obtain them from the portal.

1

Go to paymentsafe.business and click “Sign In”

Open paymentsafe.business in your browser. Click the “Sign In” button in the top-right corner of the navigation bar.

2

Enter your credentials in the Sign In modal

A sign-in modal will appear. Enter your developer email address and password, then click “Sign In”. If you don’t have an account yet, click “Sign Up” to register a free developer account.

3

Click “API Portal” in the top navigation

Once logged in, look for the “API Portal” tab in the top navigation bar and click it. This is the developer hub where all your API credentials and settings live.

4

Click “Keys & Webhooks” in the sidebar

In the Developer Portal sidebar under Developer Tools, click “Keys & Webhooks”. You will land on the API credentials page in Test Mode by default — showing your sandbox keys (pk_test_... / sk_sandbox_...).

5

Toggle to “Live Mode”

Click the “Live Mode” toggle at the top of the page. You will see a confirmation message: “Switched Developer Portal to Production (live) mode.”

⚠️

Live keys charge real money through Paystack. Make sure your integration is fully tested in Sandbox before switching.

6

Copy your live keys and store them securely

Your live credentials are now visible. Click the “Copy” button next to each key and store them as follows:

🌐 Public Key — Frontend safe

pk_live_...

Add to .env.local as PAYMENTSAFE_PUBLIC_KEY

🔒 Secret Key — Backend only

sk_live_...

Store in Firebase Secrets via CLI — never in source code

.env.local (public key only)

PAYMENTSAFE_PUBLIC_KEY=pk_live_your_key_here

Firebase CLI (secret key — run once)

firebase functions:secrets:set PAYMENTSAFE_SECRET_KEY
# When prompted, paste your sk_live_... key and press Enter

🔐

Your .env.local is already in .gitignore — it will never be committed. The secret key stored via Firebase Secrets is encrypted at rest and only injected into Cloud Functions at runtime.

Base URL & Headers

https://api.paymentsafe.business/v1

Authorization: Bearer <your_api_key>
Content-Type: application/json

Transactions

Exchange Rates

{ "USD_GHS": 15.20, "EUR_GHS": 16.50, "source": "cache" }

Health Check

{ "status": "ok", "service": "PaymentSafe API", "version": "1.0" }

Errors

Rate Limits

100 requests per hour per API key on the free plan. Window resets every 60 minutes. Contact hello@paymentsafe.business to discuss higher limits.

Installation

npm install paymentsafe-js
# or
yarn add paymentsafe-js

Usage

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

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

// Create escrow
const txn = await ps.transactions.create({
  title: 'iPhone 14 Pro Max',
  price: 6500,
  currency: 'GHS',
  buyerPhone: '+233540000001',
  sellerPhone: '+233244000002'
});

console.log(txn.verificationUrl); // share with buyer & seller

// Other methods
await ps.transactions.get('tx-api-xxx');
await ps.transactions.confirmDelivery('tx-api-xxx');
await ps.transactions.release('tx-api-xxx');
await ps.transactions.dispute('tx-api-xxx', 'Item not as described');
await ps.rates.get();

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

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

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

Webhook Verification

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

app.post('/webhooks/escrow', express.raw({ type: 'application/json' }), (req, res) => {
  const event = verifyWebhook(
    req.body,
    req.headers['x-paymentsafe-signature'],
    process.env.PAYMENTSAFE_WEBHOOK_SECRET
  );

  if (event.type === 'escrow.funded') {
    // Safe to ship — payment is secured in escrow
  }
  res.sendStatus(200);
});

PaymentSafe for AI IDEs

The paymentsafe-mcp package is a Model Context Protocol (MCP) server that lets AI coding assistants create and manage escrow transactions using natural language — no API boilerplate required.

IDE Setup

All IDEs use the same JSON config block:

{
  "mcpServers": {
    "paymentsafe": {
      "command": "npx",
      "args": ["-y", "paymentsafe-mcp"],
      "env": {
        "PAYMENTSAFE_API_KEY": "sk_sandbox_your_key_here"
      }
    }
  }
}

Full per-IDE instructions: npmjs.com/package/paymentsafe-mcp

Available MCP Tools

Transaction Statuses

Webhook Events

PaymentSafe sends a signed POST to your webhookUrl on every status change. Retried up to 5 times with exponential backoff.

// Example payload
{
  "event": "escrow.funded",
  "timestamp": 1751886000,
  "data": {
    "id": "tx-api-1234567890-abc123",
    "status": "FUNDED",
    "currency": "GHS",
    "price": 6500,
    "fee": 195,
    "sandbox": false
  }
}

Signature header: x-paymentsafe-signature (sha256=HMAC hex)

Currencies & Countries

Payment methods (via Paystack): Mobile Money (MTN, Vodafone, AirtelTigo), Debit/Credit Cards (Visa, Mastercard), Bank Transfer, USSD. No smartphone required for USSD access.

Fees & Pricing

Common Setup Issues

Running into a problem? These are the most frequent issues developers encounter when integrating PaymentSafe.

firebase deploy --only functions