Skip to main content
POST
/
api
/
v2
/
invoices
Create an invoice
curl --request POST \
  --url https://api.pawpayments.com/api/v2/invoices \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "amount": 1,
  "fiat_currency": "<string>",
  "asset": "<string>",
  "chain": "<string>",
  "extra": "<string>",
  "notify_url": "<string>",
  "ttl": 3600,
  "metadata": {},
  "title": "<string>",
  "description": "<string>",
  "underpay_tolerance": 5,
  "accepted_coins": [
    "<string>"
  ],
  "excluded_coins": [
    "<string>"
  ],
  "on_paid_url": "<string>",
  "on_cancel_url": "<string>",
  "price_modifier": 0,
  "fee_bearer": "client",
  "payer_info": {},
  "permanent_address": false,
  "user_id": "<string>"
}
'
{
  "ok": true,
  "result": {
    "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
  }
}

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
amount
required
Required range: x > 0
​
fiat_currency
string
required
​
billing_type
enum<string>
required

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.

Available options:
VARY,
STATIC
​
asset
string | null
​
chain
string | null
​
extra
string | null
Required string length: 1 - 64
Pattern: ^[A-Za-z0-9_-]{1,64}$
​
notify_url
string | null
Maximum string length: 500
​
ttl
integer
default:3600
Required range: 300 <= x <= 86400
​
metadata
Metadata · object
​
title
string | null
Maximum string length: 150
​
description
string | null
Maximum string length: 500
​
underpay_tolerance
number | null
Required range: 0 <= x <= 10
​
accepted_coins
string[] | null
​
excluded_coins
string[] | null
​
on_paid_url
string | null
Maximum string length: 500
​
on_cancel_url
string | null
Maximum string length: 500
​
price_modifier
number | null
Required range: -90 <= x <= 90
​
fee_bearer
enum<string>
default:client
Available options:
merchant,
client
​
payer_info
Payer Info · object
​
webhook_format
enum<string> | null
Available options:
native_v2,
cryptomus,
heleket,
nowpayments,
coinpayments,
coinpayments_v2
​
permanent_address
boolean
default:false

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.

​
user_id
string | null

External user identifier — required when permanent_address=true.

Required string length: 1 - 128

Response

Created

​
ok
boolean
required
​
result
Invoice · object
required
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
}