Configuration

Before creating invoices, you need a checkout configuration. Each user has one config that stores their extended public key and default settings.

Get configuration

GET /api/checkout/config

Returns your current checkout config, or 404 if not configured yet.

Response:

{
  "config": {
    "id": "uuid",
    "userId": "123",
    "xpub": "zpub6r...",
    "addressIndex": 15,
    "defaultTtlMinutes": 20,
    "unconfirmedWaitMinutes": 480,
    "callbackUrl": "https://yoursite.com/webhook",
    "redirectUrl": "https://yoursite.com/thank-you",
    "createdAt": "2025-01-10T08:00:00.000Z",
    "updatedAt": "2025-01-15T12:00:00.000Z"
  }
}

Create or update configuration

PUT /api/checkout/config

Creates a new config or updates the existing one (upsert). If you change the xpub, the address index resets to 0.

Request body:

Field	Type	Required	Description
xpub	string	Yes	Extended public key (xpub, ypub, or zpub). 60–120 characters.
defaultTtlMinutes	integer	No	Default invoice expiration time. 1–1440 (24h). Default: 20.
unconfirmedWaitMinutes	integer	No	Grace period after expiry for unconfirmed transactions. 1–2880 (48h). Default: 480 (8h).
callbackUrl	string	No	Webhook URL for payment notifications. Must be a valid URL.
redirectUrl	string	No	Default redirect URL after payment confirms. Can be overridden per invoice.

Example:

curl -X PUT \
  -H "X-Api-Key: fc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "xpub": "zpub6rFR7y4Q2AijBEqTUqiByp...",
    "defaultTtlMinutes": 30,
    "callbackUrl": "https://yoursite.com/webhook"
  }' \
  https://fincobra.com/api/checkout/config

Error responses:

Status	Error
400	Validation failed (xpub too short, invalid URL, etc.)
409	xpub already used by another configuration

Get wallet balance

GET /api/checkout/config/balance

Returns the current wallet balance derived from your xpub via Electrum.

Response:

{
  "confirmedBtc": 0.0042,
  "unconfirmedBtc": 0.001,
  "totalBtc": 0.0052,
  "totalUsd": 520.00,
  "btcRate": 100000
}

Field	Type	Description
confirmedBtc	number	Confirmed balance in BTC
unconfirmedBtc	number	Unconfirmed (mempool) balance in BTC
totalBtc	number	Total balance (confirmed + unconfirmed)
totalUsd	number	Total balance converted to USD
btcRate	number	Current BTC/USD exchange rate used

Configuration fields reference

Field	Description
id	Unique config ID (UUID). Also used as the HMAC signing secret for webhooks.
userId	Owner user ID
xpub	Extended public key for address derivation
addressIndex	Next derivation index (auto-incremented)
defaultTtlMinutes	Default time-to-live for new invoices
unconfirmedWaitMinutes	How long to wait after expiry for late transactions
callbackUrl	Webhook endpoint for payment events
redirectUrl	Default post-payment redirect URL