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",
    "webhookSecret": "a1b2c3d4e5f6...",
    "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.0,
  "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)
webhookSecret	HMAC-SHA256 signing secret for webhook verification. Store securely.
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

Rotate webhook secret

POST /api/checkout/config/webhook-secret/rotate

Rotates the HMAC signing secret used for webhook delivery and returns the new value immediately:

{
  "webhookSecret": "new-secret-value"
}

WARNING

After rotating the secret, update your webhook consumer before accepting more events. Requests signed with the old secret will stop validating immediately.