Skip to content

API Reference

Base URL: https://fincobra.com

Use the FinCobra dashboard to configure Checkout, payment methods, webhook settings, and API keys. Use the API from your server to create invoices and read known invoice state.

Authentication

Merchant endpoints require an API key:

http
X-Api-Key: fc_live_...

API keys can create invoices and read known invoice data. They cannot list all invoices or change Checkout configuration.

Merchant Endpoints

MethodPathDescription
POST/api/checkout/invoicesCreate an invoice
GET/api/checkout/invoices/:idGet invoice detail
GET/api/checkout/invoices/:id/statusGet invoice status
POST/api/checkout/invoices/:id/voidVoid an unpaid invoice
POST/api/checkout/invoices/:id/record-paymentRecord an external payment

Create Invoice

POST /api/checkout/invoices

Creates a checkout invoice using your configured payment methods.

Request

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"
  }'

Request Body

FieldTypeRequiredDescription
amountUsdnumberYesInvoice amount in USD. Minimum 0.01.
paymentTimingobjectNoPer-invoice timing override. Omit to use the dashboard default.
productNamestringNoProduct or service label. Max 200 chars.
issuedBystringNoInvoice issuer name. Defaults to the dashboard setting. Max 120 chars.
billTostringNoCustomer or company name shown on the invoice. Max 120 chars.
redirectUrlstringNoRedirect URL after the payer-facing flow completes.
merchantReferencestringNoYour order, cart, or internal reference. Max 200 chars.
customerIdstringNoYour internal customer ID. Max 200 chars.
customerEmailstringNoCustomer email for reconciliation. Max 320 chars.
metadataobjectNoJSON object stored with the invoice. metadata.notes, when present, must be a string up to 140 chars.

Response

Returns HTTP 201 with an Invoice object:

json
{
  "id": "a1b2c3d4-1111-4222-8333-abcdefabcdef",
  "paymentUrl": "https://fincobra.com/pay/a1b2c3d4-1111-4222-8333-abcdefabcdef",
  "amountUsd": 49.99,
  "status": "awaiting_payment",
  "paymentCoverage": "no_payment",
  "receivedAmountUsd": 0,
  "confirmedAmountUsd": 0,
  "confirmations": 0,
  "paymentTiming": {
    "mode": "immediate",
    "expiresAfterMinutes": 20,
    "payableUntilAt": "2026-04-29T10:20:00.000Z"
  },
  "paymentDetectedAt": null,
  "confirmedAt": null,
  "createdAt": "2026-04-29T10:00:00.000Z",
  "productName": "Pro Plan - Monthly",
  "issuedBy": "Acme, Inc.",
  "billTo": null,
  "redirectUrl": "https://example.com/thanks",
  "lastTransactionHash": null,
  "merchantReference": "order_123",
  "customerId": null,
  "customerEmail": "buyer@example.com",
  "metadata": null,
  "paymentSummary": {
    "paymentCoverage": "no_payment",
    "receivedAmountUsd": 0,
    "confirmedAmountUsd": 0,
    "remainingAmountUsd": 49.99,
    "overpaymentAmountUsd": 0
  },
  "paymentOptions": [
    {
      "id": "payment-option-1",
      "railType": "wallet_contract",
      "assetCode": "USDT",
      "network": "ethereum",
      "tokenContract": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "quotedAmount": 49.99,
      "quoteRate": 1,
      "destinationAddress": null,
      "status": "active",
      "isDefault": true,
      "paymentUri": null,
      "qrCode": null,
      "optionPayload": {
        "railType": "wallet_contract",
        "chainId": 1,
        "contractAddress": "0x...",
        "tokenContract": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
        "recipient": "0x1111111111111111111111111111111111111111",
        "decimals": 6,
        "requiredConfirmations": 14,
        "paymentAmountAtomic": "49990000"
      }
    }
  ],
  "defaultPaymentOptionId": "payment-option-default",
  "lastPaymentOptionId": "payment-option-1",
  "lastPaymentObservedAt": null
}

Use paymentUrl for hosted checkout. Use paymentOptions[] only when building custom payment UI.

Get Invoice Detail

GET /api/checkout/invoices/:id

Returns a known invoice by id.

bash
curl https://fincobra.com/api/checkout/invoices/a1b2c3d4-1111-4222-8333-abcdefabcdef \
  -H "X-Api-Key: fc_live_..."

Returns an Invoice object, including payments[] when payment events have been observed:

json
{
  "id": "a1b2c3d4-1111-4222-8333-abcdefabcdef",
  "paymentUrl": "https://fincobra.com/pay/a1b2c3d4-1111-4222-8333-abcdefabcdef",
  "amountUsd": 49.99,
  "status": "payment_detected",
  "paymentCoverage": "exact_payment",
  "receivedAmountUsd": 49.99,
  "confirmedAmountUsd": 0,
  "confirmations": 1,
  "paymentTiming": {
    "mode": "immediate",
    "expiresAfterMinutes": 20,
    "payableUntilAt": "2026-04-29T10:20:00.000Z"
  },
  "paymentDetectedAt": "2026-04-29T10:05:00.000Z",
  "confirmedAt": null,
  "createdAt": "2026-04-29T10:00:00.000Z",
  "productName": "Pro Plan - Monthly",
  "issuedBy": "Acme, Inc.",
  "billTo": null,
  "redirectUrl": "https://example.com/thanks",
  "lastTransactionHash": "0xabc123...",
  "merchantReference": "order_123",
  "customerId": null,
  "customerEmail": "buyer@example.com",
  "metadata": {
    "orderId": "order_123"
  },
  "paymentSummary": {
    "paymentCoverage": "exact_payment",
    "receivedAmountUsd": 49.99,
    "confirmedAmountUsd": 0,
    "remainingAmountUsd": 0,
    "overpaymentAmountUsd": 0
  },
  "paymentOptions": [
    {
      "id": "payment-option-1",
      "railType": "wallet_contract",
      "assetCode": "USDT",
      "network": "ethereum",
      "tokenContract": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "quotedAmount": 49.99,
      "quoteRate": 1,
      "destinationAddress": null,
      "status": "active",
      "isDefault": true,
      "paymentUri": null,
      "qrCode": null,
      "optionPayload": {
        "railType": "wallet_contract",
        "chainId": 1,
        "contractAddress": "0x...",
        "tokenContract": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
        "recipient": "0x1111111111111111111111111111111111111111",
        "decimals": 6,
        "requiredConfirmations": 14,
        "paymentAmountAtomic": "49990000"
      }
    }
  ],
  "defaultPaymentOptionId": "payment-option-default",
  "lastPaymentOptionId": "payment-option-1",
  "payments": [
    {
      "id": "payment-1",
      "paymentOptionId": "payment-option-1",
      "assetCode": "USDT",
      "network": "ethereum",
      "destinationAddress": null,
      "transactionHash": "0xabc123...",
      "amountReceived": 49.99,
      "observedTotalAmount": 49.99,
      "confirmations": 1,
      "observedAt": "2026-04-29T10:05:00.000Z",
      "confirmedAt": null,
      "invalidatedAt": null,
      "invalidationReason": null
    }
  ],
  "lastPaymentObservedAt": "2026-04-29T10:05:00.000Z"
}

Get Invoice Status

GET /api/checkout/invoices/:id/status

Returns a polling-friendly status payload for a known invoice:

bash
curl https://fincobra.com/api/checkout/invoices/a1b2c3d4-1111-4222-8333-abcdefabcdef/status \
  -H "X-Api-Key: fc_live_..."
json
{
  "status": "payment_detected",
  "paymentCoverage": "exact_payment",
  "receivedAmountUsd": 49.99,
  "confirmedAmountUsd": 0,
  "confirmations": 1,
  "paymentDetectedAt": "2026-04-29T10:05:00.000Z",
  "confirmedAt": null,
  "paidOutOfBandAt": null,
  "paidOutOfBandNote": null,
  "paymentTiming": {
    "mode": "immediate",
    "expiresAfterMinutes": 20,
    "payableUntilAt": "2026-04-29T10:20:00.000Z"
  },
  "paymentSummary": {
    "paymentCoverage": "exact_payment",
    "receivedAmountUsd": 49.99,
    "confirmedAmountUsd": 0,
    "remainingAmountUsd": 0,
    "overpaymentAmountUsd": 0
  },
  "paymentOptions": [
    {
      "id": "payment-option-1",
      "railType": "wallet_contract",
      "assetCode": "USDT",
      "network": "ethereum",
      "tokenContract": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "quotedAmount": 49.99,
      "quoteRate": 1,
      "destinationAddress": null,
      "status": "active",
      "isDefault": true,
      "paymentUri": null,
      "qrCode": null,
      "optionPayload": {
        "railType": "wallet_contract",
        "chainId": 1,
        "contractAddress": "0x...",
        "tokenContract": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
        "recipient": "0x1111111111111111111111111111111111111111",
        "decimals": 6,
        "requiredConfirmations": 14,
        "paymentAmountAtomic": "49990000"
      }
    }
  ],
  "defaultPaymentOptionId": "payment-option-default",
  "lastPaymentOptionId": "payment-option-1",
  "payments": [
    {
      "id": "payment-1",
      "paymentOptionId": "payment-option-1",
      "assetCode": "USDT",
      "network": "ethereum",
      "destinationAddress": null,
      "transactionHash": "0xabc123...",
      "amountReceived": 49.99,
      "observedTotalAmount": 49.99,
      "confirmations": 1,
      "observedAt": "2026-04-29T10:05:00.000Z",
      "confirmedAt": null,
      "invalidatedAt": null,
      "invalidationReason": null
    }
  ],
  "lastPaymentObservedAt": "2026-04-29T10:05:00.000Z"
}

Void Invoice

POST /api/checkout/invoices/:id/void

Voids an invoice that is still awaiting_payment.

bash
curl -X POST https://fincobra.com/api/checkout/invoices/a1b2c3d4-1111-4222-8333-abcdefabcdef/void \
  -H "X-Api-Key: fc_live_..." \
  -H "Content-Type: application/json" \
  -d '{}'

Returns the updated invoice object. Requests for invoices in any other status return HTTP 409.

Record Payment

POST /api/checkout/invoices/:id/record-payment

Records an external payment for an invoice in awaiting_payment, partially_paid, or expired.

bash
curl -X POST https://fincobra.com/api/checkout/invoices/a1b2c3d4-1111-4222-8333-abcdefabcdef/record-payment \
  -H "X-Api-Key: fc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "note": "Paid by wire transfer"
  }'

Request Body

FieldTypeRequiredDescription
notestringYesReconciliation note for the external payment. Max 2000 chars.

Returns the updated invoice object with status: "paid_out_of_band", paidOutOfBandAt, and paidOutOfBandNote.

Public Payment Page API

These unauthenticated endpoints power the hosted payment page and can be used for custom payment pages. Do not use them for private merchant metadata or server-side reconciliation.

MethodPathDescription
GET/api/checkout/pay/:idGet customer-facing invoice data
GET/api/checkout/pay/:id/statusPoll customer-facing invoice status

Get Public Invoice

GET /api/checkout/pay/:id

Returns customer-facing invoice data, payment instructions, and public payment status. It does not require an API key.

Public responses intentionally exclude merchant-only fields such as merchantReference, customerId, customerEmail, and metadata. Customer-facing fields such as issuedBy, billTo, productName, paymentTiming, and redirectUrl may be included. Merchant reconciliation notes for out-of-band payments are not returned by public endpoints.

json
{
  "id": "a1b2c3d4-1111-4222-8333-abcdefabcdef",
  "paymentUrl": "https://fincobra.com/pay/a1b2c3d4-1111-4222-8333-abcdefabcdef",
  "amountUsd": 49.99,
  "status": "awaiting_payment",
  "paymentCoverage": "no_payment",
  "receivedAmountUsd": 0,
  "confirmedAmountUsd": 0,
  "confirmations": 0,
  "paymentTiming": {
    "mode": "immediate",
    "expiresAfterMinutes": 20,
    "payableUntilAt": "2026-04-29T10:20:00.000Z"
  },
  "paymentDetectedAt": null,
  "confirmedAt": null,
  "createdAt": "2026-04-29T10:00:00.000Z",
  "productName": "Pro Plan - Monthly",
  "issuedBy": "Acme, Inc.",
  "billTo": null,
  "redirectUrl": "https://example.com/thanks",
  "lastTransactionHash": null,
  "paymentSummary": {
    "paymentCoverage": "no_payment",
    "receivedAmountUsd": 0,
    "confirmedAmountUsd": 0,
    "remainingAmountUsd": 49.99,
    "overpaymentAmountUsd": 0
  },
  "paymentOptions": [
    {
      "id": "payment-option-1",
      "railType": "address_transfer",
      "assetCode": "BTC",
      "network": "bitcoin",
      "tokenContract": null,
      "quotedAmount": 0.00073,
      "quoteRate": 68479.45,
      "destinationAddress": "bc1qexample...",
      "status": "active",
      "isDefault": true,
      "paymentUri": "bitcoin:bc1qexample...?amount=0.00073",
      "qrCode": "<svg>...</svg>",
      "optionPayload": {
        "railType": "address_transfer",
        "requiredConfirmations": 1
      }
    }
  ],
  "defaultPaymentOptionId": "payment-option-default",
  "lastPaymentOptionId": "payment-option-1",
  "payments": [],
  "lastPaymentObservedAt": null
}

Get Public Invoice Status

GET /api/checkout/pay/:id/status

Returns the current customer-facing status for an invoice. Use this endpoint when building a custom payment page that polls for payment progress.

json
{
  "status": "payment_detected",
  "paymentCoverage": "exact_payment",
  "receivedAmountUsd": 49.99,
  "confirmedAmountUsd": 0,
  "confirmations": 1,
  "paymentDetectedAt": "2026-04-29T10:05:00.000Z",
  "confirmedAt": null,
  "paidOutOfBandAt": null,
  "paidOutOfBandNote": null,
  "paymentTiming": {
    "mode": "immediate",
    "expiresAfterMinutes": 20,
    "payableUntilAt": "2026-04-29T10:20:00.000Z"
  },
  "paymentSummary": {
    "paymentCoverage": "exact_payment",
    "receivedAmountUsd": 49.99,
    "confirmedAmountUsd": 0,
    "remainingAmountUsd": 0,
    "overpaymentAmountUsd": 0
  },
  "paymentOptions": [
    {
      "id": "payment-option-1",
      "railType": "address_transfer",
      "assetCode": "BTC",
      "network": "bitcoin",
      "tokenContract": null,
      "quotedAmount": 0.00073,
      "quoteRate": 68479.45,
      "destinationAddress": "bc1qexample...",
      "status": "active",
      "isDefault": true,
      "paymentUri": "bitcoin:bc1qexample...?amount=0.00073",
      "qrCode": null,
      "optionPayload": {
        "railType": "address_transfer",
        "requiredConfirmations": 1
      }
    }
  ],
  "defaultPaymentOptionId": "payment-option-default",
  "lastPaymentOptionId": "payment-option-1",
  "payments": [
    {
      "id": "payment-1",
      "paymentOptionId": "payment-option-1",
      "assetCode": "BTC",
      "network": "bitcoin",
      "destinationAddress": "bc1qexample...",
      "transactionHash": "btc_tx_hash",
      "amountReceived": 0.00073,
      "observedTotalAmount": 0.00073,
      "confirmations": 1,
      "observedAt": "2026-04-29T10:05:00.000Z",
      "confirmedAt": null,
      "invalidatedAt": null,
      "invalidationReason": null
    }
  ],
  "lastPaymentObservedAt": "2026-04-29T10:05:00.000Z"
}

Objects

Invoice Object

FieldTypeDescription
idstringInvoice UUID. Store this with your order.
paymentUrlstringHosted payment page URL.
amountUsdnumberInvoice amount in USD.
statusstringMain invoice state. See Status values.
paymentCoveragestringWhether payment is missing, partial, exact, or overpaid.
receivedAmountUsdnumberUSD amount received across all valid payment options.
confirmedAmountUsdnumberUSD amount that has reached the confirmation threshold.
confirmationsnumberConfirmations observed for the invoice-counted payment.
productNamestring or nullProduct or service label.
issuedBystring or nullInvoice issuer name shown on the hosted page.
billTostring or nullCustomer or company name shown on the hosted page.
redirectUrlstring or nullURL used after the payer-facing flow completes.
lastTransactionHashstring or nullLatest transaction hash observed for invoice-counted payment evidence.
merchantReferencestring or nullYour order, cart, or internal reference.
customerIdstring or nullYour internal customer ID.
customerEmailstring or nullCustomer email for reconciliation.
metadataobject or nullMerchant metadata stored with the invoice.
paymentSummaryobjectAmount received, remaining, and overpaid.
paymentTimingobjectImmediate or due-date timing.
paymentOptionsarrayPayment instructions available for this invoice.
defaultPaymentOptionIdstring or nullInitial hosted page payment option for the invoice.
lastPaymentOptionIdstring or nullLatest observed payment option for the invoice.
paymentsarrayObserved payment events. Present on detail/status responses.
paymentDetectedAtstring or nullISO timestamp when sufficient payment was first detected.
confirmedAtstring or nullISO timestamp when sufficient payment reached the confirmation threshold.
paidOutOfBandAtstring or nullISO timestamp when an external payment was recorded.
paidOutOfBandNotestring or nullReconciliation note for an external payment.
exceptionTypelate_payment, partial_payment, or nullException type when merchant review is needed.
exceptionStatusopen, closed, or nullCurrent exception state.
exceptionActionaccept_late_payment, mark_paid_out_of_band, close_unpaid, or nullMerchant action used when the exception was closed.
exceptionNotestring or nullMerchant note recorded when the exception was closed.
exceptionClosedAtstring or nullISO timestamp when the exception was closed.
createdAtstringISO timestamp when the invoice was created.
lastPaymentObservedAtstring or nullISO timestamp for the latest observed payment event.

Payment Summary Object

FieldTypeDescription
paymentCoveragestringWhether payment is missing, partial, exact, or overpaid.
receivedAmountUsdnumberUSD amount received across all valid payment options.
remainingAmountUsdnumberUSD amount still due.
overpaymentAmountUsdnumberUSD amount overpaid.

Payment Timing Object

Immediate timing:

json
{
  "mode": "immediate",
  "expiresAfterMinutes": 20,
  "payableUntilAt": "2026-04-29T10:20:00.000Z"
}

Due-date timing:

json
{
  "mode": "due_date",
  "dueAfterDays": 7,
  "gracePeriodDays": 14,
  "dueAt": "2026-05-06T10:00:00.000Z",
  "payableUntilAt": "2026-05-20T10:00:00.000Z"
}

Due-date invoices require an enabled USDT or USDC payment method on Ethereum.

Payment Option Object

FieldTypeDescription
idstringPayment option ID.
railTypewallet_contract or address_transferPayment rail used by this option.
assetCodestringAsset shown to the payer, such as USDT, USDC, or BTC.
networkstringNetwork shown to the payer, such as ethereum or bitcoin.
tokenContractstring or nullToken contract address for token-based options.
quotedAmountnumberAmount due in the option asset.
quoteRatenumberRate used to quote the asset amount.
destinationAddressstring or nullDestination address for address-transfer payment options.
paymentUristring or nullPayment URI for address-transfer payment options.
qrCodestring or nullSVG QR code for the selected address-transfer option when requested.
statusstringPayment option status.
isDefaultbooleanWhether this is the default option on the hosted page.
optionPayloadobject or nullExecutable payment data for custom wallet UI.

For standard hosted checkout, redirect to paymentUrl and ignore paymentOptions[].

Payment Object

FieldTypeDescription
idstringObserved payment ID.
paymentOptionIdstringPayment option matched by the observation.
assetCodestringObserved asset.
networkstringObserved network.
destinationAddressstring or nullObserved destination address when applicable.
transactionHashstring or nullOn-chain transaction hash when available.
amountReceivednumberAmount counted from this observation.
observedTotalAmountnumberTotal amount observed for the matched payment evidence.
confirmationsnumberConfirmations observed for this payment.
observedAtstringISO timestamp when payment was observed.
confirmedAtstring or nullISO timestamp when this payment was confirmed.
invalidatedAtstring or nullISO timestamp when previously observed evidence was invalidated, if applicable.
invalidationReasonstring or nullReason a previously observed payment no longer counts toward the invoice payment, if applicable.

Status Values

FieldValues
statusawaiting_payment, partially_paid, payment_detected, confirmed, paid_out_of_band, expired, voided
paymentCoverageno_payment, partial_payment, exact_payment, overpayment

Use status for fulfillment decisions. paymentCoverage and paymentSummary explain underpayment and overpayment. A payment first observed at or before paymentTiming.payableUntilAt is on time; a payment first observed after that timestamp is late. Overpayment during the payable window does not open an exception; the invoice remains in its payment lifecycle state and exposes the excess amount in paymentSummary.overpaymentAmountUsd. A late payment never confirms an expired or voided invoice automatically. Late full payment opens a late_payment exception, and the invoice becomes confirmed only after the merchant closes it with accept_late_payment. confirmedAmountUsd shows how much USD has reached the confirmation threshold. Use payments[] for payment-level details such as transaction hash, observed asset amount, USD credit, confirmations, and confirmedAt.

Rate Limits

API-key-authenticated checkout requests are limited to 100 requests per minute from the same client. This limit applies to:

MethodPath
POST/api/checkout/invoices
GET/api/checkout/invoices/:id
GET/api/checkout/invoices/:id/status
POST/api/checkout/invoices/:id/void
POST/api/checkout/invoices/:id/record-payment

Requests over the limit return HTTP 429. Use the retry time in the error response before sending more requests.

Error Format

Errors use a JSON object with an error message:

json
{
  "error": "Human-readable error message"
}

Validation errors name the first invalid field and the relevant constraint:

json
{
  "error": "productName must be at most 200 characters"
}

HTTP Status Codes

CodeMeaning
200Success
201Invoice created
400Invalid request body, query, or invoice ID. The error message names the invalid field when validation fails.
401Missing or invalid API key
403Billing blocked invoice creation, or the API key cannot access the requested route
404Checkout config or invoice not found
409Incompatible invoice timing or unavailable payment method
429Rate limit exceeded. API-key-authenticated checkout requests are limited to 100 requests per minute from the same client.
502Payment-method or wallet backend unavailable