> ## Documentation Index > Fetch the complete documentation index at: https://docs.pawpayments.com/llms.txt > Use this file to discover all available pages before exploring further. # Create an invoice > Creates a new invoice. If `asset` is omitted, the customer picks the currency on the hosted checkout (the deposit address is allocated only after the choice is made). ## OpenAPI ````yaml /api-reference/openapi.json post /api/v2/invoices openapi: 3.1.0 info: title: PawPayments API description: >- Public REST API for the PawPayments crypto payment gateway. All `/api/v2/*` endpoints require an `x-api-key` header issued in the merchant dashboard. Responses are wrapped in `{"ok": true, "result": ...}` on success and `{"ok": false, "error": {code, message, details?}}` on failure. version: 2.0.0 servers: - url: https://api.pawpayments.com description: Production security: - ApiKeyAuth: [] tags: - name: Catalog - name: Merchant - name: Invoices - name: Payouts - name: Notifications - name: Permanent addresses paths: /api/v2/invoices: post: tags: - Invoices summary: Create an invoice description: >- Creates a new invoice. If `asset` is omitted, the customer picks the currency on the hosted checkout (the deposit address is allocated only after the choice is made). operationId: post__api_v2_invoices parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateInvoiceV2.a1ea1bf' required: true responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/InvoiceEnvelope.d4a12ff' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope.d4a12ff' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope.d4a12ff' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope.d4a12ff' '422': description: Unprocessable Content content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope.d4a12ff' components: schemas: CreateInvoiceV2.a1ea1bf: properties: amount: anyOf: - exclusiveMinimum: 0 type: number - type: string title: Amount fiat_currency: title: Fiat Currency type: string asset: anyOf: - type: string - type: 'null' default: null title: Asset chain: anyOf: - type: string - type: 'null' default: null title: Chain extra: anyOf: - maxLength: 64 minLength: 1 pattern: ^[A-Za-z0-9_-]{1,64}$ type: string - type: 'null' default: null title: Extra billing_type: description: >- Invoice settlement mode. `STATIC` — fixed-price service purchase: the invoice expects exactly `amount`. An underpayment moves it to `partially_paid` (NOT finalized) so the client can top up to the full amount; the address keeps listening until the invoice expires or reaches `success`/`paid_over`. `VARY` — open-ended balance top-up: any incoming payment finalises the invoice (`success` if it covers `amount`, `partially_paid` (finalized) if less). Required value when `permanent_address=true`. enum: - VARY - STATIC title: Billing Type type: string notify_url: anyOf: - maxLength: 500 type: string - type: 'null' default: null title: Notify Url ttl: default: 3600 maximum: 86400 minimum: 300 title: Ttl type: integer metadata: anyOf: - type: object - type: 'null' default: null title: Metadata title: anyOf: - maxLength: 150 type: string - type: 'null' default: null title: Title description: anyOf: - maxLength: 500 type: string - type: 'null' default: null title: Description underpay_tolerance: anyOf: - maximum: 10 minimum: 0 type: number - type: 'null' default: null title: Underpay Tolerance accepted_coins: anyOf: - items: type: string type: array - type: 'null' default: null title: Accepted Coins excluded_coins: anyOf: - items: type: string type: array - type: 'null' default: null title: Excluded Coins on_paid_url: anyOf: - maxLength: 500 type: string - type: 'null' default: null title: On Paid Url on_cancel_url: anyOf: - maxLength: 500 type: string - type: 'null' default: null title: On Cancel Url price_modifier: anyOf: - maximum: 90 minimum: -90 type: number - type: 'null' default: null title: Price Modifier fee_bearer: default: client enum: - merchant - client title: Fee Bearer type: string payer_info: anyOf: - type: object - type: 'null' default: null title: Payer Info webhook_format: anyOf: - enum: - native_v2 - cryptomus - heleket - nowpayments - coinpayments - coinpayments_v2 - type: 'null' default: null title: Webhook Format permanent_address: default: false description: >- If true, bind this invoice to the permanent deposit address for (merchant, user_id, asset family). The address is created on first use and reused thereafter. Requires `billing_type=VARY` and a non-empty `user_id`. If `asset` is provided the address is allocated immediately; if omitted, the address is allocated when the customer selects a currency on the hosted checkout. XMR is not supported for permanent addresses. title: Permanent Address type: boolean user_id: anyOf: - maxLength: 128 minLength: 1 type: string - type: 'null' default: null description: External user identifier — required when `permanent_address=true`. title: User Id required: - amount - fiat_currency - billing_type title: CreateInvoiceV2 type: object InvoiceEnvelope.d4a12ff: properties: ok: const: true title: Ok type: boolean result: $ref: '#/components/schemas/InvoiceEnvelope.d4a12ff.Invoice' required: - ok - result title: InvoiceEnvelope type: object ErrorEnvelope.d4a12ff: example: error: code: VALIDATION_ERROR details: - field: amount message: Field required message: Validation failed ok: false properties: ok: const: false title: Ok type: boolean error: $ref: '#/components/schemas/ErrorEnvelope.d4a12ff.ErrorBody' required: - ok - error title: ErrorEnvelope type: object InvoiceEnvelope.d4a12ff.Invoice: example: accepted_coins: - usdt_tron - usdc_eth address_from: null address_to: TXk2Y5...redacted amount: 49.5 asset: usdt_tron billing_type: fiat created_at: 1763398800 description: 1 month subscription excluded_coins: null expires_at: 1763400600 external_id: f2c8a3d1-4b7e-4f8a-9c1d-2e3b4a5c6d7e extra: order-12345 fee_bearer: merchant fiat_amount: 50 fiat_currency: USD initial_amount: 49.5 initial_asset: usdt_tron initial_fiat_amount: 50 metadata: customer_id: u_42 notify_url: https://shop.example.com/webhook/paw on_cancel_url: https://shop.example.com/cancel on_paid_url: https://shop.example.com/thanks order_id: 65f1c3a4e8b1c2d3a4b5c6d7 original_amount: 50 payer_info: null payment_url: >- https://pay.pawpayments.com/checkout/f2c8a3d1-4b7e-4f8a-9c1d-2e3b4a5c6d7e permanent_address_id: null price_modifier: -1 processed_at: null received_amount: 0 status: created title: Premium plan txid: null type: token underpay_tolerance: 0.01 user_id: null properties: order_id: description: Unique 24-character hex invoice id. title: Order Id type: string external_id: anyOf: - type: string - type: 'null' default: null description: Public checkout id (UUID). title: External Id status: anyOf: - type: string - type: 'null' default: null description: >- One of: created, confirming, partially_paid, paid_over, success, failed, high_risk, expired, cancelled, refunded. Terminal-expiry split: `cancelled` is reachable only from `partially_paid` + `billing_type=STATIC` (merchant was already credited the partial amount at AML time; the credit is kept on expiry — `cancelled` reports the final under-paid state without reversal). Everything else still in `created` at TTL (including the sub-$2 tiny-payment deferral path that stored `received_amount` without enqueueing AML) → `expired`. `partially_paid` + `billing_type=VARY` is terminal at AML time and never transitions on TTL. title: Status asset: anyOf: - type: string - type: 'null' default: null title: Asset initial_asset: anyOf: - type: string - type: 'null' default: null description: >- Asset originally requested at invoice creation. Immutable after first assignment — if the customer changes the payment currency on the hosted checkout, `asset` reflects the new choice while `initial_asset` keeps the original one. title: Initial Asset type: anyOf: - type: string - type: 'null' default: null description: 'Asset type: `native` or `token`.' title: Type amount: anyOf: - type: number - type: 'null' default: null description: Originally requested amount in `asset`. title: Amount initial_amount: anyOf: - type: number - type: 'null' default: null description: >- Snapshot of the originally requested crypto amount (immutable; equals `amount`). title: Initial Amount fiat_amount: anyOf: - type: number - type: 'null' default: null description: >- Cumulative amount paid in `fiat_currency`. Updated on each on-chain payment. title: Fiat Amount initial_fiat_amount: anyOf: - type: number - type: 'null' default: null description: >- Originally requested amount in `fiat_currency` (immutable; useful when `fiat_amount` becomes a partial sum). title: Initial Fiat Amount fiat_currency: anyOf: - type: string - type: 'null' default: null title: Fiat Currency billing_type: anyOf: - type: string - type: 'null' default: null description: >- Settlement mode: `STATIC` (fixed-price service — `partially_paid` keeps the invoice open for top-ups until `success`/`paid_over`/`expires_at`) or `VARY` (any incoming payment finalises the invoice — used for balance top-ups and for invoices bound to permanent addresses). title: Billing Type address_to: anyOf: - type: string - type: 'null' default: null title: Address To address_from: anyOf: - type: string - type: 'null' default: null description: Sender address of the (last) on-chain payment, when known. title: Address From extra: anyOf: - type: string - type: 'null' default: null title: Extra title: anyOf: - type: string - type: 'null' default: null title: Title description: anyOf: - type: string - type: 'null' default: null title: Description expires_at: anyOf: - type: integer - type: 'null' default: null description: Unix timestamp when the invoice stops accepting new deposits. title: Expires At metadata: anyOf: - type: object - type: 'null' default: null title: Metadata fee_bearer: anyOf: - type: string - type: 'null' default: null title: Fee Bearer underpay_tolerance: anyOf: - type: number - type: 'null' default: null title: Underpay Tolerance accepted_coins: anyOf: - items: type: string type: array - type: 'null' default: null title: Accepted Coins excluded_coins: anyOf: - items: type: string type: array - type: 'null' default: null title: Excluded Coins on_paid_url: anyOf: - type: string - type: 'null' default: null title: On Paid Url on_cancel_url: anyOf: - type: string - type: 'null' default: null title: On Cancel Url notify_url: anyOf: - type: string - type: 'null' default: null title: Notify Url price_modifier: anyOf: - type: number - type: 'null' default: null title: Price Modifier original_amount: anyOf: - type: number - type: 'null' default: null description: Set only when price_modifier was applied. title: Original Amount payer_info: anyOf: - type: object - type: 'null' default: null title: Payer Info permanent_address_id: anyOf: - type: string - type: 'null' default: null description: Set only on deposit invoices auto-created from a permanent address. title: Permanent Address Id user_id: anyOf: - type: string - type: 'null' default: null description: >- Set only on deposit invoices auto-created from a permanent address (copied from the address). title: User Id received_amount: anyOf: - type: number - type: 'null' default: null description: Cumulative crypto amount actually received on-chain. title: Received Amount txid: anyOf: - type: string - type: 'null' default: null description: >- Hash of the (last) transaction that contributed to this invoice. Set after a successful on-chain payment. title: Txid payment_url: anyOf: - type: string - type: 'null' default: null title: Payment Url webhook_format: anyOf: - type: string - type: 'null' default: null title: Webhook Format created_at: anyOf: - type: integer - type: 'null' default: null description: Unix timestamp (seconds). title: Created At processed_at: anyOf: - type: integer - type: 'null' default: null description: >- Unix timestamp when the invoice transitioned to a paid status (success / partially_paid / paid_over). title: Processed At required: - order_id title: Invoice type: object ErrorEnvelope.d4a12ff.ErrorBody: properties: code: description: Machine-readable error code (e.g. NOT_FOUND, VALIDATION_ERROR). title: Code type: string message: title: Message type: string details: anyOf: - {} - type: 'null' default: null description: >- Optional context. For VALIDATION_ERROR contains a list of {field, message}. title: Details required: - code - message title: ErrorBody type: object securitySchemes: ApiKeyAuth: type: apiKey name: x-api-key in: header ````