Skip to main content

Accept Bitcoin Payments: Integration Responsibilities

This page defines the boundary between Manatee and your application. For the runnable testnet integration, use the Quickstart; for the commercial product overview, see Bitcoin Payment API.

Manatee monitors on-chain payments without taking custody. Your customer sends Bitcoin directly to a wallet address you control; Manatee watches that address and reports detection and confirmation to your backend. See Custodial vs. Non-Custodial Bitcoin Payments for a detailed explanation of fund control and responsibilities.

For a deeper look at event payloads, retries, and failure handling, see Webhook Delivery in a Bitcoin Payment API.

How the checkout flow works​

  1. Your checkout creates an order in your own system.
  2. Your backend calls POST /v1/btc/payments with either amount_sats or fiat_amount plus fiat_currency, confirmation policy, expiry, and webhook URL.
  3. Manatee returns a Bitcoin receiving address and a payment ID.
  4. Your frontend shows the address, exact amount, and expiry time to the customer.
  5. Manatee watches the Bitcoin network and sends signed webhook events as the payment status changes.
  6. Your backend verifies the webhook signature and marks the order as paid after payment.confirmed.

What Manatee handles​

  • Payment address monitoring
  • Mempool detection
  • Confirmation tracking
  • Payment expiry while the payment is still pending
  • Signed webhook delivery
  • Webhook retry attempts
  • Payment lookup by API

What stays in your system​

  • Product pricing, tax rules, and refund handling
  • Final checkout display and customer communication
  • Customer checkout UI
  • Wallet ownership
  • Order fulfillment policy
  • Accounting and reconciliation records

Use a dedicated business wallet or wallet account for Manatee payments. Configure a receive descriptor or extended public key so each payment gets a fresh receiving address. Store the returned Manatee payment ID next to your own order ID and process webhook events idempotently.

Make your webhook route reachable by server-to-server HTTP requests. If your site uses Cloudflare, a WAF, bot protection, captchas, browser challenges, or login redirects, bypass those protections only for the webhook path and verify requests with the X-Manatee-Signature HMAC header.

For the complete first integration, start with the Quickstart.

Last updated on