Authentication & Base URL
All sandbox requests are routed over secure HTTPS connection to the sandbox endpoint:
https://api.paymentsafe.business/v1
Sandbox Base
Pass your secret API key (`sk_sandbox_...`) inside the HTTP `Authorization` header as a Bearer token:
Authorization: Bearer sk_sandbox_77c29be01ffb43aa9f7478da25ab8a4c
Content-Type: application/json
⚠️ Security Warning: Never expose your secret API keys in client-side script tags or public Git repositories.
Create Escrow Vault Draft
POST /escrows
Initiates a new escrow contract draft. Call this on your backend when a buyer triggers checkout.
Request JSON Payload:
{
"merchantId": "cli_55f9a62b",
"itemTitle": "Oraimo Smart Watch ES-1",
"amount": 350.00,
"currency": "GHS",
"buyerEmail": "buyer@example.com",
"sellerPhone": "+233240001111",
"inspectionDays": 3,
"tradeNature": "local"
}
💡 B2B Cargo Shipments: For international cargo logistics, set "tradeNature": "cargo" and append logistics identifiers like "cargoShippingLine", "containerNum", and "blNum" (Bill of Lading).
Response JSON Payload (201 Created):
{
"id": "tx_88f910ab",
"status": "CREATED",
"escrowFee": 5.25,
"totalDue": 355.25,
"createdAt": "2026-06-20T09:30:15Z"
}
Retrieve Escrow Status
GET /escrows/:id
Query the vault to inspect whether the contract has been paid, completed, or disputed.
Response JSON Payload (200 OK):
{
"id": "tx_88f910ab",
"status": "FUNDED",
"amount": 350.00,
"payoutStatus": "AWAITING_DELIVERY",
"fundedAt": "2026-06-20T09:32:04Z"
}
Escrow Status Definitions:
| Status Value |
Event Trigger / Meaning |
| CREATED |
Contract draft generated, awaiting payment from the buyer. |
| FUNDED |
Buyer has completed checkout. Money is locked securely in the escrow vault. |
| COMPLETED |
Buyer approved delivery. Vault unlocked and funds settled to the seller. |
| DISPUTED |
Delivery inspection failed. Contract locked and flagged for mediation. |
Webhooks & Event Notifications
Webhooks are outbound HTTP POST callbacks that notify your backend in real-time when an escrow payment is funded, completed, or disputed.
Configure your endpoint URL in the API Keys & Webhooks sub-tab, and select which events you wish to subscribe to. Your API must return an HTTP status code 200 OK to acknowledge receipt of the webhook.
Webhook Trigger Events
| Event ID |
Description |
| escrow.created |
Fires when a new escrow contract draft is generated. |
| escrow.funded |
Fires when the buyer pays the deposit successfully. Dispatch goods now! |
| escrow.completed |
Fires when funds are released and settled. Safe to close order. |
| escrow.disputed |
Fires when the buyer files a dispute. Stop delivery/logistics if possible. |
Sample Webhook Callback Payload
Outbound JSON schema sent via POST to your target webhook endpoint:
{
"event": "escrow.funded",
"timestamp": 1781948408,
"data": {
"id": "tx_88f910ab",
"merchantId": "cli_55f9a62b",
"itemTitle": "Oraimo Smart Watch ES-1",
"amount": 350.00,
"currency": "GHS",
"status": "FUNDED",
"buyerEmail": "buyer@example.com",
"escrowFee": 5.25,
"totalDue": 355.25
}
}
Webhook Localhost Testing
If developing your integration locally (e.g. at http://localhost:3000), PaymentSafe cannot reach your machine. Use a secure tunnel generator like ngrok to forward traffic:
- Download and install ngrok.
-
Run the tunnel forwarder in your terminal:
ngrok http 3000
- Copy the public HTTPS address generated (e.g.
https://abcd-12-34.ngrok-free.app).
- Append your local endpoint path (e.g.
/webhooks) and paste it into the Webhook Target URL input in the developer console.
Alternative Escrow Triggering Mechanisms
Beyond custom REST API checkouts, PaymentSafe supports direct integration with various customer-facing channels:
Chatbot Triggers (WhatsApp & Telegram)
Text the PaymentSafe Bot directly (e.g., /escrow @seller 350 GHS "Watch"). The bot creates the draft via API and sends back the Paystack checkout link.
Offline USSD Gateway (*224#)
Dial the shortcode on any feature phone. Follow simple numeric menus to prompt mobile money (MoMo STK Push) checkouts directly on the buyer's phone without data connection.
QR Code "Protected Checkouts"
Scan a product QR code at physical handover hubs. Instantly open pre-filled agreement checkout pages to lock funds before accepting handoff.
Carrier & Logistics Webhooks
Secure trade agreements automatically when a shipping line registers the cargo Bill of Lading (B/L) or a dispatcher picks up local deliveries.
Email Invoice Parser
Importers forward B2B cargo invoices directly to bills@paymentsafe.business. Our engine parses the parameters and drafts the escrow agreement automatically.
