Skip to main content
POST
/
escrow-create
Create an escrow
curl --request POST \
  --url https://aarwcjjzhlmkgdwrisyt.supabase.co/functions/v1/escrow-create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "category": "goods_products",
  "payer_role": "initiator",
  "title": "iPhone 15 Pro Max 256GB",
  "description": "Brand new, sealed in box. Delivery via courier.",
  "counterparty_phone": "+2348012345679",
  "amount": 500000
}
'
{
  "success": true,
  "status": 201,
  "data": {
    "escrow_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "invite_token": "f1e2d3c4-b5a6-7890-fedc-ba0987654321",
    "fee_breakdown": {
      "escrow_amount": 500000,
      "payer_fee": 7500,
      "vat": 562.5,
      "total_charge": 508062.5,
      "seller_fee": 7500,
      "seller_payout": 492500
    }
  }
}

Authorizations

​
Authorization
string
header
required

JWT access token obtained from /auth-verify (login context) or /auth-signup. Set the bearer_token environment variable in your API client to apply it globally.

Body

application/json
​
category
enum<string>
required

The type of escrow. Determines inspection period and display labels: goods_products → Buyer/Seller (1-day inspection), hiring → Client/Freelancer (manual release), auto_dealership → Buyer/Dealer (immediate on delivery), p2p_crypto → Sender/Receiver (immediate on approval).

Available options:
goods_products,
hiring,
auto_dealership,
p2p_crypto
​
payer_role
enum<string>
required

Who pays into the escrow. 'initiator' means the creator pays; 'counterparty' means the other party pays.

Available options:
initiator,
counterparty
​
title
string
required
Required string length: 1 - 200
Example:

"iPhone 15 Pro Max 256GB"

​
counterparty_phone
string
required
Pattern: ^(\+234[0-9]{10}|0[0-9]{10})$
Example:

"+2348012345679"

​
amount
number
required
Required range: x >= 0.01
Example:

500000

​
description
string
Maximum string length: 2000
Example:

"Brand new, sealed in box. Delivery via courier."

Response

Escrow created — fee breakdown and invite token returned

​
success
boolean
Example:

true

​
status
integer
Example:

201

​
data
object