Skip to main content

​
The Invoice object

Every invoice returned by the API is an InvoiceResponse object.
​
id
string
required
UUID that uniquely identifies this invoice.
​
merchantId
string
required
UUID of the merchant that owns this invoice.
​
externalRef
string
Your own reference / idempotency key, if provided at creation time. null when omitted.
​
reference
string
required
SwiftPay-generated 10-character human-readable reference (e.g. A3FX9KZ2QP). Safe to share with customers.
​
addresses
InvoiceDepositAddress[]
required
One deposit address per supported network. Each element contains:
  • networkId — chain identifier (e.g. ethereum, polygon, sepolia)
  • network — human-readable chain name (e.g. Ethereum Mainnet)
  • address — EVM address to which the customer should send funds
​
recipient
string
EVM treasury address that receives settled funds after the platform fee. null if not set.
​
tokenAddress
string
required
On-chain contract address of the accepted token.
​
tokenSymbol
string
required
Ticker symbol of the accepted token (e.g. USDC, USDT).
​
targetNetwork
string
Chain on which the first payment was detected. null until at least one payment is received.
​
amountExpected
string
required
Requested payment amount as a decimal string (e.g. "100.00").
​
pendingAmount
string
Amount not yet confirmed on-chain. null when no transactions are in-flight.
​
receivedAmount
string
required
Total confirmed amount received so far.
​
platformFee
string
required
Protocol fee transferred to SwiftPay at settlement. Calculated at invoice creation time from amountExpected using the per-token fee configuration (configurable rate with optional ceiling).
​
amountRemitted
string
required
Total amount forwarded to recipient at settlement — the full received balance minus platformFee. Any overpayment above amountExpected is included here.
​
overpaidAmount
string
required
Amount received above amountExpected. Forwarded to recipient alongside the net payment at settlement (no additional fee is charged on the overpayment). "0" when the exact amount or less was received.
​
status
string
required
Invoice lifecycle status. One of:
  • pending — awaiting first payment
  • partial — partially paid
  • paid — fully paid, funds not yet settled
  • completed — funds settled to recipient
​
expiresAt
string
ISO 8601 timestamp after which the invoice will no longer accept payments. null if no expiry set.
​
createdAt
string
required
ISO 8601 timestamp when the invoice was created.
​
paidAt
string
ISO 8601 timestamp when the invoice reached paid status. null until then.
​
completedAt
string
ISO 8601 timestamp when the invoice reached completed status. null until then.
​
metadata
object
required
Arbitrary key-value pairs you attached at creation time. Empty object {} when none provided.
​
transactions
TransactionResponse[]
required
Array of on-chain payment records associated with this invoice. Empty array until a payment is detected.

​
Endpoints

MethodPathDescription
POST/v1/invoicesCreate a new invoice
GET/v1/invoicesList all invoices for the authenticated merchant
GET/v1/invoices/:idRetrieve a single invoice by ID
GET/v1/invoices/:id/transactionsList transactions for an invoice
All endpoints require a secret API key in the X-Swift-Key header: 
X-Swift-Key: sk_live_...

​
Create an invoice

POST /v1/invoices Creates a new invoice and derives a unique deposit address on each supported network. If you supply an externalRef that was used before with identical parameters, the original invoice is returned with HTTP 200 instead of 201 (idempotent creation).

​
Request body

​
token
string
required
Token symbol to accept. Must be a token supported by SwiftPay (e.g. "USDC", "USDT").
​
amountExpected
number
required
Requested payment amount in the token’s major unit (e.g. 100 for 100 USDC). Must be greater than 0.
​
chains
string[]
List of networkId values to generate deposit addresses for (e.g. ["ethereum", "polygon"]). Omit or pass an empty array to use all chains that support the requested token.
​
externalRef
string
Your own idempotency key (e.g. an order ID). If the same externalRef is submitted again with the same parameters, the existing invoice is returned unchanged. If parameters differ, a 409 error is returned.
​
recipient
string
EVM address to receive settled funds after the protocol fee. If omitted, funds are held until a recipient is configured in dashboard settings.
​
expiresAt
string
ISO 8601 timestamp for invoice expiry (e.g. "2026-03-11T12:00:00Z"). After this time the invoice will no longer accept payments.
​
metadata
object
Arbitrary key-value pairs stored alongside the invoice and returned in all responses. Useful for linking to your internal records.

​
Response

Returns the created Invoice object with HTTP 201, or 200 when an idempotent match is found.

​
Error codes

StatusErrorCondition
400invalid request bodyMissing required fields, amountExpected ≤ 0, or malformed JSON
400unknown chainOne or more values in chains are not recognised
400no supported chains for tokenThe requested token has no supported chains (after filtering)
400invalid recipient addressrecipient is not a valid EVM address
401unauthorizedX-Swift-Key header is missing or the key is invalid / revoked
409externalRef conflictexternalRef was used before but with different parameters

​
List invoices

GET /v1/invoices Returns a paginated list of all invoices belonging to the authenticated merchant, ordered by createdAt descending.

​
Query parameters

​
limit
integer
default:"20"
Maximum number of invoices to return. Accepted range: 1–100.
​
offset
integer
default:"0"
Number of invoices to skip (cursor-style pagination).
​
status
string
Filter by invoice status. One of: pending, partial, paid, completed.

​
Response

{
  "data": [ /* Invoice objects */ ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

​
Error codes

StatusErrorCondition
401unauthorizedX-Swift-Key header is missing or the key is invalid / revoked

​
Get an invoice

GET /v1/invoices/:id Retrieves a single invoice by its UUID.

​
Path parameters

​
id
string
required
UUID of the invoice to retrieve (e.g. b3f1c2d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d).

​
Response

Returns the Invoice object with HTTP 200.

​
Error codes

StatusErrorCondition
400invalid invoice id:id is not a valid UUID
401unauthorizedX-Swift-Key header is missing or the key is invalid / revoked
404invoice not foundNo invoice with this ID belongs to the authenticated merchant

​
List invoice transactions

GET /v1/invoices/:id/transactions Returns all on-chain payment transactions detected for a given invoice. Transactions are returned in the order they were detected.

​
Path parameters

​
id
string
required
UUID of the invoice whose transactions you want to retrieve.

​
Response

{
  "data": [
    {
      "id": "uuid",
      "invoiceId": "uuid",
      "txHash": "0x...",
      "networkId": "ethereum",
      "amount": "100.00",
      "fee": "1.00",
      "status": "confirmed",
      "confirmedAt": "2026-03-11T10:05:00Z",
      "createdAt": "2026-03-11T10:00:00Z"
    }
  ]
}

​
Error codes

StatusErrorCondition
400invalid invoice id:id is not a valid UUID
401unauthorizedX-Swift-Key header is missing or the key is invalid / revoked
404invoice not foundNo invoice with this ID belongs to the authenticated merchant

​
Error response format

All errors share the same envelope: 
{
  "success": false,
  "error": "human-readable error message",
  "details": {},
  "traceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
Use traceId when contacting support@swiftpay.finance to help diagnose issues.

​
Request / response examples

See Invoice endpoint examples for complete curl examples covering success and error scenarios for every endpoint.