Tiankii Merchant API
Charge in Bitcoin and Lightning with one call — create a checkout invoice, render it, poll it, settle it
Checkout Invoice is the core of the TK Merchant API. Every payment your store collects — from a payment link, an invoice, a POS sale, or a direct integration — ends up as a checkout invoice on /v1/invoice: the actual Lightning or on-chain charge, with its amount, payment destination, exchange rates, status, and full event trail.
Creating one takes a single request. It returns a POS-ready payload with everything a checkout screen needs to render.
Send storeId as an empty string. Validation requires the field, but when you authenticate with an API key the store is resolved from the key and the value you send is overwritten.
Get your API key, store ID, and app ID, then make your first call
Every endpoint, parameter, and response — with live examples
The checkout flow
Create the charge
POST /v1/invoice with amount and currency. The response carries the invoice id, the hosted invoice URL, the resolved payment method, the crypto amount and destination, and the exchange rates. Pass a webhook URL to be called on payment, and metadata or buyer if you need to carry order context.
Render the checkout
GET /v1/invoice/:id/checkout returns the full checkout representation at any time — use it to rebuild the payment screen without recreating the charge. Need a different rail? PATCH /v1/invoice/:id/payment-method swaps it while the invoice is still New and recomputes the destination and amount.
Poll the status
GET /v1/invoice/:id/status is the lightweight poll for a checkout screen: it re-evaluates the invoice against the connector and returns only { status }. For an invoice that has been open a while, POST /v1/invoice/:id/recheck forces a one-shot deep check instead of waiting for the background sweep.
Settle and reconcile
Collected in cash? POST /v1/invoice/:id/mark-as-paid. Charge went wrong? POST /v1/invoice/:id/cancel moves it to Expired, and POST /v1/invoice/:id/reopen re-checks a closed invoice in case it was actually paid. GET /v1/invoice/:id/events gives you the full audit trail, and POST /v1/invoice/:id/notification re-sends the paid receipt by email.
What feeds a checkout invoice
The two ways to ask for money: a shareable payment link (PAYMENT_LINK) or an invoice issued to a customer (INVOICE). When someone pays one, a checkout invoice is generated.
/v1/payment-requests
Your buyers — contact details and addresses. They’re the recipients of the bills you issue.
/v1/customers
Your catalog: products, their modifiers, and the terminals where each one is sold.
/v1/products
Invoice vs. checkout invoice. An invoice is a payment request of type INVOICE — the bill that is issued, under /v1/payment-requests/billing-invoices. A checkout invoice is the /v1/invoice module — the charge that is executed. Two different objects.
Ready to start? Head to the getting started guide to create your credentials and make your first request.