Skip to main content

Bitcoin payment API

A payment API your backend can reason about.

Create an on-chain Bitcoin payment, expose only the returned payment instructions to checkout, and drive order state from verifiable events.

Explore API referenceCreate test API key
POST /v1/btc/paymentsapplication/json
Requestcurl
curl -X POST /v1/btc/payments \
  -H "Authorization: Bearer $MANATEE_API_KEY" \
  -H "Idempotency-Key: order-10042" \
  -d '{
    "fiat_amount": "51.00",
    "fiat_currency": "EUR",
    "reference": "order-10042",
    "required_confirmations": 1
  }'
Response201 Created
{
  "id": "pay_abc123",
  "status": "pending",
  "amount_sats": 85000,
  "address": "tb1q...",
  "expires_at": "2026-07-20T18:30:00Z"
}

State model

Four states. One fulfilment decision.

Use payment state as an explicit contract instead of inferring success from a browser redirect.
  1. pending

    Instructions issued

    Show the exact address, satoshi amount, and expiry returned by the API.

  2. detected

    Transaction seen

    A matching transaction is visible, but has not reached your confirmation policy.

  3. confirmed

    Ready to fulfil

    The required confirmation threshold is met and a signed event is delivered.

  4. expired / cancelled

    Monitor released

    Closed payment attempts stop consuming active monitor capacity.

Read the complete payment lifecycle

Integration contract

The production details are part of the interface.

Authentication, retries, event verification, and reconciliation are documented behavior, not assumptions hidden behind an SDK.
Authentication
Network-scoped bearer keysKeep Testnet4 and mainnet credentials separate and server-side.
Safe retries
Idempotency-Key per operationRepeat a timed-out create request without creating a second payment.
Order updates
HMAC-signed webhook eventsVerify the raw request body before changing fulfilment state.
Reconciliation
Explicit status transitionsHandle underpayment, expiry, cancellation, and late transactions deliberately.

Start without moving real Bitcoin

Run the full integration on Testnet4 first.

Network-scoped test keySigned webhook verificationDashboard usage visibility
Create test API keyOpen Quickstart