Skip to content

API Reference ​

This is the complete API reference for BITXpay. All endpoints use HTTPS and return JSON responses.

Base URL ​

text
https://api.bitxpay.com/api/v1
text
https://sandboxapi.bitxpay.com/api/v1

Authentication ​

All merchant API requests must include signature authentication headers. Merchant endpoints (payment links and /merchant/... subscriptions) use Ed25519 (EdDSA) signature authentication (RSA-PSS accepted for legacy keys). See Authentication for details.

Merchant APIs (Ed25519 signature):

bash
X-API-Key: btxm_9b451fa04a2e           # same format in sandbox and production
X-API-Signature: <base64_encoded_ed25519_signature>
X-API-Timestamp: 2026-01-31T12:00:00Z

Payer checkout routes under /public/... do not use merchant credentials. Dashboard APIs, including webhook management, use a dashboard session. Never embed your merchant private key in a checkout page.

Endpoints ​

Payments (Merchant API) ​

MethodEndpointDescription
GET/payment_links/currenciesGet currencies; optionally filter by currency_type=fiat or crypto
GET/payment_links/catalogDiscover available checkout chains, tokens, and settlement currencies
GET/payment_linksList all payment links
POST/payment_linksCreate a payment link
GET/payment_links/:idGet payment link by ID
PUT/payment_links/:id/statusDeactivate or expire a payment link
DELETE/payment_links/:idSoft-delete a payment link

Subscriptions — Authenticated (Merchant) Routes ​

MethodEndpointDescription
POST/merchant/subscription_plans/Create a subscription plan
GET/merchant/subscription_plans/List subscription plans
GET/merchant/subscription_plans/:idGet subscription plan by ID
PUT/merchant/subscription_plans/:idUpdate a subscription plan
POST/merchant/subscribers/Create a subscriber
GET/merchant/subscribers/Get subscribers by merchant
GET/merchant/subscribers/plan/:plan_idGet subscribers by plan ID
PUT/merchant/subscribers/:idUpdate a subscriber
GET/merchant/subscribers/:idGet subscriber by ID
GET/merchant/subscribers/invitationsGet merchant invitations
GET/merchant/subscription_links/List subscription links
GET/merchant/subscription_links/:idGet subscription link by ID

These routes require Merchant API Key authentication (X-API-Key/X-API-Signature with Ed25519), same as the Payments API.

Subscriptions — Public Routes ​

MethodEndpointDescription
GET/public/subscriptions/plans/List public subscription plans
GET/public/subscriptions/plans/:idGet public subscription plan by ID
GET/public/subscriber/preparePrepare subscription enrollment
GET/public/subscriber/:idGet subscriber by ID
PUT/public/subscriber/:idUpdate subscriber
POST/public/subscriptions/link/Create a subscription link
GET/public/subscriptions/link/:walletAddressGet subscription links by wallet address
POST/public/subscriptions/link/paymentRecord a subscription payment
PUT/public/subscriptions/link/:idUpdate a subscription link
GET/public/subscriptions/nft/:plan_idGet subscription NFT metadata

These routes do not require merchant signature headers — they are called directly from the customer-facing wallet/checkout flow. See Subscriptions for full request/response details.

Payments — Public Checkout ​

MethodEndpointDescription
GET/public/payments/links/:idGet payer-facing payment link details
GET/public/payments/links/:id/validateValidate a payment link
GET/public/payments/engine/links/:id/optionsGet available network/token choices
POST/public/payments/engine/links/:id/quoteSelect or refresh a payment quote
GET/public/payments/engine/links/:id/statePoll order status and confirmations

The engine checkout routes are mounted only when configured and enabled. See Checkout for request and response details.

Webhook Management — Dashboard Session ​

Webhook configuration uses /webhooks with dashboard authentication. See Webhook Management for every method, request/response, shared-secret behavior, polling, and test events. The Webhook Event Data reference documents all typed event payloads with field tables, examples, and a downloadable JSON Schema.

The generated Request and Response Fields reference tracks exact names, JSON types, serialization tags, and declared constraints for the current models, including public checkout and webhook management.

The generated Route Inventory lists the registered integration routes and their authentication boundaries, including legacy checkout, metadata, contact/assets, development helpers, and the session-protected mass-payout group.

Response Format ​

Merchant payment and subscription controllers generally return message and data:

json
{
  "message": "Payment link created successfully",
  "data": {
    "id": "22222222-2222-2222-2222-222222222222",
    "payment_status": "processing"
  }
}

Message-only responses omit data. Payment list results nest records at data.data and pagination at data.pagination. Subscription lists wrap their endpoint-specific list object in data. The checkout catalog, engine payer routes, and subscription prepare response are unwrapped JSON objects.

Error Handling ​

Use the HTTP status as the primary error indicator. Merchant controller errors generally return a message:

json
{
  "message": "Invalid payment link ID"
}

Authentication middleware also returns error and a string code, such as SIGNATURE_VERIFICATION_FAILED. Engine errors may return error and code; do not assume a numeric code or a uniform error envelope for every route.

Error Codes ​

CodeDescription
400Bad Request - Invalid parameters
401Unauthorized - Invalid API key
403Forbidden - Insufficient permissions
404Not Found - Resource doesn't exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error

Rate Limits ​

Rate limits are attached to individual routes. In this backend checkout, payment/default limiters are configured to 100 requests per minute. Merchant payment create/currency/catalog routes attach a limiter; list/get/status/delete do not attach a separate endpoint limiter. Subscription routes attach payment/default limiters. Limiter identity uses recognized user/API-key context, falling back to the client IP.

Handle HTTP 429, honor Retry-After when present, and use response rate-limit headers when available. Global middleware or infrastructure can impose additional limits; the backend does not define separate sandbox/production account ceilings of 100/1000 requests per minute.