Configuration

Before creating invoices, configure Checkout in the FinCobra dashboard. The dashboard controls payment methods, invoice defaults, webhook delivery, and API keys. Merchant integrations use API keys only for invoice creation and invoice lookup.

Setup Checklist

1. Add at least one payment method.
2. Set default invoice timing.
3. Add your invoice issuer name.
4. Configure a redirect URL if customers should return to your site after payment.
5. Configure a webhook URL if your server needs payment notifications.
6. Generate and copy an API key.
7. Optional: install FinCobra Checkout on iPhone or Android for quick access from your phone.

Payment Methods

Checkout supports these method types:

Method type	Use for
bitcoin	Bitcoin address-transfer checkout
ethereum	Ethereum stablecoin checkout with wallet-contract and address-transfer rails

Invoices are built from the enabled payment methods. Each created invoice returns paymentOptions[], which describes the available rails for that invoice. Ethereum payment methods require at least one enabled rail.

Ethereum due-date invoices require an enabled USDT or USDC payment method on Ethereum. Bitcoin payment methods are only used for immediate invoices.

Invoice Defaults

Setting	Description
Default payment timing	Timing used when an API request omits paymentTiming.
Bitcoin post-expiry grace	How long to keep watching BTC invoice addresses after the final payable deadline.
Invoice issuer name	Default issuedBy value and organization name shown on hosted invoices.
Customer emails	Optional invoice-created and payment-detected email notifications.
Redirect URL	Default URL used after payment confirmation. Can be overridden per invoice.
Invoice form fields	Dashboard-only setting for optional fields shown in the dashboard create-invoice form.

Immediate Timing

Use immediate timing for standard checkout flows with a countdown timer:

{
  "paymentTiming": {
    "mode": "immediate",
    "expiresAfterMinutes": 20
  }
}

expiresAfterMinutes must be between 1 and 1440.

Due-Date Timing

Use due-date timing when an invoice should remain payable through a due date and grace period:

{
  "paymentTiming": {
    "mode": "due_date",
    "dueAfterDays": 7,
    "gracePeriodDays": 14
  }
}

dueAfterDays must be between 1 and 60. gracePeriodDays must be between 0 and 90.

Due-date invoices do not show a live expiration countdown. They remain payable until the final payable deadline (dueAt + gracePeriodDays) and then expire.

Webhooks

Set a webhook URL in the dashboard to receive invoice events. Use the API settings event switches to choose which webhook events are delivered. Create a webhook signing secret before relying on webhook delivery. FinCobra signs webhook payloads with your webhook signing secret.

The webhook secret is shown when it is created or rotated. Copy it immediately and store it in your server-side secret manager.

See Webhooks for payloads and signature verification.

API Keys

Generate API keys from the dashboard. The raw key is shown once and cannot be retrieved later.

Use API keys only from your server:

X-Api-Key: fc_live_...

API keys can create invoices and read invoice-specific data. Dashboard configuration, payment-method management, webhook settings, exports, and exception closing are managed in the dashboard.