{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","tabs","tab","cards","card"]},"type":"markdown"},"seo":{"title":"Invoices - Crypto Payment Tracking","projectTitle":"Vilna Docs","description":"Create payment invoices, track incoming transactions, handle partial and overpayments, and share public payment pages using the Vilna API.","siteUrl":"https://docs.vilna.io","keywords":["crypto asset management","blockchain monitoring","digital asset security","cryptocurrency API","wallet tracking","blockchain analytics","enterprise crypto","real-time blockchain","CAIP-19","BIP44"],"lang":"en-US","image":"https://cdn.vilna.io/docs/previews/guides.png","meta":[{"name":"og:type","content":"website"},{"name":"og:site_name","content":"Vilna Documentation"},{"name":"og:image:width","content":"1200"},{"name":"og:image:height","content":"630"},{"name":"twitter:card","content":"summary_large_image"}],"llmstxt":{"title":"Vilna API Documentation","description":"Vilna is a blockchain monitoring and wallet management platform. It provides a single unified REST API for tracking addresses, transactions, balances, and activity across top blockchains - Bitcoin, Ethereum, Solana, TRON, TON, Cosmos, and others. The API uses CAIP-2/CAIP-19 standards for cross-chain identification, HD wallet management (BIP-32/44) for address derivation, and RFC 7807 for error responses. Authentication is via API key in the X-Api-Key header.\n","excludeFiles":["legal/**/*.md","@l10n/**/*.md"],"sections":[{"title":"Overview","description":"What Vilna is, supported blockchains, and target audience","includeFiles":["overview.md"],"excludeFiles":[]},{"title":"Getting Started","description":"Quickstart guide and core API concepts","includeFiles":["guides/quickstart.md","guides/dashboard.md","guides/core-concepts.md","guides/authentication.md"],"excludeFiles":[]},{"title":"API Reference","description":"Platform API and Management API endpoint documentation","includeFiles":["apis/platform/index.md","apis/mgmt/index.md","apis/rpc/index.md","apis/platform/api.yaml","apis/mgmt/api.yaml"],"excludeFiles":[]},{"title":"Developer Guides","description":"Integration patterns, events, notifications, SDK, and error handling","includeFiles":["guides/events.md","guides/channels.md","guides/integration-patterns.md","guides/sdk.md","guides/mcp.md","guides/errors.md","guides/simulation.md","guides/invoices.md"],"excludeFiles":[]},{"title":"Business","description":"Value proposition, use cases, and onboarding","includeFiles":["business/index.md","business/use-cases.md"],"excludeFiles":[]},{"title":"Optional","description":"Additional reference material","includeFiles":["guides/blockchain-basics.md","guides/faq.md","apis/mgmt/guide.md","guides/widget.md","guides/storage-client.md","apis/platform/caip-standards.md","apis/mgmt/authorization.md"],"excludeFiles":[]}],"hide":false},"priority":0.7,"jsonLd":{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://docs.vilna.io/"},{"@type":"ListItem","position":2,"name":"Guides"},{"@type":"ListItem","position":3,"name":"Invoices"}]},{"@type":"TechArticle","headline":"Invoices - Crypto Payment Tracking","description":"Create payment invoices, track incoming transactions, handle partial and overpayments, and share public payment pages using the Vilna API.","url":"https://docs.vilna.io/guides/invoices","datePublished":"2026-01-15","dateModified":"2026-05-26","proficiencyLevel":"Intermediate","image":"https://cdn.vilna.io/docs/previews/guides.png","author":{"@id":"https://vilna.io/#organization"},"publisher":{"@id":"https://vilna.io/#organization"}}]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"invoices","__idx":0},"children":["Invoices"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Invoices let you request crypto payments to a specific address for a specific token amount. Vilna tracks incoming transactions in real time, detects partial payments, overpayments, and confirms payments once they reach the required block depth. Each invoice has a public URL you can share with payers - no authentication required on their end. To see how invoices fit into a broader payment flow, check the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/business/use-cases#multi-network-payment-monitoring"},"children":["payment monitoring use case"]},"."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Non-custodial"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Vilna watches the blockchain and tells you when an invoice is paid. It never holds the funds or controls the receiving wallet: the address is yours - one you provide, or derive from your own extended public key - and the payer sends to it directly. See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/legal/non-custodial"},"children":["Non-custodial Service Notice"]},"."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Before you begin"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You need a Vilna API key with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:invoice:read"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:invoice:write"]}," permissions. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/authentication"},"children":["Authentication"]}," for details."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"invoice-lifecycle","__idx":1},"children":["Invoice lifecycle"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An invoice moves through the following statuses:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Waiting for payment. No transactions received yet."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["underpaid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Partial payment received. The amount is below the requested total."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Full amount received. Waiting for block confirmations."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["confirmed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment confirmed with sufficient block confirmations."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["overpaid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Received more than the requested amount."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cancelled by the merchant."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expired"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The invoice passed its deadline without receiving full payment."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Status transitions:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"From"},"children":["From"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"To"},"children":["To"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Trigger"},"children":["Trigger"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Full payment received"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["underpaid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Partial payment received"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["overpaid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["More than required amount received"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cancelled by merchant"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expired"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Deadline passed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["underpaid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Remaining amount received"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["underpaid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["overpaid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["More than remaining amount received"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["underpaid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cancelled by merchant"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["underpaid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expired"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Deadline passed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["confirmed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Block confirmations reached"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["overpaid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["confirmed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Block confirmations reached"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["confirmed"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expired"]}," are terminal - no further transitions."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-a-crypto-payment-invoice","__idx":2},"children":["Create a crypto payment invoice"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To create an invoice, specify the deposit address, token (as a CAIP-19 asset identifier), amount in base units, and an expiration time. The address must belong to your project and must not already have an active invoice."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"curl","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api.vilna.io/v1/invoices\" \\\n  -H \"X-Api-Key: ${VILNA_API_KEY}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"address\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18\",\n    \"asset_gid\": \"eip155:56/bep20:0x55d398326f99059fF775485246999027B3197955\",\n    \"amount\": \"42500000\",\n    \"expires_at\": \"2026-06-15T18:00:00Z\",\n    \"metadata\": {\n      \"order_id\": \"ORD-20260615-1042\",\n      \"customer\": \"john@example.com\"\n    }\n  }'\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"TypeScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const { data, error } = await client.POST(\"/invoices\", {\n  body: {\n    address: \"0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18\",\n    asset_gid: \"eip155:56/bep20:0x55d398326f99059fF775485246999027B3197955\",\n    amount: \"42500000\",\n    expires_at: \"2026-06-15T18:00:00Z\",\n    metadata: {\n      order_id: \"ORD-20260615-1042\",\n      customer: \"john@example.com\",\n    },\n  },\n});\n\nif (error) {\n  console.error(error.detail);\n} else {\n  console.log(\"Invoice created:\", data.item.id);\n  console.log(\"Status:\", data.item.status); // \"pending\"\n}\n","lang":"typescript"},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response"]}," (abbreviated):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"item\": {\n    \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"address\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18\",\n    \"asset_gid\": \"eip155:56/bep20:0x55d398326f99059fF775485246999027B3197955\",\n    \"amount\": \"42500000\",\n    \"received_amount\": \"0\",\n    \"status\": \"pending\",\n    \"expires_at\": \"2026-06-15T18:00:00Z\",\n    \"metadata\": {\n      \"order_id\": \"ORD-20260615-1042\",\n      \"customer\": \"john@example.com\"\n    },\n    \"created_at\": \"2026-06-15T10:30:00Z\",\n    \"updated_at\": \"2026-06-15T10:30:00Z\",\n    \"status_logs\": [\n      {\n        \"status\": \"pending\",\n        \"comment\": null,\n        \"changed_at\": \"2026-06-15T10:30:00Z\"\n      }\n    ],\n    \"transactions\": []\n  },\n  \"references\": {\n    \"tokens\": {},\n    \"blockchains\": {}\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Key fields:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}]}," - the requested payment in base units (smallest token denomination). For USDT on BSC with 6 decimals, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"42500000\""]}," equals 42.5 USDT."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata"]}]}," - optional key-value pairs for linking invoices to your internal records."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expires_at"]}]}," - the payment deadline. After this time, the invoice moves to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expired"]}," if full payment has not arrived."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"One invoice per address"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An address can have only one active invoice at a time. Attempting to create a second invoice for the same address returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409 Conflict"]}," error."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"share-the-payment-page","__idx":3},"children":["Share the payment page"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every invoice has a public endpoint that requires no authentication. The invoice UUID acts as the access token - anyone with the link can view the payment details."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"curl","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl \"https://api.vilna.io/v1/public/invoices/550e8400-e29b-41d4-a716-446655440000\"\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"TypeScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"// No API key needed - this is a public endpoint\nconst response = await fetch(\n  \"https://api.vilna.io/v1/public/invoices/550e8400-e29b-41d4-a716-446655440000\"\n);\nconst invoice = await response.json();\n\nconsole.log(\"Pay to:\", invoice.item.address);\nconsole.log(\"Amount:\", invoice.item.amount.formatted, \"USDT\");\n","lang":"typescript"},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The public response includes the address, amount, status, and transaction history - everything a payer needs. It excludes merchant-only fields like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this endpoint to build custom payment pages, or direct payers to your hosted payment UI."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"check-invoice-status","__idx":4},"children":["Check invoice status"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retrieve full invoice details, including the status log and detected transactions."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"curl","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl \"https://api.vilna.io/v1/invoices/550e8400-e29b-41d4-a716-446655440000\" \\\n  -H \"X-Api-Key: ${VILNA_API_KEY}\"\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"TypeScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const { data, error } = await client.GET(\"/invoices/{invoice_id}\", {\n  params: { path: { invoice_id: \"550e8400-e29b-41d4-a716-446655440000\" } },\n});\n\nif (data) {\n  console.log(\"Status:\", data.item.status);\n  console.log(\"Received:\", data.item.received_amount);\n  console.log(\"Transactions:\", data.item.transactions.length);\n}\n","lang":"typescript"},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once a payment arrives, the response includes transaction details:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"item\": {\n    \"status\": \"paid\",\n    \"received_amount\": \"42500000\",\n    \"transactions\": [\n      {\n        \"hash\": \"0xabc123def456789012345678901234567890123456789012345678901234abcd\",\n        \"block_number\": 12345678,\n        \"is_success\": true,\n        \"detected_at\": \"2026-06-15T12:05:00Z\",\n        \"confirmed_at\": null,\n        \"deposits\": [\n          {\n            \"asset_gid\": \"eip155:56/bep20:0x55d398326f99059fF775485246999027B3197955\",\n            \"amount\": \"42500000\",\n            \"is_matched\": true\n          }\n        ]\n      }\n    ],\n    \"status_logs\": [\n      { \"status\": \"pending\", \"comment\": null, \"changed_at\": \"2026-06-15T10:30:00Z\" },\n      { \"status\": \"paid\", \"comment\": null, \"changed_at\": \"2026-06-15T12:05:00Z\" }\n    ]\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each transaction includes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_success"]}]}," - whether the transaction succeeded on-chain. Failed transactions appear in the list but do not count toward payment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["confirmed_at"]}]}," - ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," until the transaction reaches the required number of block confirmations."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deposits"]}]}," - individual token movements within the transaction. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_matched"]}," flag indicates whether the token matches the one the invoice expects."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handle-partial-payments-and-overpayments","__idx":5},"children":["Handle partial payments and overpayments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Vilna tracks every deposit and updates the invoice status automatically:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Partial payment"]},": The invoice moves to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["underpaid"]},". The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["received_amount"]}," field reflects the running total. Additional payments accumulate until the full amount is reached."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Full payment"]},": The invoice moves to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paid"]},", then to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["confirmed"]}," once block confirmations are sufficient."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Overpayment"]},": If the total received exceeds the requested amount, the status moves to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["overpaid"]},". Handle refunds in your application logic."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can monitor these transitions by polling the invoice endpoint or by setting up ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/events"},"children":["webhook notifications"]}," for invoice status changes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"list-invoices","__idx":6},"children":["List invoices"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retrieve all invoices with optional status filtering and pagination."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"curl","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# List all pending and underpaid invoices\ncurl \"https://api.vilna.io/v1/invoices?status=pending&status=underpaid&limit=20&page=1\" \\\n  -H \"X-Api-Key: ${VILNA_API_KEY}\"\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"TypeScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const { data, error } = await client.GET(\"/invoices\", {\n  params: {\n    query: {\n      status: [\"pending\", \"underpaid\"],\n      limit: 20,\n      page: 1,\n    },\n  },\n});\n\nif (data) {\n  for (const invoice of data.items) {\n    console.log(invoice.id, invoice.status, invoice.amount);\n  }\n  console.log(\"Total:\", data.meta.total);\n}\n","lang":"typescript"},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The list endpoint returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["InvoiceSummary"]}," objects (without ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status_logs"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactions"]},"). Use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/invoice/get-invoice"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /invoices/{invoice_id}"]}]}," for full details on a specific invoice."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"cancel-an-invoice","__idx":7},"children":["Cancel an invoice"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cancel an active invoice to free the address for new invoices. Only invoices in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["underpaid"]}," status can be cancelled. You can include an optional comment (up to 64 characters) explaining the reason."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"curl","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api.vilna.io/v1/invoices/550e8400-e29b-41d4-a716-446655440000/actions/cancel\" \\\n  -H \"X-Api-Key: ${VILNA_API_KEY}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"comment\": \"Customer requested cancellation\"\n  }'\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"TypeScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const { error } = await client.POST(\n  \"/invoices/{invoice_id}/actions/cancel\",\n  {\n    params: { path: { invoice_id: \"550e8400-e29b-41d4-a716-446655440000\" } },\n    body: {\n      comment: \"Customer requested cancellation\",\n    },\n  }\n);\n\nif (!error) {\n  console.log(\"Invoice cancelled\");\n}\n","lang":"typescript"},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful cancellation returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204 No Content"]},". The operation is idempotent - cancelling an already-cancelled invoice returns the same response."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Request body is optional"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["comment"]}," field is optional. You can send an empty body or omit the request body entirely."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":8},"children":["Next steps"]},{"$$mdtype":"Tag","name":"Cards","attributes":{"columns":2,"cardMinWidth":240},"children":[{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Events & Monitoring","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/events"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set up webhooks to receive real-time invoice status updates instead of polling"]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Core Concepts","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/core-concepts"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Learn about CAIP identifiers, base unit amounts, and the response envelope pattern"]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Integration Patterns","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/integration-patterns"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Deposit detection, payment monitoring, and other common integration scenarios"]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Platform API reference","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/apis/platform/"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Full endpoint catalog including invoice endpoints with request and response schemas"]}]}]}]},"headings":[{"value":"Invoices","id":"invoices","depth":1},{"value":"Invoice lifecycle","id":"invoice-lifecycle","depth":2},{"value":"Create a crypto payment invoice","id":"create-a-crypto-payment-invoice","depth":2},{"value":"Share the payment page","id":"share-the-payment-page","depth":2},{"value":"Check invoice status","id":"check-invoice-status","depth":2},{"value":"Handle partial payments and overpayments","id":"handle-partial-payments-and-overpayments","depth":2},{"value":"List invoices","id":"list-invoices","depth":2},{"value":"Cancel an invoice","id":"cancel-an-invoice","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"seo":{"title":"Invoices - Crypto Payment Tracking","description":"Create payment invoices, track incoming transactions, handle partial and overpayments, and share public payment pages using the Vilna API.","priority":0.7,"image":"https://cdn.vilna.io/docs/previews/guides.png","jsonLd":{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://docs.vilna.io/"},{"@type":"ListItem","position":2,"name":"Guides"},{"@type":"ListItem","position":3,"name":"Invoices"}]},{"@type":"TechArticle","headline":"Invoices - Crypto Payment Tracking","description":"Create payment invoices, track incoming transactions, handle partial and overpayments, and share public payment pages using the Vilna API.","url":"https://docs.vilna.io/guides/invoices","datePublished":"2026-01-15","dateModified":"2026-05-26","proficiencyLevel":"Intermediate","image":"https://cdn.vilna.io/docs/previews/guides.png","author":{"@id":"https://vilna.io/#organization"},"publisher":{"@id":"https://vilna.io/#organization"}}]}}},"lastModified":"2026-05-26T20:25:55.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/invoices","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}