Overview

The Solverr REST API creates invoices, payment links, refunds, payouts, subscriptions and credits. Your server calls it with an API key, and checkouts and paying agents call its public endpoints without one.

Base URLCopy Anchor Link

The base URL is the address of your Solverr app followed by /api/v1. In these docs, your-solverr-host stands for that address. Replace it with yours, such as pay.example.com.

https://your-solverr-host/api/v1

Every endpoint lives under this base URL. Requests and responses are JSON, and amounts are decimal strings such as "25.00".

AuthenticationCopy Anchor Link

Business endpoints need your API key as a bearer token:

curl https://your-solverr-host/api/v1/invoices \
  -H "Authorization: Bearer sk_live_…"

API keys start with sk_live_. The owner of the business creates them in Dashboard → Developers after verifying the payout wallet. Every request with an API key works on real payments, so keep the key on your server.

Each key is shown only once; Solverr stores only a hash and the last 4 characters. You can revoke a key in Dashboard → Developers, after which it returns 401 at once.

Public checkout endpointsCopy Anchor Link

The endpoints the checkout page uses take no key, need only an invoice id and never return anything private to you, so agents and custom checkouts can call them too. They allow cross-origin requests from any site (no cookies are sent), so a custom checkout can call them from the customer's browser.

EndpointsCopy Anchor Link

Each endpoint page shows its parameters, an example request and the possible responses, and can send a request from your browser.

ErrorsCopy Anchor Link

Every error has the same shape:

{
  "error": {
    "type": "invalid_request",
    "message": "amount must be a decimal string with up to 2 decimals, such as \"25.00\".",
    "param": "amount"
  }
}

param is present when one field or header caused the error. message is a sentence you can log or show.

Checkout endpoints add a code to the invalid_state errors for a paid invoice, an expired invoice and a payment in progress: invoice_paid, invoice_expired or payment_in_progress. A 429 for an invoice that reached its 10 new payment addresses in an hour carries too_many_attempts, and its Retry-After can be up to an hour. A 429 for a payment that already has 5 support cases from the last 24 hours also carries too_many_attempts, with a Retry-After of up to a day. Use the code when you show your own text instead of message.

Request bodies are strict: an unknown field returns 400. The POST endpoints that take no body (redeem an invoice, cancel a refund or payout, refund a credit charge and POST /api/v1/webhooks/test) ignore the fields of a body you send, but the body must still be valid JSON. A wrong HTTP method on an existing path is the one exception to the error shape: it returns 405 without a body.

IdempotencyCopy Anchor Link

To retry a POST safely after a network error, send an Idempotency-Key header with a unique string of 1 to 255 characters for that operation, such as invoice-order-1042.

curl https://your-solverr-host/api/v1/invoices \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-order-1042" \
  -d '{"amount":"25.00","currency":"USD","order_id":"1042"}'

• The same key on the same endpoint with the same body returns the stored response with the header Idempotent-Replayed: true, and no second invoice is created.
• The same key with a different body, or on another endpoint, returns 409 idempotency_conflict.
• While the first request with a key is still running, the same key returns 409 idempotency_conflict with Retry-After: 1. The request never runs twice; wait a moment and retry.
• Only successful responses are stored. When a request ends with an error, the key is released and you can retry with it.
• Keys belong to your business across every endpoint, are shared by all your API keys and are kept for 24 hours. Give each operation its own key, for example invoice-order-1042 for the invoice of order 1042 and refund-order-1042 for its refund, not the order id alone.

These endpoints read the header: create an invoice, payment link, refund, payout, payout batch or subscription; redeem an invoice; cancel a refund or payout; the three credits endpoints (top up, charge and refund a charge); and POST /api/v1/webhooks/test.

PaginationCopy Anchor Link

List endpoints return the newest objects first:

{ "object": "list", "data": [], "has_more": true }

To read every page, repeat the call with starting_after set to the last id of the previous page, until has_more is false.

curl "https://your-solverr-host/api/v1/invoices?limit=50&starting_after=inv_7h3K9dWq2LmN4pRt6vXy" \
  -H "Authorization: Bearer sk_live_…"

Rate limitsCopy Anchor Link

Most limits count requests in fixed 60-second windows; the table names the other window lengths. Over a limit, the API returns 429 rate_limited with a Retry-After header that gives the seconds until the window resets. Wait that long before you try again.

A network is an IPv4 address or an IPv6 /48; a single IP address is an IPv4 address or an IPv6 /64.

Invoice amounts and lifetimeCopy Anchor Link

• amount is a decimal string with up to 2 decimals, and currency is USD, EUR or INR.
• The settlement amount is fixed when the invoice is created. EUR and INR are converted to USD at the ECB reference rates, which the ECB publishes once per working day and Solverr reads again every hour. USDC, USDT and DAI count as 1 USD; other coins use their current USD price.
• An invoice lives 60 minutes by default. Set expires_in from 900 seconds (15 minutes) to 86400 seconds (24 hours).
• metadata takes up to 20 keys of your own, with keys up to 40 characters and values up to 500.