Create invoice
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, nestedmetadata(orderId, tip, posData JSON string, description), nestedbuyer(customer contact / billing fields),couponCode, andwebhook(URL notified on payment). The fieldsprQuantity,paymentRequestIdandlnurlpRequestIdare 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
Headers
Scope the request to a specific store / account instead of the one resolved from the API key. Aliases: the x-account-id header, or the application_account_id / account_id query parameter.
Query parameters
Payment method to pre-select on the new charge (a PaymentMethodsLike value). Omit it to let the store’s default resolve.
Request
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.