Create invoice

Creates a new invoice for the given store and returns a POS-ready payload (InvoicePosDto) containing the invoice id, hosted invoice URL, resolved payment method, crypto amount / destination and exchange rates.

Auth

Send the merchant API key in the x-api-key header (alias x-account-api-key). The key must carry Merchant.invoice.create. Also accepts JWT user, POS JWT and Google-signed tokens. Optionally scope the key to a specific account/store with the x-application-account-id header (alias x-account-id) or the application_account_id query param.

Query params

paymentMethod (optional): id of the default payment method to pre-select for this invoice.

Body

CreateInvoiceDto (JSON). Required: amount, currency, storeId.

⚠️ About storeId: when you authenticate with an API key the store is taken from the key, and the handler overwrites whatever you send (data.storeId = user.store_id). The field is nonetheless declared @IsNotEmpty(), so the validation pipe rejects the request if you omit it. Send it empty — the value has no effect. Optional: appId, nested metadata (orderId, tip, posData JSON string, description), nested buyer (customer contact / billing fields), couponCode, and webhook (URL notified on payment). The fields prQuantity, paymentRequestId and lnurlpRequestId are internal linking fields.

Side effects

Persists a new Invoices record in status new, resolves the exchange rate and payment destination, and — if a webhook is supplied — registers it for payment callbacks. Unknown body properties are stripped by the global validation pipe.

Notas: storeId is required by validation but ignored for API-key callers (overwritten in createdInvoiceByUser when the principal is not POS/limited). Response type is InvoicePosDto. The DTO exposes deprecated aliases (rate, satsDue, cryptoCode, btcAddress, nationalRate, invoiceWallet, btcDue) kept for backward compatibility — prefer exchangeRate, cryptoAmount, paymentType, paymentDestination, usdExchangeRate.

## Create invoice Creates a new invoice for the given store and returns a POS-ready payload (`InvoicePosDto`) containing the invoice id, hosted invoice URL, resolved payment method, crypto amount / destination and exchange rates. ### Auth Send the merchant API key in the `x-api-key` header (alias `x-account-api-key`). The key must carry **`Merchant.invoice.create`**. Also accepts JWT user, POS JWT and Google-signed tokens. Optionally scope the key to a specific account/store with the `x-application-account-id` header (alias `x-account-id`) or the `application_account_id` query param. ### Query params - `paymentMethod` (optional): id of the default payment method to pre-select for this invoice. ### Body `CreateInvoiceDto` (JSON). Required: `amount`, `currency`, `storeId`. > ⚠️ **About `storeId`**: when you authenticate with an API key the store is taken from the key, and the handler overwrites whatever you send (`data.storeId = user.store_id`). The field is nonetheless declared `@IsNotEmpty()`, so the validation pipe rejects the request if you omit it. Send it empty — the value has no effect. Optional: `appId`, nested `metadata` (orderId, tip, posData JSON string, description), nested `buyer` (customer contact / billing fields), `couponCode`, and `webhook` (URL notified on payment). The fields `prQuantity`, `paymentRequestId` and `lnurlpRequestId` are internal linking fields. ### Side effects Persists a new `Invoices` record in status `new`, resolves the exchange rate and payment destination, and — if a `webhook` is supplied — registers it for payment callbacks. Unknown body properties are stripped by the global validation pipe. --- **Notas:** storeId is required by validation but ignored for API-key callers (overwritten in createdInvoiceByUser when the principal is not POS/limited). Response type is InvoicePosDto. The DTO exposes deprecated aliases (rate, satsDue, cryptoCode, btcAddress, nationalRate, invoiceWallet, btcDue) kept for backward compatibility — prefer exchangeRate, cryptoAmount, paymentType, paymentDestination, usdExchangeRate.

Authentication

x-api-keystring

API Key authentication via header

Query parameters

paymentMethodstringOptional

Payment method to pre-select on the new charge (a PaymentMethodsLike value). Omit it to let the store’s default resolve.

Request

This endpoint expects an object.

amountdoubleRequired

currencystringRequired

storeIdstringRequired

Leave it empty: when authenticating with an API key the store is resolved from the key and the handler overwrites whatever you send (data.storeId = user.store_id), so the value has no effect.

Create invoice

Auth

Query params

paymentMethod (optional): id of the default payment method to pre-select for this invoice.

Body

CreateInvoiceDto (JSON). Required: amount, currency, storeId.

⚠️ About storeId: when you authenticate with an API key the store is taken from the key, and the handler overwrites whatever you send (data.storeId = user.store_id). The field is nonetheless declared @IsNotEmpty(), so the validation pipe rejects the request if you omit it. Send it empty — the value has no effect. Optional: appId, nested metadata (orderId, tip, posData JSON string, description), nested buyer (customer contact / billing fields), couponCode, and webhook (URL notified on payment). The fields prQuantity, paymentRequestId and lnurlpRequestId are internal linking fields.

$	curl -X POST "https://api.md.tiankii.com/v1/invoice?paymentMethod=BTC_StrikeLike" \
>	-H "x-application-account-id: acct_3f9a21c7" \
>	-H "x-api-key: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"amount": 1.5,
>	"currency": "USD",
>	"storeId": ""
>	}'

Create invoice

Auth

Query params

Body

Side effects

Authentication

Headers

Query parameters

Request

Create invoice

Auth

Query params

Body

Side effects