Developer documentation

REST API & webhooks for Brionic Payments.

The Brionic Payments API creates crypto charges and invoices, manages customers, and pushes real-time webhooks. It's a JSON REST API that follows Stripe-style conventions closely enough that most tooling works out of the box.

Base URL

https://pay.brionicsecurity.com/api/v1

The public health check (no auth) lives at https://pay.brionicsecurity.com/api/health.

Authentication

Authenticate every request with a secret API key as a Bearer token. Create keys in your dashboard under Developers → API keys. A key is shown once: store it securely and never expose it in client-side code.

• sk_live_…, live keys settle real on-chain payments.
• sk_test_…, test keys for integration work.

curl https://pay.brionicsecurity.com/api/v1/charges \
  -H "Authorization: Bearer sk_live_your_key_here"

Requests without a valid key return 401 Unauthorized.

Errors & status codes

The API uses standard HTTP status codes. Errors return a JSON body with a message:

{
  "error": {
    "type": "invalid_request",
    "message": "Amount must be greater than zero."
  }
}

Code	Meaning
200 / 201	Success.
400 / 422	Invalid request or validation error.
401	Missing or invalid API key.
404	Resource not found.
429	Rate limited, slow down.

Charges

A charge is a single request for payment in a crypto asset. Each one has its own pay page, a QR code, and a unique destination tag (XRP/RLUSD) or memo id (XLM/USDC) that the watcher uses to match the payment back to it.

Method	Endpoint	Description
POST	/charges	Create a charge.
GET	/charges	List charges.
GET	/charges/{id}	Retrieve a charge.
POST	/charges/{id}/cancel	Cancel an open charge.

Create a charge, price it directly in crypto, or in fiat (auto-converted at the current rate):

curl https://pay.brionicsecurity.com/api/v1/charges \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": "XRP",
    "fiat_amount": "49.99",
    "fiat_currency": "USD",
    "description": "Pro plan",
    "success_url": "https://yoursite.com/thanks"
  }'

Response:

{
  "id": "ch_9f2c…",
  "object": "charge",
  "status": "pending",
  "asset": "XRP",
  "crypto_amount": "99.980000",
  "receive_address": "r…",
  "hosted_url": "https://pay.brionicsecurity.com/pay/ch_9f2c…",
  "expires_at": "2026-06-20 12:30:00"
}

Accepted assets: XRP, XLM, USDC, RLUSD. Provide either amount (crypto) or fiat_amount + fiat_currency, not both.

Invoices

An invoice is an itemized request for payment you can email to a customer. It wraps a long-lived charge and has its own branded pay page.

Method	Endpoint	Description
POST	/invoices	Create an invoice.
GET	/invoices	List invoices.
GET	/invoices/{id}	Retrieve an invoice.
POST	/invoices/{id}/send	Finalize & email the invoice.
POST	/invoices/{id}/void	Void an invoice.

curl https://pay.brionicsecurity.com/api/v1/invoices \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": "USDC",
    "customer_email": "[email protected]",
    "customer_name": "Jane Doe",
    "items": [
      { "description": "Design work", "quantity": 1, "unit_amount": "250" }
    ],
    "send": true
  }'

Customers

Method	Endpoint	Description
POST	/customers	Create a customer.
GET	/customers	List customers.
GET	/customers/{id}	Retrieve a customer.

Settlement (non-custodial)

Brionic is fully non-custodial. Every charge and invoice is addressed to your own wallet, so payments settle directly to you on-chain and Brionic never holds your funds. There is no platform balance and no payout step. Add a receiving wallet for each asset you accept under Wallets in your dashboard; a charge in an asset you have no wallet for is rejected. You can override the destination per charge by passing a receive_address.

Events

Method	Endpoint	Description
GET	/events	List recent events.
GET	/events/{id}	Retrieve an event.

Webhooks

Add HTTPS endpoint URLs under Developers → Webhooks. We POST a JSON event the instant something happens. Each endpoint has its own signing secret (whsec_…).

Event types include:

charge.created     charge.pending      charge.confirmed
charge.completed   charge.underpaid    charge.expired
payment.unverified
invoice.created    invoice.sent        invoice.paid       invoice.voided     invoice.scheduled

Verifying signatures

Each delivery includes a Brionic-Signature header so you can confirm it came from us and wasn't tampered with:

Brionic-Signature: t=1718900000,v1=<hex hmac_sha256("<t>.<rawBody>", whsec)>
Brionic-Event-Id: evt_…
Brionic-Event-Type: charge.completed

To verify: take the t value, concatenate t + "." + rawRequestBody, compute an HMAC-SHA256 with your endpoint's signing secret, and compare it to v1 in constant time. Reject timestamps that are too old (e.g. > 5 minutes) to prevent replays.

// PHP example
$payload = $_SERVER['HTTP_BRIONIC_SIGNATURE']; // "t=...,v1=..."
parse_str(str_replace(',', '&', $payload), $sig);
$expected = hash_hmac('sha256', $sig['t'] . '.' . file_get_contents('php://input'), $whsec);
if (hash_equals($expected, $sig['v1']) && abs(time() - (int) $sig['t']) < 300) {
    // ✓ trusted event, process it
}

Respond with a 2xx status to acknowledge. We retry failed deliveries with exponential backoff.

AI assistants (MCP server)

Brionic ships a Model Context Protocol server that exposes the API as tools an AI assistant (Claude Desktop, Cursor, and other MCP clients) can call in natural language. You can create charges and invoices, look up records, and manage pay-per-call endpoints in XRP, RLUSD, XLM, and USDC by asking. The MCP server is included on the Gold and Diamond plans. Download the MCP server (ZIP).

Tools include brionic_create_charge, brionic_get_charge, brionic_create_invoice, brionic_send_invoice, brionic_list_invoices, brionic_create_customer, brionic_list_events, brionic_create_x402_endpoint, and brionic_x402_fetch, each a thin wrapper over the REST endpoints above. Requires Node.js 18+ and an API key.

Add it to Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "brionic": {
      "command": "node",
      "args": ["/path/to/brionic-mcp/src/server.js"],
      "env": { "BRIONIC_API_KEY": "sk_test_…" }
    }
  }
}

Your API key stays on your machine; the server only talks to the Brionic API over HTTPS. Start on sk_test_…. Charges created with an sk_live_… key settle real on-chain payments.

Pay-per-call (x402)

Charge per request for an API or an AI-agent resource. A caller hits your endpoint at https://pay.brionicsecurity.com/x402/{slug}. If it hasn't paid, Brionic answers HTTP 402 Payment Required with machine-readable payment requirements backed by an on-chain charge. The caller pays (XRP, RLUSD, XLM, or USDC), then retries with an X-PAYMENT header to receive the resource, exactly once per payment. Create endpoints under Pay-per-call in your dashboard.

First request (unpaid) returns 402:

{
  "x402Version": 1,
  "error": "payment_required",
  "accepts": [{
    "scheme": "xrpl", "network": "mainnet", "asset": "XRP",
    "amount": "0.50", "payTo": "r…", "destinationTag": 12345,
    "paymentId": "ch_…", "payUrl": "https://pay.brionicsecurity.com/pay/ch_…"
  }],
  "instructions": "Pay payTo (with destinationTag/memo), then retry with header X-PAYMENT: ch_…"
}

After the charge settles on-chain, retry to unlock the resource:

curl https://pay.brionicsecurity.com/x402/premium-data \
  -H "X-PAYMENT: ch_…"
# → 200 OK, your configured JSON/text/redirect response

Built for the agent economy: an agent can pay for a tool call programmatically, settled natively on the XRP Ledger or Stellar. Manage endpoints via the dashboard, the REST API (GET/POST /api/v1/x402), or the MCP server (brionic_create_x402_endpoint, brionic_x402_fetch).

Verified payers (XRPL Credentials)

Nominate a trusted credential issuer on the XRP Ledger under Settings → Verified payers. When a payment settles on an XRP Ledger asset (XRP, RLUSD), Brionic reads the payer's on-chain Credential (XLS-70) from that issuer and stamps the payment as a Verified payer when the credential is present, accepted, and unexpired, a compliance/KYC attestation that travels with the payment, without Brionic ever handling the payer's private documents.

Provide the issuer address (r…) and a credential type (plain text such as KYC; Brionic hex-encodes it for the ledger lookup). The lookup is read-only and best-effort, and it never blocks or delays settlement. The result appears on the payment detail page and in the API (payer_verified, credential_detail).

Tick Flag payments from unverified payers to enforce the policy. When a payment settles from a payer who does not hold a valid credential, Brionic records it as unverified, emits a payment.unverified webhook, and emails the account owner so you can review it. Because settlement is non-custodial the funds are already in your wallet: Brionic never rejects or reverses the on-chain payment, and the flag is purely informational.

Account verification & plans

Brionic bills a flat monthly subscription (paid on-chain) rather than taking a percentage of each payment, so merchants keep 100% of what they're paid. A plan must be active before invoices can be sent, and the $1 Starter tier is what verifies the account. Each plan (Starter, Silver, Gold, Diamond) allows a set number of settled transactions per month. Manage your plan under Billing & plans in the dashboard.

Pay-per-call (x402) and the MCP server are included on the Gold and Diamond plans; the REST API and webhooks are available on every plan.

Brionic is non-custodial: payments settle straight to your own wallet for each asset (configured under Wallets), and funds never touch a platform-controlled address. There is nothing to hold and no payout to wait for. Add a receiving wallet for each asset you want to accept.

Plugins & integrations

Prefer not to write code? Drop-in integrations connect your store to Brionic and reconcile orders using the same signed webhooks described above.

WooCommerce

Download the plugin (ZIP) or see the WooCommerce overview. Then under WooCommerce → Settings → Payments → Brionic Payments:

• Paste a secret API key (sk_live_…) from Developers → API keys.
• Add a webhook endpoint in your dashboard pointing to https://your-store.com/wp-json/brionic/v1/webhook (events charge.completed, charge.underpaid, charge.expired) and paste its signing secret (whsec_…) into the plugin.
• Choose which coins to accept (XRP, XLM, USDC, RLUSD). Customers pick at checkout and pay on the hosted page; the order is marked paid on-chain.

Shopify

Download the connector (ZIP) or see the Shopify overview. Run the Brionic ⇄ Shopify connector and install it on your store. It uses the standard manual-payment pattern: a buyer who chooses your “Crypto” payment method places a pending order, the connector creates a Brionic charge and exposes a hosted pay link via an App Proxy, and when charge.completed arrives it marks the Shopify order paid through the Admin API. Point a webhook endpoint at https://your-connector/webhooks/brionic.

Square (customer import)

Already selling with Square? Under Integrations in your dashboard, connect Square with a read-only access token and sync your Square customer directory into Brionic (matched by email, re-runnable any time). Nothing in Square is changed. It just lets you start invoicing your existing customers in crypto. There's a dedicated overview at /square.

All integrations are non-custodial: funds settle to the wallet you configure in Brionic. Need a plugin for another platform? Ask us.

Need help?

Reach us through the support form or at [email protected].