Payments API

Create a payment order

POST /api/v1/payments
X-API-Key: your-api-key
Content-Type: application/json

Request body:

{
  "amount": "99.00",
  "currency": "USDT",
  "external_id": "order_123",
  "webhook_url": "https://your-backend.com/webhooks/paywarden",
  "metadata": {
    "customer_id": "cust_456",
    "product": "Pro Plan"
  }
}

Field	Type	Required	Description
amount	string	✅	Amount in USDT (e.g. "99.00")
currency	string	✅	Must be "USDT"
external_id	string	✅	Your internal order ID (must be unique)
webhook_url	string	❌	URL to receive payment events
metadata	object	❌	Arbitrary key-value pairs, returned in webhooks

Response 201:

{
  "id": "ord_abc123",
  "status": "pending",
  "amount": "99.00",
  "currency": "USDT",
  "address": "TXxx...unique-payment-address",
  "external_id": "order_123",
  "expires_at": "2025-01-01T01:00:00Z",
  "created_at": "2025-01-01T00:00:00Z",
  "checkout_url": "https://pay.yourdomain.com/checkout/ord_abc123"
}

Get order details

GET /api/v1/payments/:id
X-API-Key: your-api-key

Response 200:

{
  "id": "ord_abc123",
  "status": "confirmed",
  "amount": "99.00",
  "amount_received": "99.00",
  "currency": "USDT",
  "address": "TXxx...",
  "external_id": "order_123",
  "tx_hash": "def456...",
  "confirmations": 19,
  "expires_at": "2025-01-01T01:00:00Z",
  "created_at": "2025-01-01T00:00:00Z",
  "confirmed_at": "2025-01-01T00:05:00Z",
  "events": [
    { "type": "created", "at": "2025-01-01T00:00:00Z" },
    { "type": "detected", "at": "2025-01-01T00:03:00Z", "tx_hash": "def456..." },
    { "type": "confirmed", "at": "2025-01-01T00:05:00Z", "confirmations": 19 }
  ]
}

Order status values

Status	Description
pending	Waiting for payment
detected	Transfer seen on-chain, awaiting confirmations
confirmed	Payment confirmed, webhook sent
completed	Webhook acknowledged by your backend
expired	Order expired without payment
failed	Webhook delivery failed after 10 attempts

List orders

GET /api/v1/payments?page=1&limit=20&status=confirmed
X-API-Key: your-api-key

Query param	Default	Description
page	1	Page number
limit	20	Items per page (max 100)
status	—	Filter by status

Response 200:

{
  "data": [ /* array of order objects */ ],
  "total": 142,
  "page": 1,
  "limit": 20
}