Custom checkout
Create a payment for each order and store the returned payment ID beside your own order reference.
Bitcoin payment API
Bitcoin payment API for custom checkout systems.
Create Bitcoin payment requests from your backend, show customers a wallet address and amount, track transaction status, and receive signed webhooks when payments are detected and confirmed.
Use case
A payment verification API between your checkout and the Bitcoin network.
Manatee is designed for developers who already run a backend and want to add Bitcoin payment verification without operating their own listener, confirmation worker, or webhook retry system.
Bitcoin transaction webhook API
Receive signed events when a payment is detected and when it reaches the confirmation threshold.
Non-custodial flow
Customer funds settle directly to wallet addresses you control. Manatee monitors payment state but does not hold Bitcoin.
Payment lifecycle
From payment creation to signed order updates.
The API gives your backend explicit checkpoints for building a Bitcoin checkout without treating an unconfirmed transaction as final.
Create payment
Your backend creates a payment with amount, expiry, reference, confirmation policy, and webhook URL.
Show address and amount
Your checkout displays the returned Bitcoin address, exact satoshi amount, and expiry time.
Detect transaction
Manatee watches the Bitcoin network and marks the payment when a matching transaction appears.
Track confirmations
The payment moves toward confirmation based on the threshold you set per checkout.
Send signed webhook
Your backend receives HMAC-signed events for detection and confirmation.
Update order state
Your system maps payment events back to orders using your reference and stored payment ID.
API examples
Server-side requests, checkout display, and webhook reconciliation.
Keep API keys on your backend. Your frontend only needs the payment instructions your server returns to the customer.
POST /v1/btc/paymentsserver-side
curl -sS -X POST "$MANATEE_API_URL/v1/btc/payments" \
-H "Authorization: Bearer $MANATEE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-10042-create-payment" \
-d '{
"fiat_amount": "51.00",
"fiat_currency": "EUR",
"webhook_url": "https://yourapp.com/webhooks/btc",
"required_confirmations": 1,
"expires_in": 3600,
"reference": "order-10042"
}'GET /v1/btc/payments/{id}server-side
curl -sS "$MANATEE_API_URL/v1/btc/payments/pay_abc123" \ -H "Authorization: Bearer $MANATEE_API_KEY"
payment.confirmed webhookserver-side
{
"version": "1",
"type": "payment.confirmed",
"data": {
"payment_id": "pay_abc123",
"txid": "a1b2c3d4...",
"address": "tb1q...",
"amount_sats": 85000,
"received_sats": 85000,
"confirmations": 1,
"webhook_url": "https://yourapp.com/webhooks/btc"
}
}Sandbox and testnet
Build against testnet before sending real Bitcoin.
Validate payment creation, webhook signature verification, and order-state transitions before switching your checkout to mainnet.
Payment statuses
Use Manatee statuses as your checkout source of truth.
These are the current API statuses your integration should handle. If you need customer-facing labels such as waiting or paid, map them in your own order system.
No matching Bitcoin transaction has been detected yet.
Show payment instructions and keep the checkout open.
A matching transaction was seen, but confirmations are still below the configured threshold.
Show that payment was seen and wait before fulfillment.
The transaction reached the required confirmation count.
Mark the order as paid according to your risk policy.
The payment expired before a matching transaction was detected.
Close the checkout session or create a fresh payment.
Your backend cancelled a still-pending payment.
Stop showing the payment and prevent later fulfillment from this checkout.
Implementation docs
Go deeper on webhooks, security, and payment state.
These docs cover the parts most custom checkout integrations need before production.
Start with testnet
Create a test API key and verify your first Bitcoin payment flow.
Use testnet payments and signed webhook events to connect Manatee to your order backend before moving real payments to mainnet.