TillsafeDocstillsafe.comRequest early access

Invoices

Requests for payment

GET /v1/invoices

List invoices, newest first.

Authentication: Secret key

Parameters

ParameterInTypeDescription
limitqueryinteger (int32)

1 to 100, default 10

  • Minimum: 0
cursorquerystring

next_cursor from the previous page

statusqueryInvoiceStatus

Only invoices in this status

customer_refquerystring

Only invoices for this customer reference

Responses

StatusDescriptionBody
200
InvoiceList application/json
400
ErrorResponse application/json

POST /v1/invoices

Create an invoice.

Prices are fiat decimal strings; each accepted asset gets its own exact amount due. Deposit addresses are exclusive to the invoice but may be shared between its options: all of its EVM options use one address, the same on every EVM network. Requires an Idempotency-Key.

Authentication: Secret key

Parameters

ParameterInTypeDescription
Idempotency-Keyrequiredheaderstring

Unique per logical operation; retries with the same key are safe.

Request body

application/json

CreateInvoiceRequest

FieldTypeDescription
amountrequiredstring

Price in major units of currency, as a decimal string.

  • Example: "30.00"
currencyrequiredstring

ISO 4217 code of the price.

  • Example: "USD"
assetsarray of string or null

Assets the payer may use. Defaults to the merchant's default_assets.

descriptionstring or null

Shown to the payer. At most 500 characters.

customer_refstring or null

Your reference for the customer. At most 200 characters. Never shown to the payer.

metadatamap of string or null

Up to 20 pairs; keys at most 40 characters, values at most 500. Never shown to the payer.

Responses

StatusDescriptionBody
201

Created

Invoice application/json
400

Invalid request

ErrorResponse application/json
401

No valid API key

ErrorResponse application/json
409

Idempotency-Key reused or in flight

ErrorResponse application/json

GET /v1/invoices/{id}

Retrieve an invoice.

Authentication: Secret key

Parameters

ParameterInTypeDescription
idrequiredpathstring

Invoice id (inv_…)

Responses

StatusDescriptionBody
200
Invoice application/json
404

No such invoice in this mode

ErrorResponse application/json

POST /v1/invoices/{id}/cancel

Cancel an invoice nobody has paid.

Only while nothing has been seen for it (awaiting_payment with no payment at all). The deposit address stops being offered and goes into its cooldown, where a transfer that still arrives is attributed to this invoice and becomes refundable. Idempotent: cancelling a cancelled invoice returns it unchanged. Sends invoice.cancelled.

Authentication: Secret key

Parameters

ParameterInTypeDescription
idrequiredpathstring

Invoice id (inv_…)

Idempotency-Keyrequiredheaderstring

Unique per request

Responses

StatusDescriptionBody
200

Cancelled

Invoice application/json
404

No such invoice in this mode

ErrorResponse application/json
409

A payment was already seen, or the invoice is paid or expired (invoice_not_cancellable)

ErrorResponse application/json

POST /v1/invoices/{id}/resolve_review

Accept or reject a held payment.

An invoice is under_review when a payment was held for a person to look at (for example, one at or above the manual-review amount). accept credits what was held, exactly once, and the invoice moves on (usually to paid). reject cancels the invoice and leaves everything received refundable. Sends invoice.review_resolved and the status webhook (invoice.paid, invoice.cancelled, ...).

In live mode an API key may accept only amount-threshold holds (manual_review); accepting a risk hold (sanctions, blacklist, a finality violation) needs a person on the dashboard (review_requires_dashboard). Rejecting is always allowed.

Authentication: Secret key

Parameters

ParameterInTypeDescription
idrequiredpathstring

Invoice id (inv_…)

Idempotency-Keyrequiredheaderstring

Unique per request

Request body

application/json

ResolveReviewRequest

FieldTypeDescription
decisionrequiredReviewDecision
reasonrequiredstring

Why, for your records and the webhook (1 to 500 characters).

  • Example: "Customer verified by phone"

Responses

StatusDescriptionBody
200

Resolved

Invoice application/json
400
ErrorResponse application/json
404

No such invoice in this mode

ErrorResponse application/json
409

No open review (review_not_open), or a live risk hold that needs the dashboard (review_requires_dashboard)

ErrorResponse application/json