> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.tiankii.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.tiankii.com/_mcp/server.

# Tiankii Merchant API

**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.

```bash
curl -X POST https://api.md.tiankii.com/v1/invoice \
  -H "x-api-key: $TIANKII_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 1.5, "currency": "USD", "storeId": "" }'
```

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 started](/docs)

Get your API key, store ID, and app ID, then make your first call

#### [API Reference](/api-reference)

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

#### Payment Requests

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`

#### Customers

Your buyers — contact details and addresses. They're the recipients of the bills you issue.

`/v1/customers`

#### Products

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](/docs) to create your credentials and make your first request.