YeboSafe API Routes

Base URL

Production: https://api.yebosafe.com/api

Authentication

API Key (Server-to-Server)

Authorization: Bearer sk_live_xxx

JWT Token (Dashboard)

Authorization: Bearer eyJhbGc...

---

Health Check

Method	Route	Description
GET	/health	Service health check

---

Public Routes

Escrow Lookup

Method	Route	Description
GET	/escrows/lookup/:code	Lookup escrow by completion code

Response:

{
  "success": true,
  "data": {
    "id": "clx...",
    "reference": "clx...",
    "amount": 100.00,
    "currency": "USD",
    "description": "Product purchase",
    "status": "PENDING",
    "createdAt": "2024-01-15T10:00:00Z",
    "merchantName": "ACME Store"
  }
}

---

Merchant Authentication

/auth

Method	Route	Description	Body
POST	/auth/register	Register merchant	{ name, email, password }
POST	/auth/login	Login	{ email, password }
POST	/auth/refresh	Refresh token	{ refreshToken }
GET	/auth/me	Get current merchant	-

---

Merchant Routes

/merchants

Method	Route	Description
GET	/merchants/me	Get merchant profile
PUT	/merchants/me	Update profile
PUT	/merchants/me/webhook	Update webhook URL
GET	/merchants/me/api-keys	List API keys
POST	/merchants/me/api-keys	Create API key
DELETE	/merchants/me/api-keys/:id	Revoke API key

---

Escrow Routes

/escrows

Method	Route	Description
GET	/escrows	List escrows
POST	/escrows	Create escrow
GET	/escrows/:id	Get escrow details
POST	/escrows/:id/accept	Accept escrow
POST	/escrows/:id/refuse	Refuse escrow
POST	/escrows/:id/complete	Complete with code
POST	/escrows/:id/dispute	Open dispute
POST	/escrows/:id/cancel	Cancel escrow

Create Escrow

POST /escrows

{
  "amount": 100.00,
  "currency": "USD",
  "description": "Product purchase",
  "payerName": "John Doe",
  "payerEmail": "john@example.com",
  "payerPhone": "+1234567890",
  "metadata": {
    "orderId": "ORD-123"
  },
  "webhookUrl": "https://your-app.com/webhook"
}

Response:

{
  "success": true,
  "data": {
    "id": "clx...",
    "reference": "clx...",
    "completionCode": "123456",
    "status": "PENDING",
    "amount": "100.00",
    "currency": "USD",
    ...
  }
}

List Escrows

GET /escrows?status=PENDING&page=1&limit=20

Query Parameters:

• status: PENDING | ACCEPTED | COMPLETED | REFUSED | DISPUTED | CANCELLED | REFUNDED
• page: Page number (default: 1)
• limit: Items per page (default: 20)

Accept Escrow

POST /escrows/:id/accept

No body required. Returns updated escrow.

Refuse Escrow

POST /escrows/:id/refuse

{
  "reason": "Unable to fulfill order"
}

Complete Escrow

POST /escrows/:id/complete

{
  "completionCode": "123456"
}

Dispute Escrow

POST /escrows/:id/dispute

{
  "reason": "Item not as described"
}

Cancel Escrow

POST /escrows/:id/cancel

{
  "reason": "Customer requested cancellation"
}

---

Wallet Routes

/wallet

Method	Route	Description
GET	/wallet/balance	Get balance
GET	/wallet/transactions	List transactions

Balance Response:

{
  "success": true,
  "data": {
    "balance": 1500.00,
    "currency": "USD"
  }
}

---

Admin Routes

/admin

Method	Route	Description
GET	/admin/stats	Platform statistics
GET	/admin/escrows	All escrows (paginated)
GET	/admin/merchants	All merchants

---

Error Responses

{
  "success": false,
  "error": {
    "code": "ESCROW_NOT_FOUND",
    "message": "Escrow not found"
  }
}

Error Codes:

• INVALID_AMOUNT - Amount must be positive
• ESCROW_NOT_FOUND - Escrow doesn't exist
• ESCROW_NOT_PENDING - Escrow not in pending state
• ESCROW_NOT_ACCEPTED - Must be accepted before completion
• ALREADY_COMPLETED - Escrow already completed
• ALREADY_DISPUTED - Dispute already opened
• ALREADY_CANCELLED - Already cancelled
• ESCROW_ALREADY_CLOSED - Cannot modify closed escrow
• INVALID_CODE - Completion code not found