9 API reference

Complete reference for the Stablix API. Base URL: https://api.stablix.xyz/api/v1

Authentication

API Key (Server-to-Server)

X-API-Key: sk_live_your_secret_key

JWT Token (Dashboard)

Authorization: Bearer your_jwt_token

Public Endpoints

No authentication required. Used for payment pages and buyer protection.

---

Response Format

All responses follow this structure:

{
  "success": true,
  "data": { ... },
  "message": "Optional message"
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid amount"
  }
}

Pagination

{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

---

Idempotency

For POST requests, include an idempotency key to prevent duplicate operations:

X-Idempotency-Key: unique_request_id_123

---

Invoices

One-time payments with escrow protection.

Create Invoice

Creates a draft invoice. Call /activate to generate deposit addresses.

POST /invoices

Auth: API Key

Headers:

X-API-Key: sk_live_xxx
X-Idempotency-Key: unique_key (optional)

Request:

{
  "amount": 99.99,
  "currencies": ["USDC", "USDT"],
  "chains": ["solana", "base"],
  "customer_email": "[email protected]",
  "external_id": "order_123",
  "description": "Premium subscription",
  "buffer_hours": 24,
  "expires_in": 3600,
  "redirect_url": "https://example.com/success",
  "metadata": {
    "order_id": "123",
    "product": "Premium Plan"
  }
}

Field	Type	Required	Description
amount	number	✓	Payment amount
currencies	string[]		Accepted currencies (default: all)
chains	string[]		Accepted chains (default: all)
customer_email	string		Customer email for notifications
external_id	string		Your internal reference
description	string		Invoice description
buffer_hours	number		Escrow buffer 0-168 (default: 24)
expires_in	number		Seconds until expiry (default: 3600)
redirect_url	string		Redirect after payment
metadata	object		Custom data

Response:

{
  "success": true,
  "data": {
    "invoice_id": "inv_abc123def456",
    "amount": 99.99,
    "currencies": ["USDC", "USDT"],
    "chains": ["solana", "base"],
    "status": "draft",
    "payment_url": "https://pay.stablix.xyz/inv_abc123def456",
    "expires_at": "2024-01-15T12:00:00Z",
    "created_at": "2024-01-15T11:00:00Z"
  }
}

---

Activate Invoice

Generates deposit addresses. Called automatically when user visits payment page, or manually via API.

POST /invoices/:invoiceId/activate

Auth: API Key or Public

Response:

{
  "success": true,
  "data": {
    "invoice_id": "inv_abc123",
    "status": "pending",
    "deposit_addresses": {
      "solana": {
        "USDC": "solana_deposit_address_usdc",
        "USDT": "solana_deposit_address_usdt"
      },
      "base": {
        "USDC": "base_deposit_address_usdc",
        "USDT": "base_deposit_address_usdt"
      }
    }
  }
}

---

Get Invoice

GET /invoices/:invoiceId

Auth: API Key

Response:

{
  "success": true,
  "data": {
    "invoice_id": "inv_abc123",
    "merchant_id": "mer_xyz789",
    "amount": 99.99,
    "currencies": ["USDC", "USDT"],
    "chains": ["solana", "base"],
    "status": "paid",
    "customer_email": "[email protected]",
    "external_id": "order_123",
    "payment": {
      "chain": "solana",
      "currency": "USDC",
      "tx_hash": "payment_tx_hash...",
      "amount_received": 99.99,
      "from_address": "payer_wallet",
      "confirmed_at": "2024-01-15T11:30:00Z"
    },
    "escrow": {
      "status": "funded",
      "release_at": "2024-01-16T11:30:00Z",
      "net_amount": 98.99,
      "fee_amount": 1.00
    },
    "deposit_addresses": { ... },
    "expires_at": "2024-01-15T12:00:00Z",
    "created_at": "2024-01-15T11:00:00Z"
  }
}

---

Get Invoice (Public)

For payment pages. Limited fields.

GET /invoices/public/:invoiceId

Auth: None

Response:

{
  "success": true,
  "data": {
    "invoice_id": "inv_abc123",
    "amount": 99.99,
    "currencies": ["USDC", "USDT"],
    "chains": ["solana", "base"],
    "status": "pending",
    "merchant": {
      "business_name": "Example Store"
    },
    "deposit_addresses": { ... },
    "expires_at": "2024-01-15T12:00:00Z"
  }
}

---

List Invoices

GET /invoices

Auth: API Key

Query Parameters:

Parameter	Type	Description
status	string	Filter by status
external_id	string	Filter by external ID
customer_email	string	Filter by customer email
from	string	Start date (ISO)
to	string	End date (ISO)
page	number	Page number
limit	number	Items per page (max 100)

Response:

{
  "success": true,
  "data": [
    {
      "invoice_id": "inv_abc123",
      "amount": 99.99,
      "status": "paid",
      "created_at": "2024-01-15T11:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150
  }
}

---

Release Invoice

Manually release funds from escrow before buffer period ends.

POST /invoices/:invoiceId/release

Auth: API Key

Response:

{
  "success": true,
  "message": "Invoice released",
  "data": {
    "invoice_id": "inv_abc123",
    "status": "released",
    "release_tx_hash": "release_tx_hash..."
  }
}

---

Refund Invoice

Refund a paid invoice (funds must still be in escrow).

POST /invoices/:invoiceId/refund

Auth: API Key

Request:

{
  "reason": "Customer requested refund"
}

Response:

{
  "success": true,
  "message": "Invoice refunded",
  "data": {
    "invoice_id": "inv_abc123",
    "status": "refunded",
    "refund_tx_hash": "refund_tx_hash..."
  }
}

---

Cancel Invoice

Cancel a draft or pending invoice.

POST /invoices/:invoiceId/cancel

Auth: API Key

Response:

{
  "success": true,
  "message": "Invoice cancelled",
  "data": {
    "invoice_id": "inv_abc123",
    "status": "cancelled"
  }
}

---

Get Invoice Stats

GET /invoices/stats/summary

Auth: API Key

Query Parameters:

Parameter	Type	Description
from	string	Start date (ISO)
to	string	End date (ISO)

Response:

{
  "success": true,
  "data": {
    "total_invoices": 500,
    "total_volume": 45000.00,
    "total_fees": 450.00,
    "by_status": {
      "paid": 400,
      "pending": 50,
      "expired": 30,
      "refunded": 20
    },
    "by_chain": {
      "solana": { "count": 350, "volume": 30000 },
      "base": { "count": 150, "volume": 15000 }
    }
  }
}

---

Plans

Reusable subscription product templates.

Create Plan

POST /plans

Auth: API Key

Request:

{
  "name": "Pro Monthly",
  "description": "Full access to all features",
  "amount": 29.99,
  "interval": "monthly",
  "interval_count": 1,
  "chains": ["solana", "base"],
  "currencies": ["USDC", "USDT"],
  "buffer_hours": 24,
  "trial_days": 14,
  "splits": [
    {
      "address": "partner_wallet",
      "chain": "solana",
      "percentage": 1000,
      "label": "Partner (10%)"
    }
  ],
  "metadata": {
    "features": ["api_access", "support"]
  }
}

Field	Type	Required	Description
name	string	✓	Plan name (max 100)
description	string		Description (max 500)
amount	number	✓	Price per cycle (min 0.01)
interval	string	✓	weekly, monthly, yearly
interval_count	number		Every N intervals (1-12, default: 1)
chains	string[]		Accepted chains
currencies	string[]		Accepted currencies
buffer_hours	number		Escrow buffer 0-168 (default: 24)
trial_days	number		Free trial 0-90 (default: 0)
splits	array		Revenue splits (max 5, max 50% total)
metadata	object		Custom data

Splits Object:

Field	Type	Description
address	string	Recipient wallet
chain	string	Chain for payment
percentage	number	Basis points (100 = 1%)
label	string	Description

Response:

{
  "success": true,
  "data": {
    "plan_id": "plan_abc123def456",
    "name": "Pro Monthly",
    "amount": 29.99,
    "interval": "monthly",
    "payment_url": "https://pay.stablix.xyz/subscribe/plan_abc123def456",
    "created_at": "2024-01-15T11:00:00Z"
  }
}

---

Get Plan

GET /plans/:planId

Auth: API Key

Response:

{
  "success": true,
  "data": {
    "plan_id": "plan_abc123",
    "merchant_id": "mer_xyz789",
    "name": "Pro Monthly",
    "description": "Full access to all features",
    "amount": 29.99,
    "interval": "monthly",
    "interval_count": 1,
    "chains": ["solana", "base"],
    "currencies": ["USDC", "USDT"],
    "buffer_hours": 24,
    "trial_days": 14,
    "splits": [ ... ],
    "is_active": true,
    "subscriber_count": 150,
    "total_revenue": 4499.50,
    "payment_url": "https://pay.stablix.xyz/subscribe/plan_abc123",
    "created_at": "2024-01-15T11:00:00Z"
  }
}

---

Get Plan (Public)

For subscription pages. Limited fields.

GET /plans/public/:planId

Auth: None

Response:

{
  "success": true,
  "data": {
    "plan_id": "plan_abc123",
    "name": "Pro Monthly",
    "description": "Full access to all features",
    "amount": 29.99,
    "interval": "monthly",
    "interval_count": 1,
    "chains": ["solana", "base"],
    "currencies": ["USDC", "USDT"],
    "trial_days": 14,
    "merchant": {
      "business_name": "Example SaaS"
    }
  }
}

---

List Plans

GET /plans

Auth: API Key

Query Parameters:

Parameter	Type	Description
is_active	boolean	Filter by active status
interval	string	Filter by interval
page	number	Page number
limit	number	Items per page (max 100)

Response:

{
  "success": true,
  "data": [
    {
      "plan_id": "plan_abc123",
      "name": "Pro Monthly",
      "amount": 29.99,
      "interval": "monthly",
      "is_active": true,
      "subscriber_count": 150
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5
  }
}

---

Update Plan

Only certain fields can be updated.

PATCH /plans/:planId

Auth: API Key

Request:

{
  "name": "Pro Monthly (Updated)",
  "description": "New description",
  "is_active": true,
  "metadata": { "updated": true }
}

Field	Updatable
name	✓
description	✓
is_active	✓
metadata	✓
amount	✗
interval	✗
chains	✗
currencies	✗
splits	✗

Response:

{
  "success": true,
  "message": "Plan updated",
  "data": {
    "plan_id": "plan_abc123",
    "name": "Pro Monthly (Updated)"
  }
}

---

Archive Plan

Deactivate a plan. Existing subscriptions continue.

POST /plans/:planId/archive

Auth: API Key

Response:

{
  "success": true,
  "message": "Plan archived",
  "data": {
    "plan_id": "plan_abc123",
    "is_active": false,
    "archived_at": "2024-03-01T11:00:00Z"
  }
}

---

Get Plan Stats

GET /plans/stats

Auth: API Key

Response:

{
  "success": true,
  "data": {
    "total_plans": 5,
    "active_plans": 4,
    "total_subscribers": 350,
    "total_revenue": 15499.50
  }
}

---

Subscriptions

Recurring payment relationships between subscribers and plans.

Subscribe (Public)

Start a subscription from the plan page. Called when user enters email.

POST /subscriptions/public/plan/:planId/subscribe

Auth: None

Request:

{
  "email": "[email protected]",
  "external_id": "cust_123"
}

Response:

{
  "success": true,
  "data": {
    "subscription_id": "sub_xyz789abc123",
    "plan_id": "plan_abc123",
    "status": "pending_approval",
    "trial_end": "2024-01-29T11:00:00Z"
  }
}

---

Create Subscription (Merchant)

Pre-create a subscription for a specific user.

POST /subscriptions

Auth: API Key

Request:

{
  "plan_id": "plan_abc123def456",
  "subscriber_email": "[email protected]",
  "subscriber_external_id": "cust_123",
  "metadata": {
    "source": "checkout"
  }
}

Field	Type	Required	Description
plan_id	string	✓	Plan to subscribe to
subscriber_email	string	✓	Subscriber's email
subscriber_external_id	string		Your internal customer ID
metadata	object		Custom data

Response:

{
  "success": true,
  "data": {
    "subscription_id": "sub_xyz789abc123",
    "plan_id": "plan_abc123",
    "plan_name": "Pro Monthly",
    "amount": 29.99,
    "status": "pending_approval",
    "approval_url": "https://pay.stablix.xyz/subscribe/plan_abc123?sub=sub_xyz789abc123",
    "created_at": "2024-01-15T11:00:00Z"
  }
}

---

Get Subscription (Public)

For approval pages.

GET /subscriptions/public/:subscriptionId

Auth: None

Response:

{
  "success": true,
  "data": {
    "subscription_id": "sub_xyz789",
    "plan_id": "plan_abc123",
    "plan_snapshot": {
      "name": "Pro Monthly",
      "amount": 29.99,
      "interval": "monthly",
      "interval_count": 1,
      "buffer_hours": 24
    },
    "status": "pending_approval",
    "trial_end": "2024-01-29T11:00:00Z"
  }
}

---

Confirm Approval

After subscriber approves in wallet.

POST /subscriptions/public/:subscriptionId/confirm

Auth: None

Request:

{
  "chain": "solana",
  "currency": "USDC",
  "wallet_address": "subscriber_wallet_address",
  "tx_hash": "approval_tx_hash...",
  "approved_amount": 359.88,
  "expires_at": "2025-01-15T11:00:00Z"
}

Field	Type	Required	Description
chain	string	✓	Selected chain
currency	string	✓	Selected currency
wallet_address	string	✓	Subscriber's wallet
tx_hash	string	✓	Approval transaction hash
approved_amount	number	✓	Total approved allowance
expires_at	string		Approval expiry (ISO)

Response:

{
  "success": true,
  "message": "Subscription activated",
  "data": {
    "subscription_id": "sub_xyz789",
    "status": "trialing",
    "trial_end": "2024-01-29T11:00:00Z",
    "next_charge_at": "2024-01-29T11:00:00Z"
  }
}

---

Get Subscription

GET /subscriptions/:subscriptionId

Auth: API Key

Response:

{
  "success": true,
  "data": {
    "subscription_id": "sub_xyz789",
    "merchant_id": "mer_abc123",
    "plan_id": "plan_abc123",
    "plan_snapshot": {
      "name": "Pro Monthly",
      "amount": 29.99,
      "interval": "monthly",
      "interval_count": 1,
      "buffer_hours": 24
    },
    "approved_chain": "solana",
    "approved_currency": "USDC",
    "subscriber": {
      "wallet_address": "subscriber_wallet...",
      "email": "[email protected]",
      "external_id": "cust_123"
    },
    "status": "active",
    "approval": {
      "status": "approved",
      "approved_amount": 359.88,
      "remaining_allowance": 299.90,
      "total_charged": 59.98,
      "expires_at": "2025-01-15T11:00:00Z",
      "last_verified_at": "2024-02-15T11:00:00Z"
    },
    "billing": {
      "current_period_start": "2024-02-15T11:00:00Z",
      "current_period_end": "2024-03-15T11:00:00Z",
      "next_charge_at": "2024-03-15T11:00:00Z",
      "total_charges": 2,
      "total_released": 59.98,
      "total_refunded": 0,
      "failed_charges": 0
    },
    "trial_end": null,
    "trial_used": true,
    "cancel_at_period_end": false,
    "created_at": "2024-01-15T11:00:00Z"
  }
}

---

List Subscriptions

GET /subscriptions

Auth: API Key

Query Parameters:

Parameter	Type	Description
status	string	Filter by status
plan_id	string	Filter by plan
chain	string	Filter by approved chain
subscriber_wallet	string	Filter by wallet
subscriber_email	string	Filter by email
subscriber_external_id	string	Filter by external ID
page	number	Page number
limit	number	Items per page

Response:

{
  "success": true,
  "data": [
    {
      "subscription_id": "sub_xyz789",
      "plan_id": "plan_abc123",
      "plan_snapshot": {
        "name": "Pro Monthly",
        "amount": 29.99
      },
      "status": "active",
      "approved_chain": "solana",
      "billing": {
        "next_charge_at": "2024-03-15T11:00:00Z"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150
  }
}

---

Pause Subscription

POST /subscriptions/:subscriptionId/pause

Auth: API Key

Response:

{
  "success": true,
  "message": "Subscription paused",
  "data": {
    "subscription_id": "sub_xyz789",
    "status": "paused"
  }
}

---

Resume Subscription

POST /subscriptions/:subscriptionId/resume

Auth: API Key

Response:

{
  "success": true,
  "message": "Subscription resumed",
  "data": {
    "subscription_id": "sub_xyz789",
    "status": "active",
    "next_charge_at": "2024-03-15T11:00:00Z"
  }
}

---

Cancel Subscription

POST /subscriptions/:subscriptionId/cancel

Auth: API Key

Request:

{
  "at_period_end": true,
  "reason": "Customer requested"
}

Field	Type	Default	Description
at_period_end	boolean	true	Cancel at period end vs immediately
reason	string		Cancellation reason

Response:

{
  "success": true,
  "message": "Subscription will be cancelled at period end",
  "data": {
    "subscription_id": "sub_xyz789",
    "status": "active",
    "cancel_at_period_end": true
  }
}

---

List Charges

GET /subscriptions/:subscriptionId/charges

Auth: API Key

Query Parameters:

Parameter	Type	Description
escrow_status	string	pending, funded, released, refunded
page	number	Page number
limit	number	Items per page

Response:

{
  "success": true,
  "data": [
    {
      "charge_id": "chg_abc123",
      "amount": 29.99,
      "fee": 0.30,
      "net_amount": 29.69,
      "escrow_status": "released",
      "escrow_tx_hash": "charge_tx...",
      "release_tx_hash": "release_tx...",
      "period_start": "2024-02-15T11:00:00Z",
      "period_end": "2024-03-15T11:00:00Z",
      "charged_at": "2024-02-15T11:00:00Z",
      "released_at": "2024-02-16T11:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5
  }
}

---

Refund Charge

Refund a specific charge (must still be in escrow).

POST /subscriptions/:subscriptionId/charges/:chargeId/refund

Auth: API Key

Request:

{
  "reason": "Service issue"
}

Response:

{
  "success": true,
  "message": "Charge refunded",
  "data": {
    "subscription_id": "sub_xyz789",
    "charge_id": "chg_abc123",
    "refund_tx_hash": "refund_tx..."
  }
}

---

Disputes

Buyer protection and conflict resolution.

Open Dispute (Merchant API)

POST /disputes/open

Auth: API Key

Request:

{
  "invoice_id": "inv_abc123",
  "reason": "product_not_received",
  "description": "Detailed explanation...",
  "buyer_email": "[email protected]",
  "evidence": [
    { "type": "text", "content": "Supporting text" },
    { "type": "link", "content": "https://example.com/proof" }
  ]
}

Field	Type	Required	Description
invoice_id	string	✓	Invoice to dispute
reason	string	✓	Reason code
description	string	✓	Detailed explanation
buyer_email	string		Email for updates
evidence	array		Supporting evidence

Reason Codes:

• product_not_received

• product_not_as_described

• unauthorized_transaction

• duplicate_charge

• service_not_rendered

• other

Response:

{
  "success": true,
  "data": {
    "dispute_id": "dis_abc123def456",
    "invoice_id": "inv_abc123",
    "amount": 99.99,
    "status": "open",
    "deadlines": {
      "merchant_response": "2024-01-18T11:00:00Z",
      "evidence": "2024-01-22T11:00:00Z",
      "resolution": "2024-01-29T11:00:00Z"
    },
    "created_at": "2024-01-15T11:00:00Z"
  }
}

---

Open Dispute (Buyer Dashboard)

POST /buyer/disputes/open

Auth: None (wallet verification)

Request:

{
  "invoice_id": "inv_abc123",
  "wallet_address": "buyer_wallet_address",
  "reason": "product_not_received",
  "description": "Detailed explanation...",
  "buyer_email": "[email protected]",
  "evidence": [ ... ]
}

---

Get Dispute

GET /disputes/:disputeId

Auth: API Key

Response:

{
  "success": true,
  "data": {
    "dispute_id": "dis_abc123",
    "invoice_id": "inv_abc123",
    "merchant_id": "mer_xyz789",
    "amount": 99.99,
    "currency": "USDC",
    "chain": "solana",
    "status": "pending_merchant",
    "reason": "product_not_received",
    "description": "...",
    "buyer_wallet": "buyer_wallet...",
    "buyer_email": "[email protected]",
    "buyer_evidence": [ ... ],
    "merchant_evidence": [ ... ],
    "deadlines": { ... },
    "status_history": [ ... ],
    "created_at": "2024-01-15T11:00:00Z"
  }
}

---

Get Dispute (Buyer)

GET /buyer/disputes/:disputeId?wallet=buyer_wallet_address

Auth: None (wallet verification)

---

List Disputes

GET /disputes

Auth: API Key

Query Parameters:

Parameter	Type	Description
status	string	Filter by status
invoice_id	string	Filter by invoice
page	number	Page number
limit	number	Items per page

---

List Buyer Disputes

GET /buyer/disputes?wallet=buyer_wallet_address

Auth: None (wallet verification)

---

Find Buyer Transactions

Look up transactions by wallet for dispute dashboard.

GET /buyer/transactions?wallet=buyer_wallet_address

or

GET /buyer/transactions?tx_hash=payment_tx_hash

Auth: None

Response:

{
  "success": true,
  "data": [
    {
      "invoice_id": "inv_abc123",
      "merchant": { "business_name": "Example Store" },
      "amount": 99.99,
      "currency": "USDC",
      "chain": "solana",
      "status": "paid",
      "escrow": {
        "status": "funded",
        "release_at": "2024-01-17T11:00:00Z"
      },
      "can_dispute": true,
      "dispute_deadline": "2024-01-17T11:00:00Z",
      "paid_at": "2024-01-15T11:00:00Z"
    }
  ]
}

---

Submit Evidence (Merchant)

POST /disputes/:disputeId/evidence

Auth: API Key

Content-Type: multipart/form-data

Field	Type	Description
files	file[]	Evidence files (max 5, 10MB each)
description	string	Text explanation
links	string[]	Supporting URLs

Response:

{
  "success": true,
  "message": "Evidence submitted",
  "data": {
    "dispute_id": "dis_abc123",
    "evidence_count": 3,
    "status": "pending_buyer"
  }
}

---

Submit Evidence (Buyer)

POST /buyer/disputes/:disputeId/evidence

Auth: None (wallet verification)

Content-Type: multipart/form-data

Field	Type	Description
wallet_address	string	Buyer's wallet
files	file[]	Evidence files
description	string	Text explanation
links	string[]	Supporting URLs

---

Accept Dispute

Merchant accepts and agrees to refund.

POST /disputes/:disputeId/accept

Auth: API Key

Response:

{
  "success": true,
  "message": "Dispute accepted, refund initiated",
  "data": {
    "dispute_id": "dis_abc123",
    "status": "resolved",
    "resolution": {
      "decision": "buyer_wins",
      "buyer_amount": 98.99,
      "merchant_amount": 0,
      "fee_amount": 1.00,
      "tx_hash": "refund_tx..."
    }
  }
}

---

Webhooks

Event notifications sent to your endpoint.

Events

Invoice Events

Event	Description
invoice.created	Invoice created
invoice.activated	Deposit addresses generated
invoice.paid	Payment received
invoice.released	Funds released to merchant
invoice.refunded	Invoice refunded
invoice.expired	Invoice expired
invoice.cancelled	Invoice cancelled

Plan Events

Event	Description
plan.created	Plan created
plan.updated	Plan updated
plan.archived	Plan archived

Subscription Events

Event	Description
subscription.created	Subscription created
subscription.approved	Subscriber approved spending
subscription.charged	Successful charge
subscription.charge_failed	Charge failed
subscription.charge_released	Charge released
subscription.charge_refunded	Charge refunded
subscription.paused	Subscription paused
subscription.resumed	Subscription resumed
subscription.cancelled	Subscription cancelled
subscription.low_allowance	Allowance below threshold
subscription.approval_expiring	Approval expires soon

Dispute Events

Event	Description
dispute.opened	New dispute
dispute.evidence_submitted	Evidence added
dispute.status_changed	Status changed
dispute.resolved	Dispute resolved
dispute.closed	Dispute closed

Webhook Payload

{
  "event": "invoice.paid",
  "data": {
    "invoice_id": "inv_abc123",
    "amount": 99.99,
    "currency": "USDC",
    "chain": "solana",
    "payment": {
      "tx_hash": "payment_tx...",
      "from_address": "payer_wallet"
    }
  },
  "timestamp": "2024-01-15T11:30:00Z"
}

Webhook Headers

X-Stablix-Signature: signature_hash
X-Stablix-Timestamp: 1705319400
X-Stablix-Event: invoice.paid
X-Stablix-Delivery-ID: del_abc123

Signature Verification

const crypto = require('crypto');

function verifyWebhook(payload, signature, timestamp, secret) {
  const signedPayload = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

---

Error Codes

Code	HTTP	Description
VALIDATION_ERROR	400	Invalid request data
UNAUTHORIZED	401	Invalid or missing auth
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
CONFLICT	409	Resource state conflict
RATE_LIMITED	429	Too many requests
INTERNAL_ERROR	500	Server error

---

Rate Limits

Endpoint Type	Limit
Public	60/minute
API Key	1000/minute
Dashboard	300/minute

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1705319400

---

Status Values

Invoice Status

Status	Description
draft	Created, no deposit addresses
pending	Activated, awaiting payment
paid	Payment received, in escrow
released	Funds released to merchant
refunded	Refunded to buyer
expired	Payment deadline passed
cancelled	Cancelled by merchant

Subscription Status

Status	Description
pending_approval	Awaiting wallet approval
trialing	In free trial
active	Active and billing
paused	Temporarily paused
past_due	Charge failed, retrying
cancelled	Subscription ended
expired	Approval never completed

Escrow Status

Status	Description
pending	Awaiting payment
funded	Funds in escrow
released	Released to merchant
refunded	Returned to buyer

Dispute Status

Status	Description
open	Newly opened
pending_merchant	Awaiting merchant response
pending_buyer	Awaiting buyer response
under_review	Admin reviewing
resolved	Decision made
closed	Withdrawn/expired