Marketplace Escrow API v1

Secure Escrow for Your Marketplace

Integrate Posteering's battle-tested escrow infrastructure into your platform in under an hour. Protect buyers, guarantee sellers, and earn trust — without building payment infrastructure from scratch.

🇳🇬 Nigeria-first ⚡ REST API 🔒 Paystack powered 🏦 Auto bank payout 📡 Webhooks 2.5% fee

How It Works

Your platform creates an escrow deal via API. The buyer pays via a Paystack payment link. Funds are held securely until your platform confirms delivery and releases payment to the seller — who receives an automatic bank transfer.

✅

The entire flow is API-driven. You control the UX on your platform — Posteering handles the money, compliance, and payouts.

Base URL

https://api.posteering.com/api/v1

Quickstart

Get a deal live in 5 minutes. Contact dev@posteering.com to get your API key.

Step 1 — Create a Deal

cURL

curl -X POST https://api.posteering.com/api/v1/marketplace/deals \
  -H "X-Api-Key: pst_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "partnerDealRef": "ORD-12345",
    "title": "iPhone 15 Pro Max 256GB",
    "amount": 45000000,
    "buyerEmail": "buyer@email.com",
    "buyerName": "John Doe",
    "sellerBankName": "Guaranty Trust Bank",
    "sellerAccountNumber": "0123456789",
    "sellerAccountName": "Jane Smith"
  }'

Step 2 — Redirect Buyer to Payment

The response includes a payment.authorizationUrl. Redirect your buyer there or use the accessCode with Paystack inline popup on your frontend.

Response

{
  "dealRef": "MPD-MMFYGGZ8-D8FA58",
  "status": "created",
  "amount": 45000000,
  "feeAmount": 1125000,
  "totalCharge": 46125000,
  "totalChargeNaira": "₦461,250.00",
  "sellerPayoutNaira": "₦450,000.00",
  "payment": {
    "authorizationUrl": "https://checkout.paystack.com/xxxx",
    "accessCode": "xxxx",
    "reference": "MPD-1234567890-abc123"
  },
  "expiresAt": "2026-03-08T06:41:30.138Z"
}

Step 3 — Verify Payment (via Webhook or Manual)

cURL

curl -X POST https://api.posteering.com/api/v1/marketplace/deals/MPD-MMFYGGZ8-D8FA58/verify \
  -H "X-Api-Key: pst_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"paymentReference": "MPD-1234567890-abc123"}'

Step 4 — Mark as Delivered

cURL

curl -X POST https://api.posteering.com/api/v1/marketplace/deals/MPD-MMFYGGZ8-D8FA58/deliver \
  -H "X-Api-Key: pst_live_your_key_here"

Step 5 — Release Funds to Seller

cURL

curl -X POST https://api.posteering.com/api/v1/marketplace/deals/MPD-MMFYGGZ8-D8FA58/release \
  -H "X-Api-Key: pst_live_your_key_here"

💸

Seller receives an automatic Paystack bank transfer to the account number you provided at deal creation. No manual payout required.

Authentication

All API requests require your partner API key passed in the X-Api-Key header.

Header

X-Api-Key: pst_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️

Your API key is shown only once at registration. Store it securely — in an environment variable, never in client-side code or version control.

API keys start with pst_live_ and are 56 characters long. Contact dev@posteering.com to register your platform and receive your key.

Deal Lifecycle

created

Deal created, awaiting payment

funded

Payment verified, funds in escrow

delivered

Seller marked as delivered

completed

Funds released, seller paid

A deal can also move to cancelled from the created state if payment was never made.

Endpoints

POST /marketplace/deals Create an escrow deal

Creates a new escrow deal and returns a Paystack payment URL for the buyer.

Request Body

Field	Type	Required	Description
`partnerDealRef`	string	required	Your internal order/deal reference. Must be unique per partner.
`title`	string	required	Description of what is being sold (max 255 chars)
`amount`	integer	required	Amount in kobo (₦1 = 100 kobo). Minimum: 100000 (₦1,000)
`buyerEmail`	string	required	Buyer's email address — used for Paystack payment
`buyerName`	string	optional	Buyer's full name
`buyerPhone`	string	optional	Buyer's phone number
`sellerEmail`	string	optional	Seller's email (for notifications)
`sellerName`	string	optional	Seller's full name
`sellerBankName`	string	optional*	Seller's bank name (required for auto payout)
`sellerAccountNumber`	string	optional*	Seller's account number (required for auto payout)
`sellerAccountName`	string	optional*	Seller's account name (required for auto payout)
`description`	string	optional	Detailed description of the item/service
`metadata`	object	optional	Any additional data you want to store with the deal

ℹ️

*Seller bank details are optional at deal creation but required for automatic payout on release. If not provided, you will need to handle seller payment manually.

GET /marketplace/deals List your deals

Query Parameters

Parameter	Type	Description
`status`	string	Filter by: created, funded, delivered, completed, cancelled
`page`	integer	Page number (default: 1)
`limit`	integer	Results per page (default: 20, max: 100)

GET /marketplace/deals/:ref Get a single deal

Use the dealRef returned at deal creation (e.g. MPD-MMFYGGZ8-D8FA58).

POST /marketplace/deals/:ref/verify Verify payment and fund escrow

Call this after the buyer completes payment on Paystack. Pass the payment reference to verify and move the deal to funded.

Field	Type	Description
`paymentReference`	string	required — Paystack transaction reference

POST /marketplace/deals/:ref/deliver Mark deal as delivered

Call this when the seller has shipped/delivered the goods or service. Moves deal to delivered. Optional body:

Field	Type	Description
`note`	string	Optional delivery note or tracking info

POST /marketplace/deals/:ref/release Release funds to seller

Releases escrowed funds to the seller. Triggers automatic Paystack bank transfer if seller bank details were provided. Deal moves to completed.

⚠️

This action is irreversible. Ensure the buyer has confirmed receipt before calling this endpoint.

POST /marketplace/deals/:ref/cancel Cancel an unfunded deal

Cancels a deal that has not yet been funded. Cannot cancel a deal that has already received payment — contact support for refunds on funded deals.

GET /marketplace/account Get your partner account stats

Returns your partner profile including total deals processed, total volume, and account status.

Webhooks

Posteering sends HTTP POST requests to your webhookUrl when deal status changes. Register your webhook URL when getting your API key.

Events

deal.fundedPayment verified — funds held in escrow

deal.deliveredSeller marked deal as delivered

deal.completedFunds released — seller payout initiated

deal.cancelledDeal cancelled before funding

Verifying Webhook Signatures

Every webhook includes an X-Posteering-Signature header. Verify it to ensure the request came from Posteering.

Node.js

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return expected === signature;
}

// In your Express handler:
app.post('/webhooks/posteering', express.raw({type: 'application/json'}), (req, res) => {
  const sig = req.headers['x-posteering-signature'];
  if (!verifyWebhook(req.body, sig, process.env.POSTEERING_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  const event = JSON.parse(req.body);
  console.log('Event:', event.event, event.data.dealRef);
  res.status(200).send('OK');
});

Webhook Payload

JSON

{
  "event": "deal.funded",
  "timestamp": "2026-03-07T08:00:00.000Z",
  "data": {
    "dealRef": "MPD-MMFYGGZ8-D8FA58",
    "partnerDealRef": "ORD-12345",
    "status": "funded",
    "amount": 45000000,
    "totalCharge": 46125000,
    "amountNaira": "₦450,000.00",
    "fundedAt": "2026-03-07T08:00:00.000Z"
  }
}

Fee Model

Item	Value
Escrow fee	2.5% of deal amount
Who pays	Buyer (added on top of deal amount)
Seller receives	100% of the deal amount
Example — ₦450,000 deal	Buyer pays ₦461,250 \| Fee: ₦11,250 \| Seller gets ₦450,000
Minimum deal amount	₦1,000 (100,000 kobo)
Payout method	Automatic Paystack bank transfer

Error Codes

Status	Code	Meaning
400	Bad Request	Invalid request body or deal already exists with same partnerDealRef
401	Unauthorized	Missing or invalid X-Api-Key header
403	Forbidden	Deal does not belong to your account
404	Not Found	Deal reference not found
409	Conflict	Duplicate partnerDealRef for your account
500	Server Error	Unexpected error — contact support

All errors return JSON: {"statusCode": 400, "message": "Descriptive error message"}

Testing

Use Paystack test cards to simulate payments in development. No real money is charged.

Field	Value
Card Number	`4084 0840 8408 4081`
Expiry	Any future date
CVV	`408`
OTP	`123456`
PIN	`0000`

ℹ️

Test deals are clearly marked in your account. Contact dev@posteering.com to switch to live mode when you are ready to process real transactions.

Support

Technical integration support: dev@posteering.com
Business enquiries: hello@posteering.com