{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/nevermined-app/json-schema/nevermined-app-router-payment-record-dto-schema.json",
  "title": "RouterPaymentRecordDto",
  "x-generated": "2026-11-20",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/nevermined-app-openapi.json#/components/schemas/RouterPaymentRecordDto",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "createdAt": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "description": "Merchant-leg lifecycle, not a money-moved flag. Read deliveryStatus and merchantSettlementObservedAt. Issued + pending means the charge outcome is unknown: neither payment nor no charge is established.",
      "enum": [
        "Issued",
        "Settled",
        "Failed"
      ]
    },
    "deliveryStatus": {
      "type": "string",
      "description": "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 recorded no merchant charge, including unreadable write-offs: this is not conclusive proof that no money moved; not_delivered when the merchant answered the paid call with an error (an x402 or MPP `evm` `exact` payment, or an MPP-tempo `charge`), so nothing was delivered, and no merchant charge has been observed yet: the merchant can still redeem the payment until its authorization expires or is canceled, so the amount stays reserved against the delegation until reconciliation decides, after confirmed cancellation or expiry, whether it becomes not_charged or a charged_ value; pending when the charge outcome is unknown. On SPT and card rails, pending is not proof of no charge. SPT and card rows are never decided on chain. Issued + pending establishes neither payment nor no charge. Read merchantSettlementObservedAt alongside it; null is not, on its own, proof of no charge.",
      "enum": [
        "delivered",
        "charged_not_delivered",
        "charged_unconfirmed",
        "not_charged",
        "not_delivered",
        "pending"
      ]
    },
    "upstreamAnsweredAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When the merchant answered the paid request with 2xx headers. This does not prove the response body completed or contained useful content. Settlement may remain unconfirmed. Null when no 2xx response was recorded."
    },
    "upstreamBodyBytes": {
      "type": [
        "number",
        "null"
      ],
      "description": "Decoded buffered paid response bytes, before JSON/text/base64 conversion or catalog error withholding. Zero flags an empty body (including a 2xx); null means not measured, including older payments, mode A, streaming, or an incomplete body read the transport detects. This is not proof of useful content or an automatic refund. JSON only; CSV is unchanged."
    },
    "fundingSource": {
      "type": "string",
      "description": "What paid for this payment: `delegation` (your delegation cap) or `subscription` (your Nevermined Subscription credits; Nevermined paid the merchant, so `delegationId` is null).",
      "enum": [
        "delegation",
        "subscription"
      ]
    },
    "creditsCharged": {
      "type": [
        "number",
        "null"
      ],
      "description": "Credits a subscription-funded payment cost. Null on a delegation payment."
    },
    "creditsStatus": {
      "type": [
        "string",
        "null"
      ],
      "description": "Where a subscription-funded payment’s credits stand: `Committed` (delivered), `Reserved` (undelivered and marked for refund, or still being decided) or `Refunded`. Null on a delegation payment.",
      "enum": [
        "Reserved",
        "Committed",
        "Refunded"
      ]
    },
    "protocol": {
      "type": "string"
    },
    "network": {
      "type": "string"
    },
    "asset": {
      "type": [
        "string",
        "null"
      ],
      "description": "The settlement asset AS PERSISTED AT MINT, which differs per rail: a symbol (`USDC`/`EURC`) for x402 and for an MPP `evm` charge, the ERC-20 contract ADDRESS from the challenge for MPP-tempo, and an ISO currency code for MPP-stripe — so `protocol: mpp` alone does not tell you which. Prefer `assetSymbol`/`assetDecimals` below for display — they normalise all three. Kept as-is for consumers that already parse it."
    },
    "assetSymbol": {
      "type": [
        "string",
        "null"
      ],
      "description": "Ticker to display for `asset`, resolved for this row’s chain (e.g. `USDC.e`). `null` only when `asset` is a contract ADDRESS we do not recognise on that chain — render the (truncated) address instead, never a guess. When `asset` already is a symbol or a currency code it is echoed here, so a non-null value does NOT by itself imply the scale is known: branch on `assetDecimals` for that."
    },
    "assetDecimals": {
      "type": [
        "number",
        "null"
      ],
      "description": "Decimal scale of `amount` for this asset, so a client never has to assume one. `null` whenever the scale is unknown — treat `amount` as raw atomic units rather than defaulting the scale, which would render a wrong NUMBER rather than a wrong label. This, NOT `assetSymbol`, is the field to branch on: the scale can be unknown on a row that still carries a symbol."
    },
    "amount": {
      "type": "string",
      "description": "Amount in the asset’s smallest unit."
    },
    "merchantAddress": {
      "type": "string",
      "description": "The merchant's pay-to identifier: a 0x address for the crypto rails (x402 / MPP `evm` / MPP-tempo), or the seller's Stripe network business profile id (profile_…) for the MPP-stripe / SPT card rail."
    },
    "txHash": {
      "type": [
        "string",
        "null"
      ],
      "description": "On-chain settlement tx for the MERCHANT leg — the transaction that moved the money, which is NOT by itself proof the payment succeeded. It is normally reported when the payment settles. It is also filled in by on-chain reconciliation for a payment still `Issued` or `Failed` whose authorization the merchant demonstrably redeemed — whether the merchant then failed to deliver, or delivered without ever reporting a usable reference. Read `merchantSettlementObservedAt` and `status` together to tell those apart. `null` until one of those happens, and always on the MPP-stripe card rail, which does not settle on a chain."
    },
    "delegationId": {
      "type": [
        "string",
        "null"
      ],
      "description": "The delegation this payment was reserved against. Null on a payment funded by a Nevermined Subscription, which spends subscription credits and no delegation."
    },
    "agentId": {
      "type": [
        "string",
        "null"
      ],
      "description": "Buyer-supplied agent identifier snapshotted at payment time; attribution only."
    },
    "agentLabel": {
      "type": [
        "string",
        "null"
      ],
      "description": "Buyer-chosen agent name snapshotted at payment time."
    },
    "requestId": {
      "type": [
        "string",
        "null"
      ],
      "description": "The idempotency id supplied at mint time, if any."
    },
    "resourceUrl": {
      "type": [
        "string",
        "null"
      ],
      "description": "The upstream resource URL recorded with the payment."
    },
    "buyer": {
      "type": "string",
      "description": "The buyer identity that funded the payment: the on-chain payer EOA (0x…) for the crypto rails (x402 / MPP `evm` / MPP-tempo), or the Stripe customer id (cus_…) for the MPP-stripe / SPT card rail."
    },
    "feeAtomic": {
      "type": [
        "string",
        "null"
      ],
      "description": "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": {
      "type": [
        "number",
        "null"
      ],
      "description": "Fee rate applied, in basis points over 10,000. `null` on rows that predate the fee."
    },
    "feeCents": {
      "type": [
        "string",
        "null"
      ],
      "description": "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/{id}/transactions, where that same row breaks it out as `feeCents` / `feeAtomic` / `feeBps`, with `feeReleased` marking a fee already refunded to the cap."
    },
    "feeStatus": {
      "type": [
        "string",
        "null"
      ],
      "description": "Fee lifecycle, independent of the payment `status`.",
      "enum": [
        "None",
        "Accrued",
        "Submitted",
        "Settled",
        "Failed",
        "Released"
      ]
    },
    "feeTxHash": {
      "type": [
        "string",
        "null"
      ],
      "description": "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. **Presence does NOT mean the fee settled — check `feeStatus` for that.** On the x402 rail — which here includes an MPP `evm` charge, whose fee leg is an x402 EIP-3009 fee authorization exactly as on x402 — it is normally `null`: Nevermined relays that leg itself as an ERC-4337 UserOp, whose artifact is a userOpHash rather than a transaction hash — a different kind of reference that resolves on no block explorer — and the reconciliation that resolves the fee reads the authorization nonce on-chain, which yields a boolean and no transaction. Only a leg settled through the facilitator instead (the fallback where Nevermined cannot relay on that chain) carries a value, reported verbatim by the facilitator (third-party text, not validated to a `0x` shape) once the fee settles. On MPP-tempo it is the hash of the fee transaction Nevermined broadcasts, recorded when the transaction is SUBMITTED rather than when it is mined — so it is present while `feeStatus` is still `Submitted`, and it remains present on rows that end `Failed` or `Released` (the transaction was refused, reverted, or expired unmined). `null` when no fee applied, or before a fee leg is submitted. Do NOT poll this field to learn whether an x402 fee settled: read `feeStatus`."
    },
    "feeNonce": {
      "type": [
        "string",
        "null"
      ],
      "description": "EIP-3009 nonce of the fee leg, recorded when the leg is submitted. **x402 rail only** — which includes an MPP `evm` charge, whose fee leg is an x402 EIP-3009 fee authorization exactly as on x402. On that rail it is the 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, and always `null` on MPP-tempo, whose fee leg is a native transaction with no EIP-3009 nonce — there the reconciliation key is `feeTxHash` instead. Not spendable on its own — the signed authorization is deliberately never stored."
    },
    "feeFailureReason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why the routing fee did not collect. Its main job is `Released`: that status is ALSO the ordinary state of a fee that was legitimately never collectable, and the delegation cap reconciles either way because the reserve is handed back, so this is the only field that tells a systemic refusal from a healthy row. Set on `Failed` too — and on a `Submitted` row whose outcome could not be DETERMINED (the settlement call timed out or answered unrecoverably), where it says why the fee is still unresolved rather than that it failed; such a row is resolved by reading the chain, never by re-submitting. Common shapes, ILLUSTRATIVE rather than exhaustive: a third party’s own verdict where one was adjudicated (`amount_too_low` and the like); one of four classified prefixes where the leg could not be signed — `fee-leg insufficient-funds:` (the funding wallet cannot cover both legs), `fee-leg guard-refused:` (a misconfigured fee destination, amount or chain), `fee-leg sign-failed:` (an infrastructure fault — the RPC or signer was unavailable), `fee-leg rail-mismatch:` (a rail returned another rail’s leg; refused, not submitted); or plain prose from any other path that gives the reserve back — `upstream returned 502 — resource not delivered` for a routed hop that did not succeed (on `POST /route` this is the ordinary one), `the fee leg expired before it could be broadcast`, or a `reconciled: …` write-off from the reconciliation sweep. It ALSO answers the opposite question on a `feeStatus: None` row: `fee-not-quoted: <why>` means a fee rate is configured but none was quoted for this payment at all — no destination is set for the settlement chain, no fee submitter is usable, the rail cannot sign a fee leg, the settlement network does not map to a chain, the fee truncated below one atomic unit and could never have been transferred, or the quote was refused outright. Such a row is charged the merchant leg and nothing else, which is correct; the field is what tells a half-finished rollout collecting 0% from a deployment that never configured a fee. Diagnostic text for a human, NOT a stable contract — branch on `feeStatus`, never on this string, whose wording follows a third party on the adjudicated paths. 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: a row whose outcome was once undetermined KEEPS the reason it recorded when the chain later proves the fee settled, so a `Settled` row can carry one. `feeStatus` is the field that says what happened."
    },
    "merchantSettlementObservedAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When on-chain reconciliation OBSERVED that the merchant was really paid for this call — i.e. the money really left the paying wallet for the merchant. Reconciliation records it on every rail that settles on a chain: an EIP-3009 `exact` authorization (x402, and an MPP `evm` charge) once its nonce is consumed, an MPP-tempo `charge` once its transfer is found, and an MPP-tempo `session` call once its channel closes having captured it. On the per-call rails (x402, MPP `evm`, MPP-tempo `charge`) it is `null` on the ordinary path: a payment that settled cleanly is anchored by `txHash` and never needs this. A `session` call is the exception: its money moves only when the channel closes, so every call the close captured carries it, `Settled` ones included. A `null` is NOT, on its own, proof you were not charged: it stays `null` until reconciliation reaches a verdict, it is always `null` on the MPP-stripe card rail, which has no on-chain leg to observe, and on the other rails reconciliation can stop on a payment whose on-chain outcome it could not determine, leaving this `null`. Read it TOGETHER with `status`, which answers a different question: `status` is what you GOT, this is what you PAID. The pair that matters is `status: Failed`/`Issued` WITH this set — the merchant took the money and delivered nothing, which these rails cannot prevent (the merchant collects the payment itself, so it can always collect and then error). Deliberately NOT folded into `status`: the three status values are unchanged, so nothing that already switches on them has to change. `txHash` is filled in alongside it whenever the settlement transaction can be identified on-chain, and is left null when it cannot — no hash is ever claimed that could not be verified. So on these rows a non-null `txHash` does NOT mean the payment succeeded: keep reading `status` for that."
    },
    "paymentId": {
      "type": "string",
      "description": "Alias of `id`, named explicitly for requestId reconciliation clients."
    },
    "chargedMicros": {
      "type": [
        "string",
        "null"
      ],
      "description": "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, because their amount unit is rail-dependent and cannot be reconstructed safely."
    },
    "resultUrl": {
      "type": "string",
      "description": "Relative URL of the retained paid result. It answers Pending when a pending row exists; before the result row is written, even a running call can answer 404. It also answers 404 after retention expires, for a mode-A payment, for an unknown payment, or for a payment owned by another caller. Retention is 24 hours after the call ends. A 404 is not delivery evidence; use `deliveryStatus`. This enclosing payment row is the durable record; it remains available after the result expires."
    }
  },
  "required": [
    "id",
    "createdAt",
    "status",
    "deliveryStatus",
    "upstreamBodyBytes",
    "fundingSource",
    "creditsCharged",
    "creditsStatus",
    "protocol",
    "network",
    "amount",
    "merchantAddress",
    "delegationId",
    "buyer",
    "paymentId",
    "chargedMicros",
    "resultUrl"
  ]
}