Quick Start

This guide shows the minimal path: create an escrow, submit a deliverable, open a dispute, get a decision. No edge cases. No error handling. Just the golden path.

Prerequisites

  • API Key and Secret from your integrator account
  • Ability to send HMAC-signed HTTP requests

Step 1: Create an Escrow

POST
/v1/escrows
http 
POST /v1/escrows
Content-Type: application/json
X-Api-Key: your_api_key
X-Timestamp: 1735430400
X-Nonce: unique_nonce_123
X-Signature: hmac_sha256_signature

{
  "external_id": "order_12345",
  "currency": "USD",
  "total_amount": 50000,
  "milestones": [
    {
      "milestone_id": "ms_design",
      "amount": 20000,
      "deadline": "2025-02-01T00:00:00Z"
    },
    {
      "milestone_id": "ms_development",
      "amount": 30000,
      "deadline": "2025-03-01T00:00:00Z"
    }
  ]
}

Response (201):

json 
{
  "id": "esc_abc123",
  "external_id": "order_12345",
  "state": "CREATED",
  "currency": "USD",
  "total_amount": 50000,
  "milestones": [...],
  "created_at": "2025-01-15T10:00:00Z"
}

Step 2: Declare Payment Status

After funds are secured in your payment system:

POST
/v1/escrows/:id/payment-status
http 
POST /v1/escrows/esc_abc123/payment-status

{
  "external_payment_ref": "pi_stripe_xyz",
  "status": "FUNDS_HELD",
  "declared_at": "2025-01-15T10:30:00Z"
}

Response (200):

json 
{
  "status": "accepted",
  "current_state": "FUNDED"
}

Step 3: Submit a Deliverable

POST
/v1/escrows/:id/deliverable
http 
POST /v1/escrows/esc_abc123/deliverable

{
  "milestone_id": "ms_design",
  "reference": {
    "type": "external_reference",
    "provider": "github",
    "uri": "https://github.com/org/repo/pull/42",
    "content_hash": "sha256:e3b0c44298fc1c149afbf4c8996fb924..."
  }
}

State transitions to DELIVERED.

Step 4: Open a Dispute

Client claims deliverable is incomplete:

POST
/v1/escrows/:id/dispute
http 
POST /v1/escrows/esc_abc123/dispute

{
  "reason_code": "DELIVERABLE_INCOMPLETE",
  "opened_by": {
    "actor_id": "usr_client_456",
    "actor_role": "client"
  }
}

Response (201):

json 
{
  "id": "dsp_def456",
  "escrow_id": "esc_abc123",
  "state": "OPEN",
  "reason_code": "DELIVERABLE_INCOMPLETE",
  "opened_by": { "actor_id": "usr_client_456", "actor_role": "client" },
  "created_at": "2025-01-20T14:00:00Z"
}

Step 5: Submit Evidence

Both parties submit evidence references:

POST
/v1/disputes/:id/evidence
http 
POST /v1/disputes/dsp_def456/evidence

{
  "submitted_by": {
    "actor_id": "usr_contractor_789",
    "actor_role": "contractor"
  },
  "reference": {
    "type": "external_reference",
    "provider": "google_drive",
    "uri": "https://drive.google.com/file/d/...",
    "content_hash": "sha256:..."
  }
}

Step 6: Lock Evidence & Get Recommendation

POST
/v1/disputes/:id/lock
http 
POST /v1/disputes/dsp_def456/lock
GET
/v1/disputes/:id/recommendation
http 
GET /v1/disputes/dsp_def456/recommendation

Response:

json 
{
  "recommendation": "SPLIT",
  "confidence": 0.72,
  "signals": ["late_delivery", "partial_completion"],
  "suggested_ratio": {
    "client": 0.4,
    "contractor": 0.6
  },
  "engine_version": "v1.0.0"
}

Step 7: Apply Decision

POST
/v1/disputes/:id/decision
http 
POST /v1/disputes/dsp_def456/decision

{
  "decision": "SPLIT",
  "final_ratio": {
    "client": 0.35,
    "contractor": 0.65
  },
  "justification": "Milestone delivered late but functional"
}

Response (200):

json 
{
  "status": "resolved",
  "outcome": "SPLIT",
  "payout": {
    "client": 17500,
    "contractor": 32500
  }
}

What Happens Next

A webhook is dispatched to your registered endpoint with the DISPUTE_RESOLVED event. You use those payout figures to execute transfers in your payment system.

We recommend. You enforce.
Next: Core Concepts →