Invoices¶

An invoice is a request for payment tied to one order. Creating one reserves a deposit address on the chain you chose; anything sent to that address is attributed to that invoice and to no other.

Create an invoice¶

curl -X POST https://api.pay.nullswap.com/api/v1/invoices \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
        "chainId": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
        "tokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
        "expectedAmount": "25500000",
        "expiresInSeconds": 3600,
        "externalId": "order-10241"
      }'

There is no merchantId field — your API key already names the merchant.

The response is the invoice:

{
  "id": "b2f4a6c8-0d1e-4f23-9a45-6b7c8d9e0f11",
  "merchantId": "9f1d2c3b-4a5e-4f60-8b71-2c3d4e5f6a7b",
  "depositWalletId": "7e2a9c14-8b3d-4c56-a789-0f1e2d3c4b5a",
  "depositAddress": "TQ5s...9Xk2",
  "depositTag": null,
  "depositXAddress": null,
  "chainId": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
  "tokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
  "expectedAmount": "25500000",
  "acceptsAnyToken": false,
  "autoSweep": true,
  "paidAmount": "0",
  "pendingAmount": "0",
  "externalId": "order-10241",
  "status": "WAITING",
  "amlStatus": null,
  "createdAt": "2026-01-01T12:00:00.000Z",
  "expiresAt": "2026-01-01T13:00:00.000Z",
  "updatedAt": "2026-01-01T12:00:00.000Z"
}

Show depositAddress and the exact expectedAmount to your customer, and stop showing them once expiresAt has passed. On RIPPLE show depositTag with them, marked as mandatory: there the address alone does not name the invoice. See Destination tags on RIPPLE. depositTag and depositXAddress are null on every other chain.

Errors¶

Validation runs in this order, so the first failing rule is the error you get:

Destination tags on RIPPLE¶

On RIPPLE, the XRP Ledger, a deposit address is not yours alone. Every RIPPLE invoice is paid to the same depositAddress, and a payment is matched to its invoice by the destination tag it carries, and by nothing else. The invoice names that tag in two more fields:

{
  "id": "b2f4a6c8-0d1e-4f23-9a45-6b7c8d9e0f11",
  "depositWalletId": "7e2a9c14-8b3d-4c56-a789-0f1e2d3c4b5a",
  "depositAddress": "rHsMGQEkVNJmpGWs8XUBoTBiAAbwxZN5v3",
  "depositTag": 959725,
  "depositXAddress": "XVMFQQBMhdouRqhPMuawgBMN1AVFToG5NjwwoxoAYuiUyDF",
  "expectedAmount": "25000000",
  "status": "WAITING"
}

Show your customer the address, the tag — labelled as required, not as an optional memo — and the exact amount. You may also show depositXAddress as an alternative to the pair, and it is what a QR code should encode: a wallet that scans it gets the address and the tag together. Every invoice.* webhook carries both fields in data as well.

The amount credited is what the payment delivered to the address, not the amount it named: an XRP Ledger payment can be sent as a partial payment, and only what arrived counts. Under- and overpayment then work as on any other chain — see Under- and overpayment.

Reading invoices¶

GET /api/v1/invoices filters on id, chainId, tokenId, status and externalId, all repeatable, plus offset, limit, order and sortBy (CREATED_AT, EXPIRES_AT, ID).

GET /api/v1/invoices?status=PAID&status=PARTIALLY_PAID&limit=100&sortBy=EXPIRES_AT&order=ASC

Status lifecycle¶

stateDiagram-v2
    direction LR
    [*] --> WAITING

    WAITING --> PAYMENT_DETECTED
    WAITING --> PARTIALLY_PAID
    WAITING --> PAID
    WAITING --> EXPIRED

    PAYMENT_DETECTED --> WAITING
    PAYMENT_DETECTED --> PARTIALLY_PAID
    PAYMENT_DETECTED --> PAID
    PAYMENT_DETECTED --> EXPIRED

    PARTIALLY_PAID --> WAITING
    PARTIALLY_PAID --> PAYMENT_DETECTED
    PARTIALLY_PAID --> PAID
    PARTIALLY_PAID --> EXPIRED

    PAID --> WAITING
    PAID --> PAYMENT_DETECTED
    PAID --> PARTIALLY_PAID

    WAITING --> SWAPPING
    PAYMENT_DETECTED --> SWAPPING
    PARTIALLY_PAID --> SWAPPING
    PAID --> SWAPPING
    SWAPPING --> COMPLETED
    SWAPPING --> FAILED
    FAILED --> SWAPPING
    FAILED --> COMPLETED

    COMPLETED --> [*]
    EXPIRED --> [*]

Four details in the diagram are easy to miss:

• Statuses can go backwards, PAID included. A transaction that is reorged away takes its amount with it: the invoice drops from PARTIALLY_PAID back to WAITING, and a PAID invoice drops back to WAITING, PAYMENT_DETECTED or PARTIALLY_PAID, whichever its remaining amounts give. Your handler must treat every webhook payload as a snapshot, not as a diff.
• Going forward, PAID leads only to SWAPPING. While an invoice is paid it cannot expire, and money that arrives meanwhile is recorded as an unexpected payment and does not change paidAmount. Only a reverted payment takes it out of PAID; once a sweep has started, a reverted payment no longer moves the status backwards.
• SWAPPING, COMPLETED and FAILED follow sweeps, not payment. An automatic sweep moves a PAID invoice to SWAPPING once the sweep is accepted; a partially paid invoice keeps waiting for the rest. Calling the sweep endpoint yourself moves the invoice to SWAPPING as soon as the call puts money in flight — from WAITING, PAYMENT_DETECTED and PARTIALLY_PAID as well as from PAID. Either way the invoice becomes COMPLETED once no sweep of the address is still running or failed; dust left on it is not waited for.
• FAILED is not final. When a sweep of a SWAPPING invoice gives up after its retries, the invoice becomes FAILED and you receive invoice.failed. The money is still on the deposit address: the next sweep — automatic, or one you request — moves the invoice back to SWAPPING, or straight to COMPLETED when it settles.

COMPLETED and EXPIRED are terminal. Amounts can still be corrected afterwards, so a late transaction on an expired invoice is recorded rather than lost — but the status will not move again.

The two amounts¶

pendingAmount and paidAmount move independently and mean different things.

Only payments in the invoice's own chain and token contribute to either figure. Deposits in another token never do, whatever you decide to do with them. The status is then derived from the two:

paidAmount >= expectedAmount   -> PAID
paidAmount > 0                 -> PARTIALLY_PAID
pendingAmount > 0              -> PAYMENT_DETECTED
otherwise                      -> WAITING

Under- and overpayment¶

The invoice does not reject a wrong amount; it records what actually arrived.

Underpayment. The invoice sits at PARTIALLY_PAID. The customer can top it up before expiresAt and several deposits sum together. If the deadline passes while it is still short, it expires with paidAmount recorded — the money is not lost, but the invoice is closed and you decide what to do.

Overpayment. The invoice becomes PAID with paidAmount > expectedAmount. There is no cap, no OVERPAID status and no automatic refund. Compare the two yourself if you refund the difference.

Expiry¶

An invoice expires when expiresAt passes — but not while money is still in flight. Expiry is skipped for an invoice that has any deposit still awaiting confirmation, or any confirmed deposit in an alternative token. A customer who pays just before the deadline therefore does not lose the payment because its confirmation arrived just after.

A PARTIALLY_PAID invoice does expire. Partial payment stops the clock only for as long as something is still confirming.

Alternative tokens¶

Set acceptsAnyToken: true and a deposit of a different token on a compatible chain is recorded as an ALTERNATIVE payment instead of being treated as a mistake. It still does not count towards paidAmount, because expectedAmount is denominated in the invoice's own token — you decide what it is worth and whether the order is settled.

Leave it false (the default) and such a deposit becomes an UNEXPECTED payment instead. Either way the money is recorded; the flag only changes how it is classified and whether you are asked to decide about it. See Invoice payments.

Moving funds to your balance¶

Money paid into an invoice arrives on its deposit address. It reaches your balance, and becomes something you can withdraw, only when it is swept off that address. A sweep moves one token's whole clean amount on the address in one go, so several payments in the same token travel together.

autoSweep on the invoice decides who starts it:

Every payment that has confirmed and cleared screening is swept, whatever its kind — EXPECTED, ALTERNATIVE and UNEXPECTED alike, and whether or not you have resolved it. Money that failed screening is never swept and never reaches your balance; it stays on the deposit address.

Sweeps are retried without anything on your side. One that could not be started is started again until it is accepted, and one that failed is raised again a limited number of times, so a temporary outage delays the money rather than stranding it. If a sweep has still not gone through, call the sweep endpoint yourself.

An automatic sweep moves a PAID invoice to SWAPPING once it is accepted, and to COMPLETED once the money is on your balance. An invoice that is not yet fully paid keeps its status while its first payments are swept, and moves on only after it becomes PAID. A sweep that gives up turns a SWAPPING invoice FAILED until a later sweep moves the money; see the status lifecycle.

Set autoSweep: false when you want to choose the moment yourself — for example, to keep a payment you may resolve as REFUNDED off your balance until you have decided. The sweep is the only way money leaves a deposit address: NullSwap does not send refunds, so with false the funds stay exactly where they are until you sweep them.

Moving money costs a network fee, and you pay it either way. On a chain's native coin the sweep pays its own network fee out of what it moves, so slightly less than was paid arrives. For a token on an account-based chain we pay the network fee in the native coin and withhold its value, in the token at current prices, from the credit — together with the cost of any approvals a converting sweep needs and of the native coin sent to the address to pay for the move. On UTXO chains and on Monero nothing is withheld beyond what the sweep itself pays. Of what arrives, the merchant fee and that network fee are withheld, and the rest is credited to your balance.

Sweep a deposit address¶

curl -X POST https://api.pay.nullswap.com/api/v1/wallets/7e2a9c14-8b3d-4c56-a789-0f1e2d3c4b5a/sweep \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
        "chainId": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
        "tokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908"
      }'

walletId in the path is the invoice's depositWalletId, or the id of a static wallet. The body is optional:

Without a body, every token with a clean amount on the address is swept. The answer is 202 with one sweep per token:

{
  "data": [
    {
      "id": "0b1c2d3e-4f50-4617-8a29-3b4c5d6e7f80",
      "walletId": "7e2a9c14-8b3d-4c56-a789-0f1e2d3c4b5a",
      "invoiceId": "b2f4a6c8-0d1e-4f23-9a45-6b7c8d9e0f11",
      "staticWalletId": null,
      "chainId": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
      "tokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
      "trigger": "MANUAL",
      "status": "SWEEPING",
      "amount": "25500000",
      "feeEstimate": null,
      "transferRequestId": "4d5e6f70-8192-4a3b-9c4d-5e6f708192a3",
      "error": null,
      "createdAt": "2026-01-01T12:10:00.000Z",
      "updatedAt": "2026-01-01T12:10:01.000Z",
      "feePercentage": "150",
      "fee": null,
      "feeUsd": null,
      "settledAt": null,
      "creditedTokenId": null,
      "dstTokenId": null,
      "amountIn": null,
      "amountOut": null,
      "conversionSkipReason": null
    }
  ]
}

Auto-conversion rules are set in the cabinet, under Convert → Auto-convert. A sweep covered by one is converted into the rule's target token on its way to your balance, when it can be. When it cannot, it is credited in its own token and conversionSkipReason says why:

A sweep can already be FAILED in the 202 itself, when it was refused the moment it was started. The 202 means the call was taken, not that every sweep in it is moving: read each status.

There is at most one active (PENDING or SWEEPING) sweep per address and token. If one is already running — an automatic one, or an earlier call of yours — it is returned as it is, and a new sweep is started only for the tokens that have none. That is not an error: trigger: "AUTO" in the answer to your call means the money was already on its way. Repeating the call is therefore safe.

When the address holds nothing clean above dust, the call answers 422 NOTHING_TO_SWEEP and adds a details object with the estimate, so you can see how far short the amount is:

{
  "statusCode": 422,
  "message": "NOTHING_TO_SWEEP",
  "timestamp": "2026-01-01T12:10:00.000Z",
  "details": {
    "amount": "150000",
    "feeEstimate": "2800000",
    "dust": [
      {
        "chainId": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
        "tokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
        "amount": "150000",
        "feeEstimate": "2800000"
      }
    ]
  }
}

amount is in base units of the token, feeEstimate in base units of the chain's native coin; the top-level pair repeats the first entry of dust. With no clean amount at all, dust is empty, amount is "0" and feeEstimate is null.

Unlike the rest of the API, an address of another merchant is a 404, not a 403: the answer does not confirm that the id exists.