Merchant API v1
Add escrow to your checkout
Let customers who don't know your brand yet buy with confidence. Their money is held until they receive the order, and your store stays in sync through signed webhooks.
POST /api/v1/checkout/sessions
Authorization: Bearer sce_…
Idempotency-Key: order-1001
{ "title": "Order #1001", "amount": "149.99",
"external_reference": "1001" }201 Created
{ "id": "cs_5b1e0c9a7d3f4e2a1b6c8d0e",
"object": "checkout.session",
"status": "OPEN",
"url": "https://smartcontractsescrow.net/checkout/Zt4…" }Choose how you integrate
WooCommerce
Install the plugin, paste two secrets, done. Orders update themselves from webhooks.
Shopify
A small bridge app creates the escrow link from order webhooks and marks orders paid.
Your own site
Any stack that can make an HTTPS request. Use the Node SDK or call the API directly.
Five-minute quickstart
Base URL https://smartcontractsescrow.net/api/v1. Read core concepts first if you're new to escrow.
1. Get your keys
Complete seller onboarding, then open Seller dashboard → Integrations:
- Create an API key. Copy the
sce_…secret: it is shown once. - Add a webhook endpoint (public HTTPS). Copy its
whsec_…signing secret.
2. Create a checkout session from your server
curl https://smartcontractsescrow.net/api/v1/checkout/sessions \
-H "Authorization: Bearer $SCE_API_KEY" \
-H "Idempotency-Key: order-1001" \
-H "Content-Type: application/json" \
-d '{
"title": "Order #1001",
"amount": "149.99",
"external_reference": "1001",
"customer_email": "buyer@example.com",
"line_items": [{"name": "Canon EOS R50", "quantity": 1, "unit_amount": "149.99"}],
"success_url": "https://shop.example.com/thank-you/1001",
"cancel_url": "https://shop.example.com/cart"
}'
3. Redirect the customer to the session url
They sign in, review the order and fees, and pay with mobile money, card or bank.
4. Handle webhooks
Ship when you receive escrow.funded, then submit the milestone
with tracking details. Mark the order complete on escrow.completed.
Always verify the signature.
Built for production
Server-side keys
Bearer API keys, stored hashed. Revoke one without touching the others.
Idempotent writes
Send an Idempotency-Key and retry safely after a timeout.
Signed webhooks
HMAC-SHA256 with timestamps, so replays and forgeries are rejected.
Retries for three days
At-least-once delivery with backoff, plus an events feed to reconcile.
Buyer protection built in
Funds are held on a double-entry ledger until the buyer approves.
OpenAPI 3.1
Import into Postman or generate a client in your language.