Invoice payments¶

An invoice aggregates; a payment is one deposit. GET /api/v1/invoices/{invoiceId}/payments lists them individually — transaction, sender, amount, token, screening verdict and classification.

curl "https://api.pay.nullswap.com/api/v1/invoices/b2f4a6c8-.../payments?limit=50" \
  -H "x-api-key: sk_live_..."

{
  "data": [{
    "id": "d4e5f6a7-b8c9-4012-a345-6b7c8d9e0f12",
    "invoiceId": "b2f4a6c8-0d1e-4f23-9a45-6b7c8d9e0f11",
    "chainTransactionId": "aa11bb22-cc33-4d44-8e55-6f7788990011",
    "chainId": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
    "tokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
    "fromAddress": "TJ8k...2Ba7",
    "amount": "25500000",
    "kind": "EXPECTED",
    "unexpectedReason": null,
    "resolution": "ACCEPTED",
    "status": "CONFIRMED",
    "confirmations": 19,
    "txHash": "4f1e0c5d8b2a7e9f3c6d1b8a5e2f9c4d7a0b3e6f1c8d5a2b9e4f7c0d3a6b1e8f",
    "refundAddress": null,
    "refundTag": null,
    "refundTxHash": null,
    "amlResultId": "5c6d7e8f-9a0b-41c2-8d34-5e6f7a8b9c0d",
    "amlStatus": "PASSED",
    "createdAt": "2026-01-01T12:04:11.000Z",
    "updatedAt": "2026-01-01T12:07:52.000Z"
  }],
  "pagination": { "offset": 0, "limit": 50, "total": 1, "order": "ASC" }
}

Filters: id, kind, resolution, plus offset, limit, order and sortBy (CREATED_AT, ID). This list defaults to order=ASC — oldest first — unlike every other list in the API.

An invoice id that does not exist, or belongs to another merchant, is not an error here: the list comes back empty.

txHash is the hash of the on-chain transaction that carried the deposit — what you show your customer, or substitute for {value} in the chain's explorerTxUrlTemplate from GET /api/v1/chains. It can be null on older payments, so check it before you render a link. Do not confuse it with refundTxHash, the transaction you sent back.

Three independent statuses¶

A payment carries three status fields, and each answers a different question.

A payment must be CONFIRMED, cleared (PASSED or SKIPPED) and EXPECTED before it counts towards paidAmount. Any one of the three failing keeps the money out of the invoice total.

How a payment is classified¶

kind is decided once, when the deposit is first seen, from the state of the invoice at that moment.

flowchart TD
    A["Deposit lands on the invoice's deposit address"] --> B{"Invoice still settling?<br/>WAITING · PAYMENT_DETECTED · PARTIALLY_PAID"}
    B -- no --> U["UNEXPECTED"]
    B -- yes --> C{"Same chain and same token<br/>as the invoice?"}
    C -- yes --> E["EXPECTED<br/>counts towards paidAmount"]
    C -- no --> D{"acceptsAnyToken"}
    D -- "true" --> F["ALTERNATIVE<br/>recorded, does not count"]
    D -- "false" --> U

When a payment is UNEXPECTED, unexpectedReason says why. A token or chain mismatch always wins over a timing reason:

What counts towards the invoice¶

Two consequences follow:

• Flagged money can never pay an invoice. It is subtracted from pendingAmount and never added to paidAmount, whatever you later resolve it as.
• Resolving a payment does not change any amount. ACCEPTED and REFUNDED record your decision for the audit trail; neither moves paidAmount.

Unexpected payments¶

resolution tracks your decision about a payment you were not asked for.

UNEXPECTED payments start PENDING. EXPECTED and ALTERNATIVE payments start ACCEPTED — you asked for the first and opted in to the second with acceptsAnyToken, so there is nothing to decide. Screening changes that: a payment of any kind whose amlStatus comes back FAILED returns to PENDING, because flagged money is yours to decide about.

Resolve a payment¶

curl -X POST https://api.pay.nullswap.com/api/v1/invoices/{invoiceId}/payments/{paymentId}/resolve \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "resolution": "REFUNDED", "refundAddress": "TJ8k...2Ba7" }'

A payment can be resolved when its resolution is PENDING and either its kind is not EXPECTED, or its amlStatus is FAILED. Expected money that passed screening settles on its own, so there is nothing to decide. Flagged expected money is the exception: it never counted towards the invoice, so the decision about it is yours.

The payment then carries what you named as refundAddress and refundTag — an X-address stored as its classic address and its tag. Refunding to an exchange account on RIPPLE almost always needs the customer's tag there: without it the money reaches the exchange and nobody's balance on it.

Record a refund¶

curl -X POST https://api.pay.nullswap.com/api/v1/invoices/{invoiceId}/payments/{paymentId}/refund \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "refundTxHash": "0xabcdef...7890" }'

The full sequence for a payment you want to send back is therefore:

POST .../resolve   { "resolution": "REFUNDED", "refundAddress": "..." }
  -> you broadcast the refund from your own wallet
POST .../refund    { "refundTxHash": "0x..." }