---
title: "List / export the buyer’s unified payment record across all agents"
method: GET
path: "/router/payments"
tags: ["Router"]
---

# List / export the buyer’s unified payment record across all agents

`GET /router/payments`

## Request

- Base URL: `https://api.sandbox.nevermined.app/api/v1`
- URL: `https://api.sandbox.nevermined.app/api/v1/router/payments`
- Auth: HTTP bearer

Returns your Router payments (newest first, capped at 1000) across every agent and delegation —
the unified audit trail. Filter by `delegationId` and by `from`/`to` (ISO-8601, inclusive on
`createdAt`). `format=csv` returns a CSV file download instead of the JSON array.

Supplying `requestId` selects a separate, exact, caller-scoped lookup instead: the list filters are
ignored and it is not subject to the 1000-row window. JSON answers it with an explicit `presence`
discriminator and zero or one `payments`; a failed lookup is an error, never `absent`. With `format=csv` it
answers the matching row, or only the header when there is none. An older
Router that ignores `requestId` answers a plain array, which is never authoritative absence.

## Query parameters

- `delegationId` string
- `from` string
- `to` string
- `requestId` string
- `format` 'json' | 'csv'

## Response `200`

A JSON array for a list; the lookup envelope (`RouterPaymentLookupDto`) with `requestId`; or a CSV file when `format=csv`.

- union
  - RouterPaymentRecordDto[]
    - `id` string, required
    - `createdAt` string, required
    - `status` 'Issued' | 'Settled' | 'Failed', required
    - `protocol` string, required
    - `network` string, required
    - `asset` string, nullable: The settlement asset AS PERSISTED AT MINT, which differs per rail: a symbol for x402 (`USDC`/`EURC`), the ERC-20 contract ADDRESS from the challenge for MPP-tempo, and an ISO currency code for MPP-stripe. Prefer `assetSymbol`/`assetDecimals` below for display — they normalise all three. Kept as-is for consumers that already parse it.
    - `assetSymbol` string, nullable: Ticker to display for `asset`, resolved from the asset address on this row’s chain — `USDC`, `EURC`, `USDC.e`, `pathUSD`. `null` when the asset is not one we recognise there; render the (truncated) `asset` instead, never a guess.
    - `assetDecimals` number, nullable: Decimal scale of `amount` for this asset, so a client never has to assume one. `null` when the asset is unrecognised — treat `amount` as raw atomic units rather than defaulting the scale, which would render a wrong NUMBER rather than a wrong label.
    - `amount` string, required: Amount in the asset’s smallest unit.
    - `merchantAddress` string, required: The merchant's pay-to identifier: a 0x address for the crypto rails (x402 / MPP-tempo), or the seller's Stripe network business profile id (profile_…) for the MPP-stripe / SPT card rail.
    - `txHash` string, nullable
    - `delegationId` string, nullable, required: The delegation this payment was reserved against. Null on a payment funded by a Nevermined Subscription, which spends subscription credits and no delegation.
    - `deliveryStatus` 'delivered' | 'charged_not_delivered' | 'charged_unconfirmed' | 'not_charged' | 'pending', required: Buyer-visible outcome: delivered when the request settled; charged_not_delivered when it failed and the merchant charge was observed; charged_unconfirmed when the charge was observed but delivery is unconfirmed; not_charged when reconciliation proved the merchant did not charge; pending when the charge outcome is unknown. On SPT and card rails, pending is not proof of no charge.
    - `feeFailureReason` string, nullable, required: Why the routing fee did not collect, or — on a `feeStatus: None` row — `fee-not-quoted: <why>` when a fee rate is configured but none was quoted for this payment. Diagnostic text for a human, NOT a stable contract: branch on `feeStatus`, never on this string. Whitespace is collapsed and any embedded `scheme://…` URL is replaced with `[url]` before publication. `null` when no fee rate is configured, and while a quoted fee is still on its happy path; a non-null value does not on its own mean the fee went uncollected — `feeStatus` says what happened.
    - `merchantSettlementObservedAt` string, nullable, required: When on-chain reconciliation OBSERVED that the merchant redeemed this payment’s authorization — the money really left your wallet. `null` on the ordinary path (a cleanly settled payment is anchored by `txHash`), and always on the MPP rails, which carry no EIP-3009 authorization. Read it together with `status`: `status` is what you GOT, this is what you PAID — `status: Failed`/`Issued` with this set means the merchant took the money and delivered nothing. A non-null `txHash` on such a row does not mean the payment succeeded.
    - `paymentId` string, required: Alias of `id`, named explicitly for requestId reconciliation clients.
    - `chargedMicros` string, nullable, required: Exact amount this payment still contributes to the delegation cap, in micros (1/10,000 of a cent). A merchant or fee share that was proven uncollected and released is excluded. `null` on legacy rows that predate exact micro-reserve columns.
    - `resultUrl` string, required: Relative URL of the retained paid result. It may answer Pending while the call is running, or 404 after retention expires, for a mode-A payment, for an unknown payment, or for a payment owned by another caller. A 404 is not delivery evidence; use `deliveryStatus`.
    - `fundingSource` 'delegation' | 'subscription', required: What paid for this payment: `delegation` (your delegation cap) or `subscription` (your Nevermined Subscription credits). On a `subscription` row Nevermined paid the merchant: `delegationId` is null, `buyer` is Nevermined's treasury, the fee fields are zero (`feeStatus` `None`) and `chargedMicros` is `"0"`; what it cost you is `creditsCharged` / `creditsStatus`.
    - `creditsCharged` integer, nullable, required: The rate, in credits, of a subscription-funded payment — kept on the row when its credits are refunded, so it counts against your allowance only when `creditsStatus` is `Committed`. Null on a delegation payment.
    - `creditsStatus` 'Reserved' | 'Committed' | 'Refunded' | 'null', nullable, required: Where a subscription-funded payment’s credits stand: `Committed` (delivered), `Reserved` (still running, undelivered and marked for refund, or still being decided) or `Refunded`. Null on a delegation payment.
    - `requestId` string, nullable
    - `resourceUrl` string, nullable
    - `buyer` string, required: The buyer identity that funded the payment: the on-chain payer EOA (0x…) for the crypto rails (x402 / MPP-tempo), or the Stripe customer id (cus_…) for the MPP-stripe / SPT card rail.
    - `feeAtomic` string, nullable: Nevermined’s routing fee for this payment, in the settlement asset’s smallest unit. `0` when no fee applied; `null` on rows that predate the fee.
    - `feeBps` number, nullable: Fee rate applied, in basis points over 10,000. `null` on rows that predate the fee.
    - `feeCents` string, nullable: Cents the fee added to the delegation-cap reserve. Note `amount` on this record is the MERCHANT leg in atomic units, so the combined cap charge is not derivable from this resource alone — it is recorded as `amountCents` on `GET /delegation/{delegationId}/transactions`, where that same row breaks it out as `feeCents` / `feeAtomic` / `feeBps`, with `feeReleased` marking a fee already refunded to the cap.
    - `feeStatus` 'None' | 'Accrued' | 'Submitted' | 'Settled' | 'Failed' | 'Released' | 'null', nullable: Fee lifecycle, independent of the payment `status`.
    - `feeTxHash` string, nullable: Settlement reference for the FEE leg — distinct from `txHash`, which is the MERCHANT leg’s. The two legs are independent movements that settle separately, so reconcile them separately. Reported verbatim by the facilitator (third-party text, not validated to a `0x` shape). `null` until the fee actually settles.
    - `feeNonce` string, nullable: EIP-3009 nonce of the fee leg, recorded when the leg is submitted. This is the only key that ties an on-chain transfer back to this payment: `authorizationState(buyer, feeNonce)` answers definitively whether the leg was consumed, which is how a `Submitted` fee is resolved. `null` until the leg is submitted. Not spendable on its own — the signed authorization is deliberately never stored.
  - RouterPaymentLookupDto: The answer to `GET /router/payments?requestId=…`: an exact, caller-scoped lookup.
    - `presence` 'present' | 'absent', required: `present` when you own the matching payment; `absent` when you have no payment recorded with that `requestId` yet — a call still in flight may record one later, so retry it with the same `requestId`, never a new one. A failed read is an error response, never `absent`.
    - `payments` RouterPaymentRecordDto[], required: Exactly one payment when `presence` is `present`; empty when it is `absent`.
      - `id` string, required
      - `createdAt` string, required
      - `status` 'Issued' | 'Settled' | 'Failed', required
      - `protocol` string, required
      - `network` string, required
      - `asset` string, nullable: The settlement asset AS PERSISTED AT MINT, which differs per rail: a symbol for x402 (`USDC`/`EURC`), the ERC-20 contract ADDRESS from the challenge for MPP-tempo, and an ISO currency code for MPP-stripe. Prefer `assetSymbol`/`assetDecimals` below for display — they normalise all three. Kept as-is for consumers that already parse it.
      - `assetSymbol` string, nullable: Ticker to display for `asset`, resolved from the asset address on this row’s chain — `USDC`, `EURC`, `USDC.e`, `pathUSD`. `null` when the asset is not one we recognise there; render the (truncated) `asset` instead, never a guess.
      - `assetDecimals` number, nullable: Decimal scale of `amount` for this asset, so a client never has to assume one. `null` when the asset is unrecognised — treat `amount` as raw atomic units rather than defaulting the scale, which would render a wrong NUMBER rather than a wrong label.
      - `amount` string, required: Amount in the asset’s smallest unit.
      - `merchantAddress` string, required: The merchant's pay-to identifier: a 0x address for the crypto rails (x402 / MPP-tempo), or the seller's Stripe network business profile id (profile_…) for the MPP-stripe / SPT card rail.
      - `txHash` string, nullable
      - `delegationId` string, nullable, required: The delegation this payment was reserved against. Null on a payment funded by a Nevermined Subscription, which spends subscription credits and no delegation.
      - `deliveryStatus` 'delivered' | 'charged_not_delivered' | 'charged_unconfirmed' | 'not_charged' | 'pending', required: Buyer-visible outcome: delivered when the request settled; charged_not_delivered when it failed and the merchant charge was observed; charged_unconfirmed when the charge was observed but delivery is unconfirmed; not_charged when reconciliation proved the merchant did not charge; pending when the charge outcome is unknown. On SPT and card rails, pending is not proof of no charge.
      - `feeFailureReason` string, nullable, required: Why the routing fee did not collect, or — on a `feeStatus: None` row — `fee-not-quoted: <why>` when a fee rate is configured but none was quoted for this payment. Diagnostic text for a human, NOT a stable contract: branch on `feeStatus`, never on this string. Whitespace is collapsed and any embedded `scheme://…` URL is replaced with `[url]` before publication. `null` when no fee rate is configured, and while a quoted fee is still on its happy path; a non-null value does not on its own mean the fee went uncollected — `feeStatus` says what happened.
      - `merchantSettlementObservedAt` string, nullable, required: When on-chain reconciliation OBSERVED that the merchant redeemed this payment’s authorization — the money really left your wallet. `null` on the ordinary path (a cleanly settled payment is anchored by `txHash`), and always on the MPP rails, which carry no EIP-3009 authorization. Read it together with `status`: `status` is what you GOT, this is what you PAID — `status: Failed`/`Issued` with this set means the merchant took the money and delivered nothing. A non-null `txHash` on such a row does not mean the payment succeeded.
      - `paymentId` string, required: Alias of `id`, named explicitly for requestId reconciliation clients.
      - `chargedMicros` string, nullable, required: Exact amount this payment still contributes to the delegation cap, in micros (1/10,000 of a cent). A merchant or fee share that was proven uncollected and released is excluded. `null` on legacy rows that predate exact micro-reserve columns.
      - `resultUrl` string, required: Relative URL of the retained paid result. It may answer Pending while the call is running, or 404 after retention expires, for a mode-A payment, for an unknown payment, or for a payment owned by another caller. A 404 is not delivery evidence; use `deliveryStatus`.
      - `fundingSource` 'delegation' | 'subscription', required: What paid for this payment: `delegation` (your delegation cap) or `subscription` (your Nevermined Subscription credits). On a `subscription` row Nevermined paid the merchant: `delegationId` is null, `buyer` is Nevermined's treasury, the fee fields are zero (`feeStatus` `None`) and `chargedMicros` is `"0"`; what it cost you is `creditsCharged` / `creditsStatus`.
      - `creditsCharged` integer, nullable, required: The rate, in credits, of a subscription-funded payment — kept on the row when its credits are refunded, so it counts against your allowance only when `creditsStatus` is `Committed`. Null on a delegation payment.
      - `creditsStatus` 'Reserved' | 'Committed' | 'Refunded' | 'null', nullable, required: Where a subscription-funded payment’s credits stand: `Committed` (delivered), `Reserved` (still running, undelivered and marked for refund, or still being decided) or `Refunded`. Null on a delegation payment.
      - `requestId` string, nullable
      - `resourceUrl` string, nullable
      - `buyer` string, required: The buyer identity that funded the payment: the on-chain payer EOA (0x…) for the crypto rails (x402 / MPP-tempo), or the Stripe customer id (cus_…) for the MPP-stripe / SPT card rail.
      - `feeAtomic` string, nullable: Nevermined’s routing fee for this payment, in the settlement asset’s smallest unit. `0` when no fee applied; `null` on rows that predate the fee.
      - `feeBps` number, nullable: Fee rate applied, in basis points over 10,000. `null` on rows that predate the fee.
      - `feeCents` string, nullable: Cents the fee added to the delegation-cap reserve. Note `amount` on this record is the MERCHANT leg in atomic units, so the combined cap charge is not derivable from this resource alone — it is recorded as `amountCents` on `GET /delegation/{delegationId}/transactions`, where that same row breaks it out as `feeCents` / `feeAtomic` / `feeBps`, with `feeReleased` marking a fee already refunded to the cap.
      - `feeStatus` 'None' | 'Accrued' | 'Submitted' | 'Settled' | 'Failed' | 'Released' | 'null', nullable: Fee lifecycle, independent of the payment `status`.
      - `feeTxHash` string, nullable: Settlement reference for the FEE leg — distinct from `txHash`, which is the MERCHANT leg’s. The two legs are independent movements that settle separately, so reconcile them separately. Reported verbatim by the facilitator (third-party text, not validated to a `0x` shape). `null` until the fee actually settles.
      - `feeNonce` string, nullable: EIP-3009 nonce of the fee leg, recorded when the leg is submitted. This is the only key that ties an on-chain transfer back to this payment: `authorizationState(buyer, feeNonce)` answers definitively whether the leg was consumed, which is how a `Submitted` fee is resolved. `null` until the leg is submitted. Not spendable on its own — the signed authorization is deliberately never stored.

## Other responses

- `400`: `from`/`to` are not valid ISO-8601 timestamps, or `requestId` is empty or repeated (BCK.ROUTER.0001).
- `401`: Missing/invalid Nevermined API key.

---

[API](https://skmtc.dev/nevermined/apis/nevermined-api.md) · [All operations](https://skmtc.dev/nevermined/apis/nevermined-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nevermined/apis/nevermined-api/revisions/cabbe618c80b?raw)