Skip to main content
POST
/
v1
/
invoices
Create an invoice
curl --request POST \
  --url https://api.swiftpay.finance/v1/invoices \
  --header 'Content-Type: application/json' \
  --header 'X-Swift-Key: <api-key>' \
  --data '
{
  "amount": "100.00",
  "token": "USDC",
  "network": "ethereum",
  "recipients": {
    "evm": "0xYourWallet..."
  },
  "externalRef": "order_8675309",
  "expiresIn": 3600,
  "metadata": {
    "userId": "user_123",
    "product": "Pro Plan"
  }
}
'
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "merchantId": "m1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "externalRef": "order_8675309",
  "reference": "SP-2024-001",
  "addresses": [
    {
      "networkId": "ethereum",
      "networkName": "Ethereum",
      "networkSymbol": "ETH",
      "address": "0xDepositAddress..."
    }
  ],
  "recipient": null,
  "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "tokenSymbol": "USDC",
  "targetNetwork": "ethereum",
  "amountExpected": "100.00",
  "pendingAmount": "100.00",
  "receivedAmount": "0.00",
  "platformFee": "0.00",
  "amountRemitted": "0.00",
  "overpaidAmount": "0.00",
  "status": "pending",
  "expiresAt": "2024-03-11T11:00:00Z",
  "createdAt": "2024-03-11T10:00:00Z",
  "paidAt": null,
  "completedAt": null,
  "metadata": {
    "userId": "user_123",
    "product": "Pro Plan"
  },
  "transactions": []
}

Documentation Index

Fetch the complete documentation index at: https://docs.swiftpay.finance/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
X-Swift-Key
string
header
required

Your secret API key (sk_live_*). Keep this server-side only.

Body

application/json
​
amount
string
required

Amount to collect in the specified token

Example:

"100.00"

​
token
string
required

Token symbol to accept (e.g. USDC, USDT)

Example:

"USDC"

​
network
string
required

Target settlement network ID

Example:

"ethereum"

​
recipients
object

Settlement wallet address per chain type. Required for any chain type that has no treasury address configured on your account. Chain types with no coverage are silently omitted from the invoice.

Example:
{ "evm": "0xYourWallet..." }
​
externalRef
string

Your order/reference ID. Acts as an idempotency key — submitting the same externalRef returns the existing invoice.

Example:

"order_8675309"

​
expiresIn
integer

Invoice TTL in seconds (default: 3600)

Example:

3600

​
metadata
object

Arbitrary key-value data attached to the invoice

Example:
{
  "userId": "user_123",
  "product": "Pro Plan"
}

Response

Existing invoice returned (idempotent — same externalRef already exists)

​
id
string<uuid>

Unique invoice ID

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

​
merchantId
string<uuid>

Owning merchant ID

Example:

"m1b2c3d4-e5f6-7890-abcd-ef1234567890"

​
externalRef
string

Your own order/reference ID (idempotency key)

Example:

"order_8675309"

​
reference
string

SwiftPay short reference code

Example:

"SP-2024-001"

​
addresses
object[]

Network-specific deposit addresses

​
recipient
object

Resolved settlement recipient. Null until the invoice is locked to a chain (first payment received).

​
tokenAddress
string

Token contract address on the target network

Example:

"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"

​
tokenSymbol
string

Token symbol

Example:

"USDC"

​
targetNetwork
string

Primary network for settlement

Example:

"ethereum"

​
amountExpected
string

Total amount expected from the payer

Example:

"100.00"

​
pendingAmount
string

Amount still awaiting payment

Example:

"0.00"

​
receivedAmount
string

Amount received on-chain so far

Example:

"100.00"

​
platformFee
string

SwiftPay 1% platform fee

Example:

"1.00"

​
amountRemitted
string

Net amount forwarded to your wallet after fee

Example:

"99.00"

​
overpaidAmount
string

Amount received above what was expected

Example:

"0.00"

​
status
enum<string>

Current invoice status

Available options:
pending,
partial,
paid,
completed
Example:

"completed"

​
expiresAt
string<date-time>

Invoice expiry timestamp

Example:

"2024-03-12T12:00:00Z"

​
createdAt
string<date-time>
Example:

"2024-03-11T10:00:00Z"

​
paidAt
string<date-time> | null

Timestamp when full payment was detected

Example:

"2024-03-11T10:05:00Z"

​
completedAt
string<date-time> | null

Timestamp when funds were forwarded to merchant

Example:

"2024-03-11T10:06:00Z"

​
metadata
object

Arbitrary key-value metadata you attached at creation

Example:
{
  "userId": "user_123",
  "product": "Pro Plan"
}
​
transactions
object[]

On-chain transactions associated with this invoice