Source: https://fincobra.com/docs/checkout/


# 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:

```bash
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, Bitcoin QR codes, address-transfer 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.

Prefer TypeScript? Use the [FinCobra SDK](./sdk.md) for `client.checkoutSessions.create(...)`, `client.invoices.create(...)`, `client.payments.get(...)`, and webhook signature verification.

## Coding agent setup

If you are using a coding agent to add FinCobra Checkout to an app, give it the [Agent Quickstart](./agent-quickstart.md). 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:

- `evm` for USDT and USDC stablecoin checkout on Ethereum, Arbitrum One, and Base
- `solana` for Solana wallet checkout with USDT and USDC direct wallet settlement
- `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.

## Supported Chains

| Network          | Assets     | Settlement                                                           |
| ---------------- | ---------- | -------------------------------------------------------------------- |
| Bitcoin          | BTC        | Unique invoice addresses derived from your Bitcoin xpub              |
| Ethereum mainnet | USDT, USDC | Wallet-contract payments and deterministic address-transfer invoices |
| Solana           | USDT, USDC | Customers connect a Solana wallet and approve payment to your wallet |
| Arbitrum One     | USDC       | Wallet-contract payments and deterministic address-transfer invoices |
| Base             | USDC       | Wallet-contract payments and deterministic address-transfer invoices |

## Base URL

All API endpoints are relative to:

```
https://fincobra.com
```

## Next steps

- [Authentication](./authentication.md) - authenticate server-side API requests
- [Agent Quickstart](./agent-quickstart.md) - give this implementation brief to a coding agent
- [TypeScript SDK](./sdk.md) - install the SDK and copy Next.js, Express, and webhook examples
- [Configuration](./configuration.md) - configure payment methods, invoice defaults, webhooks, and API keys
- [Billing](./billing.md) - understand Free Start and flat Pay as You Go pricing
- [WooCommerce](./woocommerce.md) - download the plugin zip and connect a USD store
- [MCP](./mcp.md) - connect to FinCobra MCP 0.4.0 for Checkout invoices and Watchlist tools
- [Mobile App](./mobile-app.md) - install FinCobra Checkout on iPhone or Android
- [Invoices](./invoices.md) - create invoices and read invoice state
- [Payment Page](./payment-page.md) - send customers to the hosted payment page
- [Donate Button](./donate-button.md) - add a public donation page and embeddable button
- [Webhooks](./webhooks.md) - receive and verify payment notifications
- [API Reference](./api-reference.md) - endpoint contracts and field reference
- [Smart Contracts](./smart-contracts.md) - EVM contract addresses and purpose