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
evm	Ethereum, Arbitrum One, and Base stablecoin checkout with wallet-contract and address-transfer rails
solana	Solana USDT and USDC wallet checkout

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

Supported networks and assets:

Network	Assets	Dashboard setting
Bitcoin	BTC	Bitcoin xpub
Ethereum mainnet	USDT, USDC	Ethereum payout wallet
Solana	USDT, USDC	Solana recipient wallet
Arbitrum One	USDC	Arbitrum payout wallet
Base	USDC	Base payout wallet

Solana wallet payments and Bitcoin address-transfer payments settle directly to the recipient wallet configured for the payment method. EVM wallet-contract payments and address-transfer withdrawals settle to the payout wallet configured for that specific EVM network. FinCobra records invoice volume and commission internally for billing where funds are sent directly to the merchant wallet.

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

Finding Your Bitcoin xpub

Export the extended public key for the Bitcoin account that should receive checkout payments. Wallets commonly expose it in the account details, export, or advanced settings as an xpub, ypub, or zpub. FinCobra only needs the extended public key; never paste a seed phrase or private key.

For hardware wallets, open the Bitcoin account in the wallet's companion app and look for an account-public-key or extended-public-key export. If the wallet provides several formats, use the key for the address type you already receive to: xpub for legacy addresses, ypub for nested SegWit, or zpub for native SegWit.

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.

Checkout Appearance

The General tab can set a Checkout avatar and a single background image for hosted invoice pages. The background spans the full desktop and mobile payment page, with separate contrast overlays keeping the invoice summary and payment controls readable.

Avatar and background uploads accept PNG, JPEG, and WebP images. FinCobra resizes and stores them as compressed WebP files. Checkout appearance is separate from donation-page appearance.

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.