04 invoices

Invoices are the core of Stablix. Create an invoice to accept a one-time payment.

Invoice Lifecycle

pending → paid → [buffer period] → released (auto)
                        ↘ disputed → resolved
         → expired
         → refunded

Status	Description
pending	Awaiting payment
paid	Payment received, funds in escrow
released	Funds auto-released to merchant after buffer
refunded	Funds returned to buyer
expired	Payment deadline passed
disputed	Under dispute resolution
resolved	Dispute resolved

---

Create Invoice

POST /invoices

Request

{
  "amount": 99.99,
  "currency": "USDC",
  "chain": "solana",
  "buffer_hours": 24,
  "expires_in_minutes": 60,
  "external_id": "order_12345",
  "customer_email": "[email protected]",
  "metadata": {
    "product": "Premium Plan",
    "order_id": "12345"
  },
  "redirect_url": "https://mystore.com/success",
  "splits": [
    {
      "address": "affiliate_wallet_address",
      "percentage": 10
    }
  ]
}

Parameters

Field	Type	Required	Description
amount	number	✓	Payment amount in USD
currency	string	✓	USDC or USDT
chain	string	✓	solana or base
buffer_hours	number		Escrow period (0-720 hours, default: 24)
expires_in_minutes	number		Payment deadline (default: 60)
external_id	string		Your internal order ID
customer_email	string		Buyer's email for notifications
metadata	object		Custom data (max 10 keys)
redirect_url	string		Redirect after payment
splits	array		Revenue splits (affiliates, partners)

Response

{
  "success": true,
  "data": {
    "invoice_id": "inv_abc123def456",
    "amount": 99.99,
    "currency": "USDC",
    "chain": "solana",
    "status": "pending",
    "payment_url": "https://pay.stablix.xyz/inv_abc123def456",
    "deposit_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "expires_at": "2024-01-15T12:00:00Z",
    "escrow": {
      "buffer_hours": 24
    },
    "fee": {
      "percentage": 0.5,
      "amount": 0.50
    },
    "created_at": "2024-01-15T11:00:00Z"
  }
}

Code Examples

Node.js

const response = await fetch('https://api.stablix.xyz/api/v1/invoices', {
  method: 'POST',
  headers: {
    'X-API-Key': 'sk_live_your_secret_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 99.99,
    currency: 'USDC',
    chain: 'solana',
    external_id: 'order_12345'
  })
});

const { data } = await response.json();
console.log('Payment URL:', data.payment_url);

Python

cURL

---

Get Invoice

GET /invoices/:invoiceId

Response

{
  "success": true,
  "data": {
    "invoice_id": "inv_abc123def456",
    "merchant_id": "mer_xyz789",
    "amount": 99.99,
    "currency": "USDC",
    "chain": "solana",
    "status": "paid",
    "payment": {
      "deposit_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      "tx_hash": "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp...",
      "amount_received": 99.99,
      "from_address": "buyer_wallet_address",
      "confirmed_at": "2024-01-15T11:30:00Z"
    },
    "escrow": {
      "buffer_hours": 24,
      "release_at": "2024-01-16T11:30:00Z",
      "status": "held"
    },
    "fee": {
      "percentage": 0.5,
      "amount": 0.50
    },
    "external_id": "order_12345",
    "metadata": {
      "product": "Premium Plan"
    },
    "created_at": "2024-01-15T11:00:00Z",
    "expires_at": "2024-01-15T12:00:00Z"
  }
}

---

List Invoices

GET /invoices

Query Parameters

Parameter	Type	Description
status	string	Filter by status
chain	string	Filter by chain
currency	string	Filter by currency
external_id	string	Filter by external ID
startDate	ISO date	Created after
endDate	ISO date	Created before
page	number	Page number (default: 1)
limit	number	Items per page (default: 20, max: 100)

Example

GET /invoices?status=paid&chain=solana&page=1&limit=20

Response

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

---

Fund Release

Funds are released to merchants automatically when the buffer period expires. This protects buyers from scams.

Who	Can Release?	Can Refund?
System	✅ Auto after buffer	-
Admin	✅ Manual if needed	✅
Merchant	❌ No	✅ Yes

Security Note: Merchants cannot release funds to themselves. This prevents a merchant from taking payment and disappearing before delivery. Buyers have the buffer period to open a dispute if something goes wrong.

---

Refund Invoice

Refund a paid invoice back to the buyer.

POST /invoices/:invoiceId/refund

Request

{
  "reason": "Customer requested refund"
}

Response

{
  "success": true,
  "message": "Invoice refunded successfully",
  "data": {
    "invoice_id": "inv_abc123",
    "status": "refunded",
    "refund": {
      "amount": 99.99,
      "tx_hash": "refund_tx_hash...",
      "reason": "Customer requested refund",
      "refunded_at": "2024-01-15T16:00:00Z"
    }
  }
}

---

Get Public Invoice

For payment pages. No authentication required.

GET /invoices/public/:invoiceId

Response

{
  "success": true,
  "data": {
    "invoice_id": "inv_abc123",
    "merchant": {
      "business_name": "My Store"
    },
    "amount": 99.99,
    "currency": "USDC",
    "chain": "solana",
    "status": "pending",
    "deposit_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "expires_at": "2024-01-15T12:00:00Z"
  }
}

---

Invoice Stats

Get aggregate statistics for your invoices.

GET /invoices/stats/summary

Query Parameters

Parameter	Type	Description
startDate	ISO date	Start of period
endDate	ISO date	End of period

Response

{
  "success": true,
  "data": {
    "total_invoices": 1250,
    "total_volume": 125000.00,
    "total_fees": 625.00,
    "by_status": {
      "pending": 15,
      "paid": 50,
      "released": 1150,
      "refunded": 25,
      "expired": 10
    },
    "by_chain": {
      "solana": { "count": 800, "volume": 80000 },
      "base": { "count": 450, "volume": 45000 }
    },
    "by_currency": {
      "USDC": { "count": 1000, "volume": 100000 },
      "USDT": { "count": 250, "volume": 25000 }
    }
  }
}

---

Revenue Splits

Split payments between multiple recipients (affiliates, partners, etc.).

{
  "amount": 100,
  "currency": "USDC",
  "chain": "solana",
  "splits": [
    {
      "address": "affiliate_wallet",
      "percentage": 10,
      "description": "Affiliate commission"
    },
    {
      "address": "partner_wallet",
      "percentage": 5,
      "description": "Partner fee"
    }
  ]
}

When the invoice is released:

• Affiliate receives: $10 (10%)

• Partner receives: $5 (5%)

• Merchant receives: $84.50 (85% minus 0.5% fee)

---

Idempotency

Prevent duplicate invoices using the Idempotency-Key header:

curl -X POST https://api.stablix.xyz/api/v1/invoices \
  -H "X-API-Key: sk_live_xxx" \
  -H "Idempotency-Key: order_12345_v1" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100, "currency": "USDC", "chain": "solana"}'

If you send the same request with the same idempotency key within 24 hours, you'll receive the original response instead of creating a duplicate invoice.