From a7be4022e9bff743d05272a74849aaf85c5a4044 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 29 Jun 2026 22:07:22 +0000 Subject: [PATCH 1/2] feat(openapi): add rail + settlement-timing fields to OutgoingTransaction Add four optional, nullable fields to the OutgoingTransaction schema so the rail and settlement-timing data that sparkcore already emits on outgoing_payment.* webhooks becomes first-class in the typed API model: - paymentRail: nullable PaymentRail enum, the rail used to settle the txn - railSelectionMode: nullable AUTO/MANUAL enum (new RailSelectionMode schema) - expectedSettlementAt: nullable date-time of expected settlement - settlementTimelineSeconds: nullable integer seconds to settlement All four are additive and backward-compatible: not in `required`, and nullable for instant rails, AUTO mode before a rail is resolved, and non-direct-destination transactions. Bump the spec version to 2026-06-29, rebundle openapi.yaml + mintlify/openapi.yaml, and surface the new fields in the ramps outgoing-payment webhook payload example. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01FTtfvC6Qcsh3M62jVaCT1Y --- mintlify/openapi.yaml | 30 +++++++++++++++++- mintlify/ramps/platform-tools/webhooks.mdx | 6 +++- openapi.yaml | 30 +++++++++++++++++- .../schemas/common/RailSelectionMode.yaml | 8 +++++ .../transactions/OutgoingTransaction.yaml | 31 +++++++++++++++++++ openapi/openapi.yaml | 2 +- 6 files changed, 103 insertions(+), 4 deletions(-) create mode 100644 openapi/components/schemas/common/RailSelectionMode.yaml diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 47ae971f5..131c2e341 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -3,7 +3,7 @@ info: title: Grid API description: | API for managing global payments on the open Money Grid. Built by Lightspark. See the full documentation at https://docs.lightspark.com/. - version: '2026-06-25' + version: '2026-06-29' contact: name: Lightspark Support email: support@lightspark.com @@ -17176,6 +17176,13 @@ components: - FUNDING_AMOUNT_MISMATCH - COUNTERPARTY_POST_TX_FAILED description: Reason for failure of an outgoing transaction. This is used to provide more context on why a transaction failed. If the transaction is not in a failed state, this field is omitted. + RailSelectionMode: + type: string + enum: + - AUTO + - MANUAL + description: How the payment rail was chosen — MANUAL when the platform specified a paymentRail on the destination, AUTO when Lightspark selects it. + example: AUTO OutgoingTransaction: title: Outgoing Transaction allOf: @@ -17248,6 +17255,27 @@ components: failureReason: $ref: '#/components/schemas/OutgoingTransactionFailureReason' description: If the transaction failed, this field provides the reason for failure. + paymentRail: + anyOf: + - $ref: '#/components/schemas/PaymentRail' + - type: 'null' + description: The payment rail used to settle this transaction (e.g. ACH, WIRE, NEFT, FASTER_PAYMENTS). Uses the same values as the PaymentRail sent on quote requests. Null until a rail is resolved. + railSelectionMode: + anyOf: + - $ref: '#/components/schemas/RailSelectionMode' + - type: 'null' + description: How the rail was chosen — MANUAL when the platform specified a paymentRail on the destination, AUTO when Lightspark selects it. Null when no rail is resolved. + expectedSettlementAt: + type: + - string + - 'null' + format: date-time + description: Expected settlement time at the beneficiary. Null when not yet known (e.g. instant rails, or before a rail is resolved). + settlementTimelineSeconds: + type: + - integer + - 'null' + description: Expected number of seconds from quote creation to settlement. Null when not yet known. CardTransactionStatus: type: string enum: diff --git a/mintlify/ramps/platform-tools/webhooks.mdx b/mintlify/ramps/platform-tools/webhooks.mdx index d782d4ccc..db4bcff8d 100644 --- a/mintlify/ramps/platform-tools/webhooks.mdx +++ b/mintlify/ramps/platform-tools/webhooks.mdx @@ -37,7 +37,11 @@ Grid sends webhooks for key events in the ramp lifecycle: "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001", "settledAt": "2025-10-03T15:02:30Z", "exchangeRate": 9.5, - "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006" + "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006", + "paymentRail": "ACH", + "railSelectionMode": "AUTO", + "expectedSettlementAt": "2025-10-04T15:00:00Z", + "settlementTimelineSeconds": 86400 } } ``` diff --git a/openapi.yaml b/openapi.yaml index 47ae971f5..131c2e341 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -3,7 +3,7 @@ info: title: Grid API description: | API for managing global payments on the open Money Grid. Built by Lightspark. See the full documentation at https://docs.lightspark.com/. - version: '2026-06-25' + version: '2026-06-29' contact: name: Lightspark Support email: support@lightspark.com @@ -17176,6 +17176,13 @@ components: - FUNDING_AMOUNT_MISMATCH - COUNTERPARTY_POST_TX_FAILED description: Reason for failure of an outgoing transaction. This is used to provide more context on why a transaction failed. If the transaction is not in a failed state, this field is omitted. + RailSelectionMode: + type: string + enum: + - AUTO + - MANUAL + description: How the payment rail was chosen — MANUAL when the platform specified a paymentRail on the destination, AUTO when Lightspark selects it. + example: AUTO OutgoingTransaction: title: Outgoing Transaction allOf: @@ -17248,6 +17255,27 @@ components: failureReason: $ref: '#/components/schemas/OutgoingTransactionFailureReason' description: If the transaction failed, this field provides the reason for failure. + paymentRail: + anyOf: + - $ref: '#/components/schemas/PaymentRail' + - type: 'null' + description: The payment rail used to settle this transaction (e.g. ACH, WIRE, NEFT, FASTER_PAYMENTS). Uses the same values as the PaymentRail sent on quote requests. Null until a rail is resolved. + railSelectionMode: + anyOf: + - $ref: '#/components/schemas/RailSelectionMode' + - type: 'null' + description: How the rail was chosen — MANUAL when the platform specified a paymentRail on the destination, AUTO when Lightspark selects it. Null when no rail is resolved. + expectedSettlementAt: + type: + - string + - 'null' + format: date-time + description: Expected settlement time at the beneficiary. Null when not yet known (e.g. instant rails, or before a rail is resolved). + settlementTimelineSeconds: + type: + - integer + - 'null' + description: Expected number of seconds from quote creation to settlement. Null when not yet known. CardTransactionStatus: type: string enum: diff --git a/openapi/components/schemas/common/RailSelectionMode.yaml b/openapi/components/schemas/common/RailSelectionMode.yaml new file mode 100644 index 000000000..a5ff3a846 --- /dev/null +++ b/openapi/components/schemas/common/RailSelectionMode.yaml @@ -0,0 +1,8 @@ +type: string +enum: + - AUTO + - MANUAL +description: >- + How the payment rail was chosen — MANUAL when the platform specified a + paymentRail on the destination, AUTO when Lightspark selects it. +example: AUTO diff --git a/openapi/components/schemas/transactions/OutgoingTransaction.yaml b/openapi/components/schemas/transactions/OutgoingTransaction.yaml index 5b51c7450..7bc6c0b33 100644 --- a/openapi/components/schemas/transactions/OutgoingTransaction.yaml +++ b/openapi/components/schemas/transactions/OutgoingTransaction.yaml @@ -73,3 +73,34 @@ allOf: failureReason: $ref: ./OutgoingTransactionFailureReason.yaml description: If the transaction failed, this field provides the reason for failure. + paymentRail: + anyOf: + - $ref: ../common/PaymentRail.yaml + - type: 'null' + description: >- + The payment rail used to settle this transaction (e.g. ACH, WIRE, + NEFT, FASTER_PAYMENTS). Uses the same values as the PaymentRail sent + on quote requests. Null until a rail is resolved. + railSelectionMode: + anyOf: + - $ref: ../common/RailSelectionMode.yaml + - type: 'null' + description: >- + How the rail was chosen — MANUAL when the platform specified a + paymentRail on the destination, AUTO when Lightspark selects it. Null + when no rail is resolved. + expectedSettlementAt: + type: + - string + - 'null' + format: date-time + description: >- + Expected settlement time at the beneficiary. Null when not yet known + (e.g. instant rails, or before a rail is resolved). + settlementTimelineSeconds: + type: + - integer + - 'null' + description: >- + Expected number of seconds from quote creation to settlement. Null + when not yet known. diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index dbd09c840..674dd22ad 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -4,7 +4,7 @@ info: title: Grid API description: > API for managing global payments on the open Money Grid. Built by Lightspark. See the full documentation at https://docs.lightspark.com/. - version: "2026-06-25" + version: "2026-06-29" contact: name: Lightspark Support email: support@lightspark.com From 28bb04f3a82a7f45edaa6ffa259665397bf796f4 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 29 Jun 2026 22:29:35 +0000 Subject: [PATCH 2/2] docs(openapi): clarify paymentRail/expectedSettlementAt null semantics MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address review feedback on OutgoingTransaction field descriptions: - paymentRail: replace "Null until a rail is resolved" (which implied the field always eventually becomes non-null) with an accurate description of the permanent-null cases — instant/intra-network transfers and non-direct-destination transactions — as well as the pre-resolution case. - expectedSettlementAt: instant rails settle immediately (time is known, not "not yet known"); reword so it's null for instant rails and before a deferred-settlement rail is resolved. Wording only; no schema, type, or required-field changes. Rebundled. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01FTtfvC6Qcsh3M62jVaCT1Y --- mintlify/openapi.yaml | 4 ++-- openapi.yaml | 4 ++-- .../schemas/transactions/OutgoingTransaction.yaml | 9 ++++++--- 3 files changed, 10 insertions(+), 7 deletions(-) diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 131c2e341..a0caaf16e 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -17259,7 +17259,7 @@ components: anyOf: - $ref: '#/components/schemas/PaymentRail' - type: 'null' - description: The payment rail used to settle this transaction (e.g. ACH, WIRE, NEFT, FASTER_PAYMENTS). Uses the same values as the PaymentRail sent on quote requests. Null until a rail is resolved. + description: The payment rail used to settle this transaction (e.g. ACH, WIRE, NEFT, FASTER_PAYMENTS). Uses the same values as the PaymentRail sent on quote requests. Null when no external rail is used (e.g. instant or intra-network transfers, or non-direct-destination transactions) or before a rail is resolved. railSelectionMode: anyOf: - $ref: '#/components/schemas/RailSelectionMode' @@ -17270,7 +17270,7 @@ components: - string - 'null' format: date-time - description: Expected settlement time at the beneficiary. Null when not yet known (e.g. instant rails, or before a rail is resolved). + description: Expected settlement time at the beneficiary. Null for instant rails (settlement is immediate) and before a rail with deferred settlement is resolved. settlementTimelineSeconds: type: - integer diff --git a/openapi.yaml b/openapi.yaml index 131c2e341..a0caaf16e 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -17259,7 +17259,7 @@ components: anyOf: - $ref: '#/components/schemas/PaymentRail' - type: 'null' - description: The payment rail used to settle this transaction (e.g. ACH, WIRE, NEFT, FASTER_PAYMENTS). Uses the same values as the PaymentRail sent on quote requests. Null until a rail is resolved. + description: The payment rail used to settle this transaction (e.g. ACH, WIRE, NEFT, FASTER_PAYMENTS). Uses the same values as the PaymentRail sent on quote requests. Null when no external rail is used (e.g. instant or intra-network transfers, or non-direct-destination transactions) or before a rail is resolved. railSelectionMode: anyOf: - $ref: '#/components/schemas/RailSelectionMode' @@ -17270,7 +17270,7 @@ components: - string - 'null' format: date-time - description: Expected settlement time at the beneficiary. Null when not yet known (e.g. instant rails, or before a rail is resolved). + description: Expected settlement time at the beneficiary. Null for instant rails (settlement is immediate) and before a rail with deferred settlement is resolved. settlementTimelineSeconds: type: - integer diff --git a/openapi/components/schemas/transactions/OutgoingTransaction.yaml b/openapi/components/schemas/transactions/OutgoingTransaction.yaml index 7bc6c0b33..b6ff7eb16 100644 --- a/openapi/components/schemas/transactions/OutgoingTransaction.yaml +++ b/openapi/components/schemas/transactions/OutgoingTransaction.yaml @@ -80,7 +80,9 @@ allOf: description: >- The payment rail used to settle this transaction (e.g. ACH, WIRE, NEFT, FASTER_PAYMENTS). Uses the same values as the PaymentRail sent - on quote requests. Null until a rail is resolved. + on quote requests. Null when no external rail is used (e.g. instant + or intra-network transfers, or non-direct-destination transactions) + or before a rail is resolved. railSelectionMode: anyOf: - $ref: ../common/RailSelectionMode.yaml @@ -95,8 +97,9 @@ allOf: - 'null' format: date-time description: >- - Expected settlement time at the beneficiary. Null when not yet known - (e.g. instant rails, or before a rail is resolved). + Expected settlement time at the beneficiary. Null for instant rails + (settlement is immediate) and before a rail with deferred settlement + is resolved. settlementTimelineSeconds: type: - integer