Payments

Create a payment

POST/pay/create

Generate a Bitcoin or Lightning payment request. Returns a hosted payment URL, QR data, and the live payment object.

Returns 201 on success with { success: true, payment: {…} }.
Errors return 400 with { success: false, error, message }.

Authentication

Requires an API key in the X-API-Key header.

Body parameters

typebtclightningoptional

defaults to btc

amountnumberrequired

positive number, in currency

currencyCHFUSDEURSATSoptional

defaults to CHF

descriptionstringoptional

shown on the hosted page

callback_urlstringoptional

webhooks POST here on status changes

redirect_urlstringoptional

where customers go after paying

expiration_minutesnumberoptional

default 15 (BTC) / 60 (Lightning)

required_confirmationsnumberoptional

BTC only, default 1

metadataobjectoptional

echoed back on webhooks unchanged

POST/pay/create

curl --request POST "https://api.trevi.cash/pay/create" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $BTPAY_API_KEY" \
  --data '{
    "type": "btc",
    "amount": 49.99,
    "currency": "CHF",
    "description": "Order #12345",
    "callback_url": "https://yoursite.com/webhooks/btpay",
    "redirect_url": "https://yoursite.com/orders/thank-you",
    "metadata": { "order_id": "12345" }
  }'

200Sample response

{
  "success": true,
  "payment": {
    "request_id": "pay_abc123def456abc123def456abc123de",
    "payment_type": "btc",
    "status": "pending",
    "amount_sats": 150000,
    "amount_btc": "0.00150000",
    "amount_fiat": 49.99,
    "currency": "CHF",
    "description": "Order #12345",
    "expires_at": "2026-05-18T12:15:00.000Z",
    "time_remaining_seconds": 900,
    "qr_data": "bitcoin:bc1qxyz...?amount=0.00150000",
    "btc_address": "bc1qxyz...",
    "confirmations": 0,
    "required_confirmations": 1,
    "payment_url": "https://api.trevi.cash/pay/page/pay_abc123def456abc123def456abc123de"
  }
}

Was this page helpful?

Health check

Check payment status