Get started

Getting started

Get your credentials, understand the model, and make your first call
View as Markdown

This guide takes you from an empty terminal to a working payment link. It covers authentication, the identifiers the API expects, and how the four modules fit together.

On this page

1. Get your credentials

Create an API key and find your store_id and app_id

2. Authenticate

Send your key on every request, and scope it to a store

3. How the modules fit together

Checkout Invoice, Customers, Products, and Payment Requests

4. Make your first call

Create a payment link and share its URL

5. Typical flows

Bill a customer, sell through a link, reconcile a charge

Next: the checkout flow

What the payer sees, and the API call behind every screen

1. Get your credentials

Register or log in to the merchant portal at pay.tiankii.com. You can sign up with a phone number, an email address, or single sign-on via Google, Microsoft, or Twitter.

1

Create your API key

Go to Store settings → Development Workspace and click Create API Key. Fill in the form, then click Copy Secret.

Copy the secret before you leave the screen. The list only ever shows a masked preview, so once you navigate away there is no way to recover the full value — you’d have to create a new key.

2

Get your store_id

Your Store ID is shown in the Credentials card, under Store ID — it identifies your store in every API request. Click the copy icon to grab it.

3

Get your app_id

In the same Credentials card, open the Select app dropdown and pick the application you’re integrating. Its identifier appears below as Selected App ID, ready to copy.

This is the value that app-scoped endpoints expect. If you work with more than one app, repeat the selection for each.

What each identifier is for

VariableWhere it goesWhat it identifies
api_keyx-api-key headerYour merchant account. Authenticates every request.
store_idRequest bodyYour store or merchant account on the platform.
app_idRequest bodyThe specific application, sale terminal, or POS the transaction belongs to.
pay_method_idRequest bodyThe payment method to process or enable for the transaction.

2. Authenticate

Every request sends your key in the x-api-key header:

$curl https://api.md.tiankii.com/v1/customers \
>  -H "x-api-key: $TIANKII_API_KEY"

x-account-api-key works as an alias for x-api-key. To scope a key to a specific store or account, send x-application-account-id (alias x-account-id), or pass it as the application_account_id / account_id query parameter.

Never expose your x-api-key in public repositories, browsers, or any client-side code. Treat it like a password — it authenticates as your merchant account.

3. How the modules fit together

ModuleBaseWhat it holds
Checkout Invoice/v1/invoiceThe Lightning or on-chain charge generated when someone actually pays.
Customers/v1/customersYour buyers. email is unique per store. They’re the recipients of the invoices you issue.
Products/v1/productsYour catalog, its modifiers, and the places (apps / terminals) where each product is sold.
Payment Requests/v1/payment-requestsThe aggregate you use to collect payment. Its type is PAYMENT_LINK, INVOICE, or SUBSCRIPTION.

Each module’s reference section opens with a detailed overview — scopes, constraints, and related routes. Start with the API Reference once you’ve made your first call.

Invoices vs. checkout invoices. An invoice is a payment request of type INVOICE — the bill that is issued, living under /v1/payment-requests/billing-invoices. A checkout invoice is the /v1/invoice module — the charge that is executed. Two different objects.

4. Make your first call

The fastest way to get paid is a payment link: create it once, share the URL, collect one or many payments.

$curl -X POST https://api.md.tiankii.com/v1/payment-requests/links \
>  -H "x-api-key: $TIANKII_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "title": "Dinner for two",
>    "description": "Table service, includes tip",
>    "amount": 49.99,
>    "currency": "USD",
>    "quantity": 1,
>    "allowCustomQuantity": false,
>    "buttonText": "Pay now",
>    "showConfirmPage": true,
>    "redirectUrl": "https://merchant.example.com/thanks"
>  }'

Every other endpoint follows the same shape. The API Reference has a runnable example for each one.

5. Typical flows

  1. POST /v1/customers — create the customer, or find them with GET /v1/customers.
  2. POST /v1/payment-requests/billing-invoices — create the bill against that customerId.
  3. POST /v1/payment-requests/billing-invoices/:id/send — email it to one or more recipients.
  4. GET /v1/payment-requests/billing-invoices/:id/pdf — download the PDF if you need a copy.
  5. When the customer pays, a checkout invoice is generated. Track it with GET /v1/invoice/:id and GET /v1/invoice/:id/events.
  6. PATCH /v1/payment-requests/:id/complete — close out the payment request.
  1. GET /v1/invoice — list charges.
  2. GET /v1/invoice/:id/events — inspect the full event trail for one charge.
  3. PATCH /v1/invoice/:id/reopen or PATCH /v1/invoice/:id/cancel — correct a charge that went wrong.
  4. POST /v1/invoice/:id/notification — re-send the paid-invoice notification.

Where to next

Checkout flow

Follow a payment through the hosted checkout — payment method, QR, wallet, receipt — and the API call behind each screen

API Reference

Every endpoint, parameter, and response, with a runnable example for each