Solverr

Invoices

Create an invoice

Creates an invoice and returns its checkout_url. Send the customer to that URL to pay. The settlement amount (what the business receives) is fixed when the invoice is created. EUR and INR are converted to USD with ECB reference rates; USDC, USDT and DAI count as 1 USD; other settlement coins use the current USD price. Rate limit: 1200 per minute per API key, counted separately from other endpoints.

POST
/api/v1/invoices

Authorization

bearerAuth
headerAuthorizationBearer <token>

A live API key, sk_live_ followed by 32 base58 characters.

Header Parameters

Idempotency-Key?string

A unique string of 1 to 255 characters for this operation. A key belongs to the business across every endpoint for 24 hours, so give each operation its own key, for example invoice-order-1042 and refund-order-1042, not the order id alone. A retry with the same key on the same endpoint and with the same body returns the stored response with the header Idempotent-Replayed: true. The same key with a different body or on another endpoint returns 409 idempotency_conflict. Errors are not stored, so a request that failed can be retried with the same key, even with a corrected body. While the first request with a key is still running, a retry gets 409 idempotency_conflict with Retry-After: 1.

Length1 <= length <= 255

Request Body

application/json
  1. body
amount*Amount

Decimal string with up to 2 decimals, greater than 0.

Match^\d{1,12}(\.\d{1,2})?$
currency*Currency
Value in"USD""EUR""INR"
order_id?string

Your own order reference.

Length1 <= length <= 200
description?string

Your own note about what the invoice is for. Your dashboard and Telegram messages show it; the hosted checkout page does not.

Length1 <= length <= 500
redirect_url?string

An http or https URL the customer returns to after paying.

Formaturi
Lengthlength <= 2048
customer_email?string

Where the receipt is sent when email is configured. Without it, the customer can enter one on the checkout page.

Formatemail
metadata?

Up to 20 keys of your own. Keys are at most 40 characters and values at most 500.

Propertiesproperties <= 20
expires_in?integer

Invoice lifetime in seconds, from 15 minutes to 24 hours.

Range900 <= value <= 86400
Default3600

Response Body

The invoice was created.

application/json
  1. response
id*string
object*string
mode*Mode

Always live on the objects your API key creates and reads. Only demo store invoices, seen through the public checkout endpoints, are test.

Value in"live""test"
status*InvoiceStatus
Value in"created""awaiting_payment""detected""processing""paid""underpaid""refunded""failed""expired"
amount*string

Decimal string with 2 decimals.

currency*Currency
Value in"USD""EUR""INR"
order_id*string|null
description*string|null
customer_email*|

Where the receipt is sent. When you created the invoice without one, anyone with the checkout link can enter it on the checkout page, so it is not a verified identity of the customer.

redirect_url*string|null
metadata*
settlement*

The coin and amount the business receives.

late*boolean

True when the payment arrived on a deposit address that was already replaced or expired.

extra_payment*boolean

True when a second payment also succeeded for this invoice.

checkout_url*string

The hosted checkout page for this invoice.

Formaturi
receipt_url*|

The public receipt page, once the invoice is paid.

Formaturi
redeemed_at*|

When the payment was used with POST /api/v1/invoices/{id}/redeem; a used payment cannot be redeemed again.

Formatdate-time
expires_at*string
Formatdate-time
created_at*string
Formatdate-time
Example Request
curl -X POST 'https://example.com/api/v1/invoices' \  -H 'Content-Type: application/json' \  -d '{  "amount": "25.00",  "currency": "USD",  "order_id": "1042",  "description": "Blue T-shirt",  "redirect_url": "https://shop.example/thanks"}'
Example Response
{  "id": "inv_7h3K9dWq2LmN4pRt6vXy",  "object": "invoice",  "mode": "live",  "status": "created",  "amount": "string",  "currency": "USD",  "order_id": "string",  "description": "string",  "customer_email": "string",  "redirect_url": "string",  "metadata": {    "property1": "string",    "property2": "string"  },  "settlement": {    "asset_id": "string",    "symbol": "string",    "blockchain": "string",    "amount": "string",    "amount_base": "string"  },  "late": true,  "extra_payment": true,  "checkout_url": "http://example.com",  "receipt_url": "http://example.com",  "redeemed_at": "2019-08-24T14:15:22Z",  "expires_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z"}