Skip to main content
API docs by Redocly

Bitcoin Payment API Reference (0.1.0)

Download OpenAPI specification:Download

License: Proprietary

Accept on-chain Bitcoin payments with confirmation tracking, network-scoped API keys, and signed webhooks.

payments

Create and query Bitcoin on-chain payments

Create a new payment

Creates a payment and returns a Bitcoin address.

Authorizations:
bearerAuth
header Parameters
Idempotency-Key
string

Idempotency key for safe retries

Request Body schema: application/json
required
amount_sats
required
integer >= 1

Amount in satoshis

underpayment_tolerance_ppm
integer [ 0 .. 10000 ]
Default: 0

Optional downward payment tolerance in parts per million. 1000 ppm allows a 0.1% underpayment.

webhook_url
string <uri>

Optional webhook endpoint URL. Production rejects localhost, private, link-local, and carrier-grade NAT addresses. The endpoint must accept server-to-server HTTP requests; bypass Cloudflare/WAF/bot challenges for the webhook path and verify requests with the X-Signature HMAC header.

destination_address
string

Optional custom destination address. If omitted, the API derives an address from the API key's receive descriptor. If provided, the API key must allow customer-provided addresses, the address must match the key network, and the same address cannot already have another active payment.

required_confirmations
integer [ 1 .. 6 ]
Default: 3

Number of block confirmations required before the payment is confirmed. Defaults to 3.

expires_in
integer [ 300 .. 86400 ]
Default: 3600

Payment expiry in seconds. Only pending payments expire. Defaults to 3600 (1 hour).

reference
string

Optional external reference ID for reconciliation (e.g. order ID)

Responses

Request samples

Content type
application/json
{
  • "amount_sats": 10000,
  • "underpayment_tolerance_ppm": 0,
  • "webhook_url": "https://yourapp.com/webhooks/btc",
  • "destination_address": "string",
  • "required_confirmations": 1,
  • "expires_in": 900,
  • "reference": "order-123"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "address": "string",
  • "txid": "string",
  • "amount_sats": 1,
  • "underpayment_tolerance_ppm": 10000,
  • "received_sats": 0,
  • "status": "pending",
  • "confirmations": 0,
  • "required_confirmations": 1,
  • "webhook_url": "http://example.com",
  • "network": "testnet",
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "reference": "string"
}

Get List of payments by time range

Authorizations:
bearerAuth
query Parameters
from
required
integer
Examples: from=1744675200

Start of time range

to
required
integer
Examples: to=1744675900

End of time range

filter
string
Default: "all"
Enum: "all" "verified" "unverified"

Filter by confirmation status.

  • all: all payments
  • verified: only confirmed payments
  • unverified: payments not yet confirmed (pending, detected, expired, cancelled)
limit
integer [ 1 .. 100 ]
Default: 50

Maximum number of payments to return

offset
integer >= 0
Default: 0

Number of payments to skip

Responses

Request samples 

curl -X GET "https://api.manatee-api.io/v1/btc/payments?from=1744675200&to=1744675900&filter=all&limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get a payment by ID

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X GET "https://api.manatee-api.io/v1/btc/payments/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response samples

Content type
application/json
{
  • "id": "string",
  • "address": "string",
  • "txid": "string",
  • "amount_sats": 1,
  • "underpayment_tolerance_ppm": 10000,
  • "received_sats": 0,
  • "status": "pending",
  • "confirmations": 0,
  • "required_confirmations": 1,
  • "webhook_url": "http://example.com",
  • "network": "testnet",
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "reference": "string"
}

Cancel a pending payment

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X POST "https://api.manatee-api.io/v1/btc/payments/abc123/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response samples

Content type
application/json
{
  • "id": "string",
  • "address": "string",
  • "txid": "string",
  • "amount_sats": 1,
  • "underpayment_tolerance_ppm": 10000,
  • "received_sats": 0,
  • "status": "pending",
  • "confirmations": 0,
  • "required_confirmations": 1,
  • "webhook_url": "http://example.com",
  • "network": "testnet",
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "reference": "string"
}

webhooks

Outbound HTTP callbacks sent to your server

Payment detected Webhook

Sent to the webhook_url specified during payment creation once an incoming transaction is detected in the mempool.

Signature verification

Every request includes an HMAC-SHA256 signature in the X-Signature header. Verify it by computing HMAC-SHA256(secret, body) using your webhook signing secret and comparing the result to the sha256=<hex> value in the header.

header Parameters
X-Event-ID
required
string

Unique identifier for this event delivery

X-Event-Type
required
string
Examples: payment.detected

Event type

X-Signature
required
string
Examples: sha256=a3f1...

HMAC-SHA256 signature of the raw request body using your webhook signing secret

Request Body schema: application/json
required
version
required
string

Webhook payload schema version

type
required
string
Enum: "payment.detected" "payment.confirmed"

Event type

required
object (PaymentWebhookData)

Responses

Request samples

Content type
application/json
{
  • "version": "1",
  • "type": "payment.detected",
  • "data": {
    }
}

Payment confirmed Webhook

Sent to the webhook_url specified during payment creation once the payment reaches the required number of confirmations.

Signature verification

Every request includes an HMAC-SHA256 signature in the X-Signature header. Verify it by computing HMAC-SHA256(secret, body) using your webhook signing secret and comparing the result to the sha256=<hex> value in the header.

header Parameters
X-Event-ID
required
string

Unique identifier for this event delivery

X-Event-Type
required
string
Examples: payment.confirmed

Event type

X-Signature
required
string
Examples: sha256=a3f1...

HMAC-SHA256 signature of the raw request body using your webhook signing secret

Request Body schema: application/json
required
version
required
string

Webhook payload schema version

type
required
string
Enum: "payment.detected" "payment.confirmed"

Event type

required
object (PaymentWebhookData)

Responses

Request samples

Content type
application/json
{
  • "version": "1",
  • "type": "payment.detected",
  • "data": {
    }
}

List webhook delivery events for a payment

Returns stored webhook delivery attempts for a payment that belongs to the authenticated API key.

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Send a test webhook

Sends a synthetic payment.confirmed webhook event to the provided webhook_url.

Use this endpoint to verify endpoint reachability, request headers, payload parsing, and signature validation without creating a Bitcoin transaction. The test event is delivered immediately and is not stored as a payment or webhook event.

If the webhook URL is protected by Cloudflare, a WAF, bot protection, captchas, browser challenges, or login redirects, bypass those protections for the webhook path and verify authenticity with the X-Signature HMAC header instead.

Authorizations:
bearerAuth
Request Body schema: application/json
required
webhook_url
required
string <uri>

Public webhook endpoint URL that should receive the synthetic test event. The endpoint must accept server-to-server HTTP requests and must not require browser challenges, captchas, or login redirects.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "event_id": "string",
  • "event_type": "payment.confirmed",
  • "status": 200,
  • "delivered": true
}