Checkout API

FinCobra Checkout lets you accept payments programmatically. Funds go directly to your wallet - no custodial intermediary.

Quickstart

Use this path for a standard server-side checkout integration:

1. Configure Checkout in the dashboard. Add at least one payment method, set the default invoice timing, set your issuer name, and add a webhook URL if your server needs payment updates.
2. Create an API key in Checkout settings. Copy it once and store it in your server-side environment or secret manager.
3. Create an invoice from your server:

curl -X POST https://fincobra.com/api/checkout/invoices \
  -H "X-Api-Key: fc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amountUsd": 49.99,
    "productName": "Pro Plan - Monthly",
    "merchantReference": "order_123",
    "customerEmail": "buyer@example.com"
  }'

4. Store the returned id and paymentUrl with your order.
5. Send the customer to paymentUrl. The hosted payment page handles wallet connection, QR codes, payment instructions, and live status updates.
6. Verify webhooks with your signing secret. When a webhook arrives, fetch the latest invoice status and update your order from the current invoice state.

For most integrations, you only need to create invoices, redirect customers to paymentUrl, and listen for webhooks.

Coding agent setup

If you are using a coding agent to add FinCobra Checkout to an app, give it the Agent Quickstart. It includes the exact hosted-checkout implementation scope, webhook verification requirements, status mapping, and tests to add.

Core Concepts

Concept	What to use it for
paymentUrl	Hosted payment page URL. Redirect customers here unless you are building a custom payment page.
status	Main invoice state for fulfillment. Treat confirmed as paid. Treat payment_detected as received but not fully confirmed.
Webhooks	Server-to-server notifications for invoice state changes. Always verify the signature before processing.
merchantReference	Your order, cart, or internal reference. Store it so webhook payloads can be matched to your system.
paymentSummary	Amount received, remaining, and overpaid. Use this when handling partial or overpaid invoices.
paymentOptions[]	Available payment instructions for the invoice. Most integrations do not need this unless building custom payment UI.
Billing	First $1,000 of paid invoice volume is free, then Pay as You Go starts automatically.

Payment methods

The checkout model is payment-method based:

• ethereum for USDT and USDC stablecoin checkout on Ethereum
• bitcoin for Bitcoin address generation

Invoices are built from the payment methods enabled in the dashboard. You do not need to choose a method when creating a standard hosted-page invoice.

Base URL

All API endpoints are relative to:

https://fincobra.com

Next steps

• Authentication - authenticate server-side API requests
• Agent Quickstart - give this implementation brief to a coding agent
• Configuration - configure payment methods, invoice defaults, webhooks, and API keys
• Billing - understand Free Start and automatic Pay as You Go tiers
• Mobile App - install FinCobra Checkout on iPhone or Android
• Invoices - create invoices and read invoice state
• Payment Page - send customers to the hosted payment page
• Webhooks - receive and verify payment notifications
• API Reference - endpoint contracts and field reference
• Smart Contracts - Ethereum contract addresses and purpose