Payment links

A1-2: required (still nullable) — every producer already emits null rather than omitting the field when there is no next page, so this only removes a third, unused wire state (absent) a strict client had to handle for nothing.

Present only with ?expand=summary (LIST-SUMMARY-1). Computed server-side over every link matching the request's status_group, q, client_id and settlement_kind (never cursor/limit), in one grouped query. by_status_group uses the status_group buckets exactly; they overlap (viewed/processing are both open and needs_attention), so they do not add up to total.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

refunded reads "Refunded" to the merchant and "Returned" to the payer on the same underlying value (R11 §3) — one enum member, two audience labels.

Labelled "Memo" on Payment Links merchant screens; the crypto-processing surfaces label this same field "Description" (R19 CP-G15) — one field, two display labels, never two schema fields.

A short, non-technical, server-minted id in CP-<n> form (e.g. CP-1042), unique per merchant. Set by the server at creation, never accepted as input. Distinct from invoice_number above, which is an optional, merchant-typed reference that may repeat or be null, and from id (the pl_-prefixed identifier), whose raw form is not meant to be shown to a payer or merchant as a reference number. Present on every payment link, not only crypto-processing ones.

A money value. amount is a minor-unit integer as a string; decimals states the scale so a client never re-derives it (USDC is 6). Floats never appear on a money path.

System-set at activation, never an input (RESOURCE-MODEL §2.1 invariants). Enum values are not published in RESOURCE-MODEL; left open rather than invented.

Computed grouping of payable_rails into the three UI kinds (RESOURCE-MODEL §2.1 v2 amendment; R11 PL-G5).

Editable while the link is draft, active or viewed (RESOURCE-MODEL §2.1). R11 PL-G3 flags a design screen that disables editing on viewed — not ratified as a rule change, so the contract keeps viewed editable.

System-set at activation, never an input (RESOURCE-MODEL §2.1 invariants; RESOURCE-MODEL §2.1 v2 amendment). Null on a draft that has not activated yet.

BL-39 (C4-D27) — the token identity frozen from settlement_snapshot at ACTIVATION, never a live chain read and never derived from a rate. null on a draft (no snapshot yet) or a non-Tempo settlement — Bridge bank/crypto destinations have no single payer-facing "token" this field describes. Carries no amount of its own.

BL-50 — the saved /v1/address_book entry create/update set as where this link's funds land. null until chosen. Read from the SAME reference activate freezes into settlement_snapshot (never cleared by activation), so it keeps reading the live destination after the link goes live too — distinct from settlement_asset above, which is the token identity frozen at that one moment.

C5-SHORT-LINK — the link's short public code (e.g. 7fq3k2c): 7 characters of lowercase Crockford base32 without the vowels a/e (so also no i, l, o, u). Minted by the server from a cryptographic random source when the link is created, for every link (draft or live, live or test mode), never accepted as input, never derived from ids, amounts, e-mails or names, and never changed afterwards. Unique across the project's links. It resolves to the payer session through GET /v1/payment_sessions/by_code/{short_code}, so treat it like url: share it with the payer only.

C5-SHORT-LINK — <payer host>/p/<short_code> (e.g. https://swaps.app/p/7fq3k2c), on the same per-project payer host as url and under the same rule: null exactly when url is null. Not yet a working payer link: it resolves only once the /p/:code page is live on that host, and only while the /v1 API is enabled; share url until then.

RESOURCE-MODEL §2.1 v2 amendment, R11 PL-G1.

crypto_relay (R19 X2) is a payer rail behind the crypto_relay_rail flag (off in production), never a stored restriction. A settlement_kind: crypto_only link offers crypto_tempo, plus crypto_relay where its gate admits it (the same on payable_rails and in the payer session): that flag and an admitted route (founder_accepted per founder §52.34, or proven; see K13-CRYPTO-RELAY-ROUTES.md). A1-2: open on THIS response field only — an unrecognized rail here is an opaque string, never a deserialization failure. The same vocabulary on PaymentLinkCreateRequest/PaymentLinkUpdateRequest stays closed: a merchant choosing an unknown rail is a real request error, not a fact to tolerate.

The rails the payer is offered now (one exception below), recomputed on every read; not a snapshot (RESOURCE-MODEL §2.1 v2 amendment). A later read can differ from an earlier one when a rail flag, a Relay route or the Relay cap changes. crypto_relay is listed exactly when the payer session of this link offers it (the same gate: the crypto_relay_rail flag for this merchant, the per-invoice cap, an admitted route for the link's Tempo settlement network, a USD link). If that gate cannot be read, crypto_relay is left out and the read still succeeds, where the payer session answers 503 temporarily_unavailable. Exception: an individual (direction: p2p) merchant whose Bridge fiat pay-in is not active yet is listed with its bank rails, although the payer session withholds them (C4-D23; tracked in #3977). Open-enum like allowed_rails above (queue item #3560) — the same forward-compatibility reasoning applies to a computed field.

A crypto_only settlement suppresses every fiat rail, so this reads [crypto] (RESOURCE-MODEL §2.1 v2 amendment; R19 §2.1).

Set only while status is processing and a payment arrived short of amount (§8.4). received reports the single MOST RECENT short payment recorded for this link's CURRENT attempt — one deposit's figure, not a running total of everything the link has received — and is null when that deposit's settled amount could not be confirmed (shown to the merchant as "needs review"). null while processing with nothing recorded, and again once the link leaves processing for a later full payment or a cancellation. A no-funds failure on an attempt moves the link to viewed and clears this field to null; it does NOT reopen the link to processing. The flag CAN reappear, but only when a LATER attempt creates a new transfer and puts the link back into processing — if that new attempt also under-pays, its own event is what reappears here, never an earlier attempt's superseded figure. The key itself may be absent when the underlying signal could not be read — that is not the same as null.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

refunded reads "Refunded" to the merchant and "Returned" to the payer on the same underlying value (R11 §3) — one enum member, two audience labels.

Labelled "Memo" on Payment Links merchant screens; the crypto-processing surfaces label this same field "Description" (R19 CP-G15) — one field, two display labels, never two schema fields.

A short, non-technical, server-minted id in CP-<n> form (e.g. CP-1042), unique per merchant. Set by the server at creation, never accepted as input. Distinct from invoice_number above, which is an optional, merchant-typed reference that may repeat or be null, and from id (the pl_-prefixed identifier), whose raw form is not meant to be shown to a payer or merchant as a reference number. Present on every payment link, not only crypto-processing ones.

A money value. amount is a minor-unit integer as a string; decimals states the scale so a client never re-derives it (USDC is 6). Floats never appear on a money path.

System-set at activation, never an input (RESOURCE-MODEL §2.1 invariants). Enum values are not published in RESOURCE-MODEL; left open rather than invented.

Computed grouping of payable_rails into the three UI kinds (RESOURCE-MODEL §2.1 v2 amendment; R11 PL-G5).

Editable while the link is draft, active or viewed (RESOURCE-MODEL §2.1). R11 PL-G3 flags a design screen that disables editing on viewed — not ratified as a rule change, so the contract keeps viewed editable.

System-set at activation, never an input (RESOURCE-MODEL §2.1 invariants; RESOURCE-MODEL §2.1 v2 amendment). Null on a draft that has not activated yet.

BL-39 (C4-D27) — the token identity frozen from settlement_snapshot at ACTIVATION, never a live chain read and never derived from a rate. null on a draft (no snapshot yet) or a non-Tempo settlement — Bridge bank/crypto destinations have no single payer-facing "token" this field describes. Carries no amount of its own.

BL-50 — the saved /v1/address_book entry create/update set as where this link's funds land. null until chosen. Read from the SAME reference activate freezes into settlement_snapshot (never cleared by activation), so it keeps reading the live destination after the link goes live too — distinct from settlement_asset above, which is the token identity frozen at that one moment.

C5-SHORT-LINK — the link's short public code (e.g. 7fq3k2c): 7 characters of lowercase Crockford base32 without the vowels a/e (so also no i, l, o, u). Minted by the server from a cryptographic random source when the link is created, for every link (draft or live, live or test mode), never accepted as input, never derived from ids, amounts, e-mails or names, and never changed afterwards. Unique across the project's links. It resolves to the payer session through GET /v1/payment_sessions/by_code/{short_code}, so treat it like url: share it with the payer only.

C5-SHORT-LINK — <payer host>/p/<short_code> (e.g. https://swaps.app/p/7fq3k2c), on the same per-project payer host as url and under the same rule: null exactly when url is null. Not yet a working payer link: it resolves only once the /p/:code page is live on that host, and only while the /v1 API is enabled; share url until then.

RESOURCE-MODEL §2.1 v2 amendment, R11 PL-G1.

crypto_relay (R19 X2) is a payer rail behind the crypto_relay_rail flag (off in production), never a stored restriction. A settlement_kind: crypto_only link offers crypto_tempo, plus crypto_relay where its gate admits it (the same on payable_rails and in the payer session): that flag and an admitted route (founder_accepted per founder §52.34, or proven; see K13-CRYPTO-RELAY-ROUTES.md). A1-2: open on THIS response field only — an unrecognized rail here is an opaque string, never a deserialization failure. The same vocabulary on PaymentLinkCreateRequest/PaymentLinkUpdateRequest stays closed: a merchant choosing an unknown rail is a real request error, not a fact to tolerate.

The rails the payer is offered now (one exception below), recomputed on every read; not a snapshot (RESOURCE-MODEL §2.1 v2 amendment). A later read can differ from an earlier one when a rail flag, a Relay route or the Relay cap changes. crypto_relay is listed exactly when the payer session of this link offers it (the same gate: the crypto_relay_rail flag for this merchant, the per-invoice cap, an admitted route for the link's Tempo settlement network, a USD link). If that gate cannot be read, crypto_relay is left out and the read still succeeds, where the payer session answers 503 temporarily_unavailable. Exception: an individual (direction: p2p) merchant whose Bridge fiat pay-in is not active yet is listed with its bank rails, although the payer session withholds them (C4-D23; tracked in #3977). Open-enum like allowed_rails above (queue item #3560) — the same forward-compatibility reasoning applies to a computed field.

A crypto_only settlement suppresses every fiat rail, so this reads [crypto] (RESOURCE-MODEL §2.1 v2 amendment; R19 §2.1).

Set only while status is processing and a payment arrived short of amount (§8.4). received reports the single MOST RECENT short payment recorded for this link's CURRENT attempt — one deposit's figure, not a running total of everything the link has received — and is null when that deposit's settled amount could not be confirmed (shown to the merchant as "needs review"). null while processing with nothing recorded, and again once the link leaves processing for a later full payment or a cancellation. A no-funds failure on an attempt moves the link to viewed and clears this field to null; it does NOT reopen the link to processing. The flag CAN reappear, but only when a LATER attempt creates a new transfer and puts the link back into processing — if that new attempt also under-pays, its own event is what reappears here, never an earlier attempt's superseded figure. The key itself may be absent when the underlying signal could not be read — that is not the same as null.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

refunded reads "Refunded" to the merchant and "Returned" to the payer on the same underlying value (R11 §3) — one enum member, two audience labels.

Labelled "Memo" on Payment Links merchant screens; the crypto-processing surfaces label this same field "Description" (R19 CP-G15) — one field, two display labels, never two schema fields.

A short, non-technical, server-minted id in CP-<n> form (e.g. CP-1042), unique per merchant. Set by the server at creation, never accepted as input. Distinct from invoice_number above, which is an optional, merchant-typed reference that may repeat or be null, and from id (the pl_-prefixed identifier), whose raw form is not meant to be shown to a payer or merchant as a reference number. Present on every payment link, not only crypto-processing ones.

A money value. amount is a minor-unit integer as a string; decimals states the scale so a client never re-derives it (USDC is 6). Floats never appear on a money path.

System-set at activation, never an input (RESOURCE-MODEL §2.1 invariants). Enum values are not published in RESOURCE-MODEL; left open rather than invented.

Computed grouping of payable_rails into the three UI kinds (RESOURCE-MODEL §2.1 v2 amendment; R11 PL-G5).

Editable while the link is draft, active or viewed (RESOURCE-MODEL §2.1). R11 PL-G3 flags a design screen that disables editing on viewed — not ratified as a rule change, so the contract keeps viewed editable.

System-set at activation, never an input (RESOURCE-MODEL §2.1 invariants; RESOURCE-MODEL §2.1 v2 amendment). Null on a draft that has not activated yet.

BL-39 (C4-D27) — the token identity frozen from settlement_snapshot at ACTIVATION, never a live chain read and never derived from a rate. null on a draft (no snapshot yet) or a non-Tempo settlement — Bridge bank/crypto destinations have no single payer-facing "token" this field describes. Carries no amount of its own.

BL-50 — the saved /v1/address_book entry create/update set as where this link's funds land. null until chosen. Read from the SAME reference activate freezes into settlement_snapshot (never cleared by activation), so it keeps reading the live destination after the link goes live too — distinct from settlement_asset above, which is the token identity frozen at that one moment.

C5-SHORT-LINK — the link's short public code (e.g. 7fq3k2c): 7 characters of lowercase Crockford base32 without the vowels a/e (so also no i, l, o, u). Minted by the server from a cryptographic random source when the link is created, for every link (draft or live, live or test mode), never accepted as input, never derived from ids, amounts, e-mails or names, and never changed afterwards. Unique across the project's links. It resolves to the payer session through GET /v1/payment_sessions/by_code/{short_code}, so treat it like url: share it with the payer only.

C5-SHORT-LINK — <payer host>/p/<short_code> (e.g. https://swaps.app/p/7fq3k2c), on the same per-project payer host as url and under the same rule: null exactly when url is null. Not yet a working payer link: it resolves only once the /p/:code page is live on that host, and only while the /v1 API is enabled; share url until then.

RESOURCE-MODEL §2.1 v2 amendment, R11 PL-G1.

crypto_relay (R19 X2) is a payer rail behind the crypto_relay_rail flag (off in production), never a stored restriction. A settlement_kind: crypto_only link offers crypto_tempo, plus crypto_relay where its gate admits it (the same on payable_rails and in the payer session): that flag and an admitted route (founder_accepted per founder §52.34, or proven; see K13-CRYPTO-RELAY-ROUTES.md). A1-2: open on THIS response field only — an unrecognized rail here is an opaque string, never a deserialization failure. The same vocabulary on PaymentLinkCreateRequest/PaymentLinkUpdateRequest stays closed: a merchant choosing an unknown rail is a real request error, not a fact to tolerate.

The rails the payer is offered now (one exception below), recomputed on every read; not a snapshot (RESOURCE-MODEL §2.1 v2 amendment). A later read can differ from an earlier one when a rail flag, a Relay route or the Relay cap changes. crypto_relay is listed exactly when the payer session of this link offers it (the same gate: the crypto_relay_rail flag for this merchant, the per-invoice cap, an admitted route for the link's Tempo settlement network, a USD link). If that gate cannot be read, crypto_relay is left out and the read still succeeds, where the payer session answers 503 temporarily_unavailable. Exception: an individual (direction: p2p) merchant whose Bridge fiat pay-in is not active yet is listed with its bank rails, although the payer session withholds them (C4-D23; tracked in #3977). Open-enum like allowed_rails above (queue item #3560) — the same forward-compatibility reasoning applies to a computed field.

A crypto_only settlement suppresses every fiat rail, so this reads [crypto] (RESOURCE-MODEL §2.1 v2 amendment; R19 §2.1).

Set only while status is processing and a payment arrived short of amount (§8.4). received reports the single MOST RECENT short payment recorded for this link's CURRENT attempt — one deposit's figure, not a running total of everything the link has received — and is null when that deposit's settled amount could not be confirmed (shown to the merchant as "needs review"). null while processing with nothing recorded, and again once the link leaves processing for a later full payment or a cancellation. A no-funds failure on an attempt moves the link to viewed and clears this field to null; it does NOT reopen the link to processing. The flag CAN reappear, but only when a LATER attempt creates a new transfer and puts the link back into processing — if that new attempt also under-pays, its own event is what reappears here, never an earlier attempt's superseded figure. The key itself may be absent when the underlying signal could not be read — that is not the same as null.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

refunded reads "Refunded" to the merchant and "Returned" to the payer on the same underlying value (R11 §3) — one enum member, two audience labels.

Labelled "Memo" on Payment Links merchant screens; the crypto-processing surfaces label this same field "Description" (R19 CP-G15) — one field, two display labels, never two schema fields.

A short, non-technical, server-minted id in CP-<n> form (e.g. CP-1042), unique per merchant. Set by the server at creation, never accepted as input. Distinct from invoice_number above, which is an optional, merchant-typed reference that may repeat or be null, and from id (the pl_-prefixed identifier), whose raw form is not meant to be shown to a payer or merchant as a reference number. Present on every payment link, not only crypto-processing ones.

A money value. amount is a minor-unit integer as a string; decimals states the scale so a client never re-derives it (USDC is 6). Floats never appear on a money path.

System-set at activation, never an input (RESOURCE-MODEL §2.1 invariants). Enum values are not published in RESOURCE-MODEL; left open rather than invented.

Computed grouping of payable_rails into the three UI kinds (RESOURCE-MODEL §2.1 v2 amendment; R11 PL-G5).

Editable while the link is draft, active or viewed (RESOURCE-MODEL §2.1). R11 PL-G3 flags a design screen that disables editing on viewed — not ratified as a rule change, so the contract keeps viewed editable.

System-set at activation, never an input (RESOURCE-MODEL §2.1 invariants; RESOURCE-MODEL §2.1 v2 amendment). Null on a draft that has not activated yet.

BL-39 (C4-D27) — the token identity frozen from settlement_snapshot at ACTIVATION, never a live chain read and never derived from a rate. null on a draft (no snapshot yet) or a non-Tempo settlement — Bridge bank/crypto destinations have no single payer-facing "token" this field describes. Carries no amount of its own.

BL-50 — the saved /v1/address_book entry create/update set as where this link's funds land. null until chosen. Read from the SAME reference activate freezes into settlement_snapshot (never cleared by activation), so it keeps reading the live destination after the link goes live too — distinct from settlement_asset above, which is the token identity frozen at that one moment.

C5-SHORT-LINK — the link's short public code (e.g. 7fq3k2c): 7 characters of lowercase Crockford base32 without the vowels a/e (so also no i, l, o, u). Minted by the server from a cryptographic random source when the link is created, for every link (draft or live, live or test mode), never accepted as input, never derived from ids, amounts, e-mails or names, and never changed afterwards. Unique across the project's links. It resolves to the payer session through GET /v1/payment_sessions/by_code/{short_code}, so treat it like url: share it with the payer only.

C5-SHORT-LINK — <payer host>/p/<short_code> (e.g. https://swaps.app/p/7fq3k2c), on the same per-project payer host as url and under the same rule: null exactly when url is null. Not yet a working payer link: it resolves only once the /p/:code page is live on that host, and only while the /v1 API is enabled; share url until then.

RESOURCE-MODEL §2.1 v2 amendment, R11 PL-G1.

crypto_relay (R19 X2) is a payer rail behind the crypto_relay_rail flag (off in production), never a stored restriction. A settlement_kind: crypto_only link offers crypto_tempo, plus crypto_relay where its gate admits it (the same on payable_rails and in the payer session): that flag and an admitted route (founder_accepted per founder §52.34, or proven; see K13-CRYPTO-RELAY-ROUTES.md). A1-2: open on THIS response field only — an unrecognized rail here is an opaque string, never a deserialization failure. The same vocabulary on PaymentLinkCreateRequest/PaymentLinkUpdateRequest stays closed: a merchant choosing an unknown rail is a real request error, not a fact to tolerate.

The rails the payer is offered now (one exception below), recomputed on every read; not a snapshot (RESOURCE-MODEL §2.1 v2 amendment). A later read can differ from an earlier one when a rail flag, a Relay route or the Relay cap changes. crypto_relay is listed exactly when the payer session of this link offers it (the same gate: the crypto_relay_rail flag for this merchant, the per-invoice cap, an admitted route for the link's Tempo settlement network, a USD link). If that gate cannot be read, crypto_relay is left out and the read still succeeds, where the payer session answers 503 temporarily_unavailable. Exception: an individual (direction: p2p) merchant whose Bridge fiat pay-in is not active yet is listed with its bank rails, although the payer session withholds them (C4-D23; tracked in #3977). Open-enum like allowed_rails above (queue item #3560) — the same forward-compatibility reasoning applies to a computed field.

A crypto_only settlement suppresses every fiat rail, so this reads [crypto] (RESOURCE-MODEL §2.1 v2 amendment; R19 §2.1).

Set only while status is processing and a payment arrived short of amount (§8.4). received reports the single MOST RECENT short payment recorded for this link's CURRENT attempt — one deposit's figure, not a running total of everything the link has received — and is null when that deposit's settled amount could not be confirmed (shown to the merchant as "needs review"). null while processing with nothing recorded, and again once the link leaves processing for a later full payment or a cancellation. A no-funds failure on an attempt moves the link to viewed and clears this field to null; it does NOT reopen the link to processing. The flag CAN reappear, but only when a LATER attempt creates a new transfer and puts the link back into processing — if that new attempt also under-pays, its own event is what reappears here, never an earlier attempt's superseded figure. The key itself may be absent when the underlying signal could not be read — that is not the same as null.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

refunded reads "Refunded" to the merchant and "Returned" to the payer on the same underlying value (R11 §3) — one enum member, two audience labels.

Labelled "Memo" on Payment Links merchant screens; the crypto-processing surfaces label this same field "Description" (R19 CP-G15) — one field, two display labels, never two schema fields.

A short, non-technical, server-minted id in CP-<n> form (e.g. CP-1042), unique per merchant. Set by the server at creation, never accepted as input. Distinct from invoice_number above, which is an optional, merchant-typed reference that may repeat or be null, and from id (the pl_-prefixed identifier), whose raw form is not meant to be shown to a payer or merchant as a reference number. Present on every payment link, not only crypto-processing ones.

A money value. amount is a minor-unit integer as a string; decimals states the scale so a client never re-derives it (USDC is 6). Floats never appear on a money path.

System-set at activation, never an input (RESOURCE-MODEL §2.1 invariants). Enum values are not published in RESOURCE-MODEL; left open rather than invented.

Computed grouping of payable_rails into the three UI kinds (RESOURCE-MODEL §2.1 v2 amendment; R11 PL-G5).

Editable while the link is draft, active or viewed (RESOURCE-MODEL §2.1). R11 PL-G3 flags a design screen that disables editing on viewed — not ratified as a rule change, so the contract keeps viewed editable.

System-set at activation, never an input (RESOURCE-MODEL §2.1 invariants; RESOURCE-MODEL §2.1 v2 amendment). Null on a draft that has not activated yet.

BL-39 (C4-D27) — the token identity frozen from settlement_snapshot at ACTIVATION, never a live chain read and never derived from a rate. null on a draft (no snapshot yet) or a non-Tempo settlement — Bridge bank/crypto destinations have no single payer-facing "token" this field describes. Carries no amount of its own.

BL-50 — the saved /v1/address_book entry create/update set as where this link's funds land. null until chosen. Read from the SAME reference activate freezes into settlement_snapshot (never cleared by activation), so it keeps reading the live destination after the link goes live too — distinct from settlement_asset above, which is the token identity frozen at that one moment.

C5-SHORT-LINK — the link's short public code (e.g. 7fq3k2c): 7 characters of lowercase Crockford base32 without the vowels a/e (so also no i, l, o, u). Minted by the server from a cryptographic random source when the link is created, for every link (draft or live, live or test mode), never accepted as input, never derived from ids, amounts, e-mails or names, and never changed afterwards. Unique across the project's links. It resolves to the payer session through GET /v1/payment_sessions/by_code/{short_code}, so treat it like url: share it with the payer only.

C5-SHORT-LINK — <payer host>/p/<short_code> (e.g. https://swaps.app/p/7fq3k2c), on the same per-project payer host as url and under the same rule: null exactly when url is null. Not yet a working payer link: it resolves only once the /p/:code page is live on that host, and only while the /v1 API is enabled; share url until then.

RESOURCE-MODEL §2.1 v2 amendment, R11 PL-G1.

crypto_relay (R19 X2) is a payer rail behind the crypto_relay_rail flag (off in production), never a stored restriction. A settlement_kind: crypto_only link offers crypto_tempo, plus crypto_relay where its gate admits it (the same on payable_rails and in the payer session): that flag and an admitted route (founder_accepted per founder §52.34, or proven; see K13-CRYPTO-RELAY-ROUTES.md). A1-2: open on THIS response field only — an unrecognized rail here is an opaque string, never a deserialization failure. The same vocabulary on PaymentLinkCreateRequest/PaymentLinkUpdateRequest stays closed: a merchant choosing an unknown rail is a real request error, not a fact to tolerate.

The rails the payer is offered now (one exception below), recomputed on every read; not a snapshot (RESOURCE-MODEL §2.1 v2 amendment). A later read can differ from an earlier one when a rail flag, a Relay route or the Relay cap changes. crypto_relay is listed exactly when the payer session of this link offers it (the same gate: the crypto_relay_rail flag for this merchant, the per-invoice cap, an admitted route for the link's Tempo settlement network, a USD link). If that gate cannot be read, crypto_relay is left out and the read still succeeds, where the payer session answers 503 temporarily_unavailable. Exception: an individual (direction: p2p) merchant whose Bridge fiat pay-in is not active yet is listed with its bank rails, although the payer session withholds them (C4-D23; tracked in #3977). Open-enum like allowed_rails above (queue item #3560) — the same forward-compatibility reasoning applies to a computed field.

A crypto_only settlement suppresses every fiat rail, so this reads [crypto] (RESOURCE-MODEL §2.1 v2 amendment; R19 §2.1).

Set only while status is processing and a payment arrived short of amount (§8.4). received reports the single MOST RECENT short payment recorded for this link's CURRENT attempt — one deposit's figure, not a running total of everything the link has received — and is null when that deposit's settled amount could not be confirmed (shown to the merchant as "needs review"). null while processing with nothing recorded, and again once the link leaves processing for a later full payment or a cancellation. A no-funds failure on an attempt moves the link to viewed and clears this field to null; it does NOT reopen the link to processing. The flag CAN reappear, but only when a LATER attempt creates a new transfer and puts the link back into processing — if that new attempt also under-pays, its own event is what reappears here, never an earlier attempt's superseded figure. The key itself may be absent when the underlying signal could not be read — that is not the same as null.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

refunded reads "Refunded" to the merchant and "Returned" to the payer on the same underlying value (R11 §3) — one enum member, two audience labels.

Labelled "Memo" on Payment Links merchant screens; the crypto-processing surfaces label this same field "Description" (R19 CP-G15) — one field, two display labels, never two schema fields.

A short, non-technical, server-minted id in CP-<n> form (e.g. CP-1042), unique per merchant. Set by the server at creation, never accepted as input. Distinct from invoice_number above, which is an optional, merchant-typed reference that may repeat or be null, and from id (the pl_-prefixed identifier), whose raw form is not meant to be shown to a payer or merchant as a reference number. Present on every payment link, not only crypto-processing ones.

A money value. amount is a minor-unit integer as a string; decimals states the scale so a client never re-derives it (USDC is 6). Floats never appear on a money path.

System-set at activation, never an input (RESOURCE-MODEL §2.1 invariants). Enum values are not published in RESOURCE-MODEL; left open rather than invented.

Computed grouping of payable_rails into the three UI kinds (RESOURCE-MODEL §2.1 v2 amendment; R11 PL-G5).

Editable while the link is draft, active or viewed (RESOURCE-MODEL §2.1). R11 PL-G3 flags a design screen that disables editing on viewed — not ratified as a rule change, so the contract keeps viewed editable.

System-set at activation, never an input (RESOURCE-MODEL §2.1 invariants; RESOURCE-MODEL §2.1 v2 amendment). Null on a draft that has not activated yet.

BL-39 (C4-D27) — the token identity frozen from settlement_snapshot at ACTIVATION, never a live chain read and never derived from a rate. null on a draft (no snapshot yet) or a non-Tempo settlement — Bridge bank/crypto destinations have no single payer-facing "token" this field describes. Carries no amount of its own.

BL-50 — the saved /v1/address_book entry create/update set as where this link's funds land. null until chosen. Read from the SAME reference activate freezes into settlement_snapshot (never cleared by activation), so it keeps reading the live destination after the link goes live too — distinct from settlement_asset above, which is the token identity frozen at that one moment.

C5-SHORT-LINK — the link's short public code (e.g. 7fq3k2c): 7 characters of lowercase Crockford base32 without the vowels a/e (so also no i, l, o, u). Minted by the server from a cryptographic random source when the link is created, for every link (draft or live, live or test mode), never accepted as input, never derived from ids, amounts, e-mails or names, and never changed afterwards. Unique across the project's links. It resolves to the payer session through GET /v1/payment_sessions/by_code/{short_code}, so treat it like url: share it with the payer only.

C5-SHORT-LINK — <payer host>/p/<short_code> (e.g. https://swaps.app/p/7fq3k2c), on the same per-project payer host as url and under the same rule: null exactly when url is null. Not yet a working payer link: it resolves only once the /p/:code page is live on that host, and only while the /v1 API is enabled; share url until then.

RESOURCE-MODEL §2.1 v2 amendment, R11 PL-G1.

crypto_relay (R19 X2) is a payer rail behind the crypto_relay_rail flag (off in production), never a stored restriction. A settlement_kind: crypto_only link offers crypto_tempo, plus crypto_relay where its gate admits it (the same on payable_rails and in the payer session): that flag and an admitted route (founder_accepted per founder §52.34, or proven; see K13-CRYPTO-RELAY-ROUTES.md). A1-2: open on THIS response field only — an unrecognized rail here is an opaque string, never a deserialization failure. The same vocabulary on PaymentLinkCreateRequest/PaymentLinkUpdateRequest stays closed: a merchant choosing an unknown rail is a real request error, not a fact to tolerate.

The rails the payer is offered now (one exception below), recomputed on every read; not a snapshot (RESOURCE-MODEL §2.1 v2 amendment). A later read can differ from an earlier one when a rail flag, a Relay route or the Relay cap changes. crypto_relay is listed exactly when the payer session of this link offers it (the same gate: the crypto_relay_rail flag for this merchant, the per-invoice cap, an admitted route for the link's Tempo settlement network, a USD link). If that gate cannot be read, crypto_relay is left out and the read still succeeds, where the payer session answers 503 temporarily_unavailable. Exception: an individual (direction: p2p) merchant whose Bridge fiat pay-in is not active yet is listed with its bank rails, although the payer session withholds them (C4-D23; tracked in #3977). Open-enum like allowed_rails above (queue item #3560) — the same forward-compatibility reasoning applies to a computed field.

A crypto_only settlement suppresses every fiat rail, so this reads [crypto] (RESOURCE-MODEL §2.1 v2 amendment; R19 §2.1).

Set only while status is processing and a payment arrived short of amount (§8.4). received reports the single MOST RECENT short payment recorded for this link's CURRENT attempt — one deposit's figure, not a running total of everything the link has received — and is null when that deposit's settled amount could not be confirmed (shown to the merchant as "needs review"). null while processing with nothing recorded, and again once the link leaves processing for a later full payment or a cancellation. A no-funds failure on an attempt moves the link to viewed and clears this field to null; it does NOT reopen the link to processing. The flag CAN reappear, but only when a LATER attempt creates a new transfer and puts the link back into processing — if that new attempt also under-pays, its own event is what reappears here, never an earlier attempt's superseded figure. The key itself may be absent when the underlying signal could not be read — that is not the same as null.

Caller-owned.

Server-owned (RESOURCE-MODEL §2.1). A caller-supplied value here is ignored, not merged.

Computed convenience field (RESOURCE-MODEL §2.1 v2 amendment; R11 PL-G17).

Caller-owned.

Server-owned (RESOURCE-MODEL §2.1). A caller-supplied value here is ignored, not merged.

Computed convenience field (RESOURCE-MODEL §2.1 v2 amendment; R11 PL-G17).

Caller-owned.

Server-owned (RESOURCE-MODEL §2.1). A caller-supplied value here is ignored, not merged.

Computed convenience field (RESOURCE-MODEL §2.1 v2 amendment; R11 PL-G17).

A1-2: required (still nullable) — every producer already emits null rather than omitting the field when there is no next page, so this only removes a third, unused wire state (absent) a strict client had to handle for nothing.

The payment (attempt) that completed the link — GET /v1/payments/{id} returns it.

What the link asked for, in its own currency — the ask, not an observation.

The rail the completing payment used (a Payment.payment_rail value).

The observed on-chain deposit for a crypto_tempo payment, in the token that arrived (same value as Payment.amount_received). null on every other rail.

The provider's reference for a provider-routed payment — the transfer id, or the deposit id for a payment collected on a collection account (virtual account); null for crypto_tempo.

The 1% Swaps fee, payer-borne — same value as Payment.fee for payment_id (exact server arithmetic on crypto_tempo; null on rails where the payment projection publishes none). It is why a crypto_tempo amount_received exceeds amount.

The Swaps fee deducted from what arrived on a Bridge-routed rail — same value as Payment.deducted_fee for payment_id (the provider receipt's figure); null on crypto_tempo/crypto_relay, when the payer paid in another currency than the invoice, and while no consistent receipt is recorded.

What the merchant receives — same value as Payment.net_amount for payment_id: the invoice amount on crypto_tempo/crypto_relay once settled; on a Bridge-routed rail the provider receipt's figure (what arrived minus deducted_fee, in the invoice currency, before conversion), null without one; null before settlement.

Same value as PaymentLink.settlement_kind.

Where the funds land, masked as a reference — same value as PaymentLink.settlement_destination; never a raw address or bank detail.

null while the link is paid and not yet settled.

The link's own memo.

What the merchant received, provider-confirmed. OMITTED today, never null and never the invoice amount: the received figure is recorded on the link's paid event (checked against the invoice within a 1% tolerance) but is not yet published as a provider-confirmed amount. net_amount is the server arithmetic, not this confirmation.

A1-2: required (still nullable) — every producer already emits null rather than omitting the field when there is no next page, so this only removes a third, unused wire state (absent) a strict client had to handle for nothing.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

Free text today. R11 PL-G13 is an open ruling on whether this narrows to a closed enum — left as free text pending that ruling.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.