Add SWIFT pay-in API surface: holder name, readiness webhook, failure reason - #834
Open
mohamedwane wants to merge 7 commits into
Open
Add SWIFT pay-in API surface: holder name, readiness webhook, failure reason#834mohamedwane wants to merge 7 commits into
mohamedwane wants to merge 7 commits into
Conversation
… reason PaymentSwiftAccountInfo gains accountHolderName (required) and bankAddress, and reference becomes optional (SWIFT collections are attributed by the destination account, not a memo). New INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED webhook type announces funding-coordinate changes. IncomingTransactionFailureReason gains COLLECTION_FAILED. Hygiene: PaymentAccountType gains the SWIFT_ACCOUNT value its discriminator already maps; SwiftAccountInfoBase documents accountNumber/IBAN co-presence; incoming-payment webhook docs cover bank-rail pay-ins and their exemption from the approval gate. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DLYJSn6VRoZeLV15wcuZHy
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
|
The latest updates on your projects. Learn more about Vercel for GitHub. 2 Skipped Deployments
|
github-actions
Bot
added
the
breaking-change
Contributor
|
Contributor
✱ Stainless preview builds for gridThis PR will update the cli go kotlin openapi php python ruby typescript Edit this comment to update them. They will appear in their respective SDK's changelogs. ✅ grid-typescript studio · code · diff
✅ grid-openapi studio · code · diff
✅ grid-ruby studio · code · diff
✅ grid-go studio · code · diff
✅ grid-kotlin studio · code · diff
✅ grid-python studio · code · diff
✅ grid-php studio · code · diff
✅ grid-cli studio · code · diff
This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push. |
A collection deposit can fail on either the provider's leg or Grid's (compliance rejection on the incoming-balance leg, terminal flow failure), and the producer cannot always distinguish them. The reason describes the deposit outcome, not which side failed, and no longer claims the provider has already returned the funds. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DLYJSn6VRoZeLV15wcuZHy
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DLYJSn6VRoZeLV15wcuZHy
Upstream #823 added COMPLIANCE_REJECTED to IncomingTransactionFailureReason; this branch adds COLLECTION_FAILED. Both are additive enum members — the merged description explains each. Bundles regenerated via lint:openapi (0 errors). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DLYJSn6VRoZeLV15wcuZHy
mohamedwane
marked this pull request as ready for review
August 14, 2026 18:38
Contributor
Greptile SummaryThe PR adds the deferred SWIFT pay-in API surface and aligns webhook documentation with bank-rail semantics.
Confidence Score: 5/5The PR appears safe to merge. No blocking failure remains.
|
| Filename | Overview |
|---|---|
| openapi/components/schemas/common/PaymentSwiftAccountInfo.yaml | Adds required account-holder details, optional bank address, and makes SWIFT payment references optional. |
| openapi/components/schemas/common/SwiftAccountInfoBase.yaml | Documents the SWIFT identifier invariant without reintroducing the reverted request-contract constraint. |
| openapi/components/schemas/webhooks/WebhookType.yaml | Registers the funding-instructions-updated internal-account webhook discriminator. |
| openapi/webhooks/internal-account-status.yaml | Documents the funding-instruction readiness event and provides a complete SWIFT example. |
| openapi/webhooks/incoming-payment.yaml | Consistently distinguishes informational bank-rail events from approval-mechanism payment events. |
| openapi.yaml | Regenerated root bundle reflects the modular SWIFT and webhook contract changes. |
| mintlify/openapi.yaml | Regenerated documentation bundle reflects the source specification. |
Reviews (3): Last reviewed commit: "Revert "Enforce SwiftAccountInfoBase's a..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Greptile P2 on the ready round: the operation description said bank-rail PENDING events are informational, but the 200/202/403/422 response descriptions still read as unconditional approve/reject/RFI semantics. Each now carves out bank rails explicitly. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DLYJSn6VRoZeLV15wcuZHy
…cturally The description already promised that accountNumber or iban is always present; encode it as anyOf so validators and codegen see the invariant instead of trusting prose. Both identifiers remain legal together. The redocly ignore entries follow the existing precedent for anyOf branches that reference parent-level properties. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DLYJSn6VRoZeLV15wcuZHy
Contributor
Author
|
@greptileai review Generated by Claude Code |
…ant structurally" This reverts commit aab23ff.
Contributor
Author
|
@greptileai review Generated by Claude Code |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Reason
SWIFT pay-ins (epic AT-5861, milestone AT-6333) shipped their substrate in webdev M2/M3 without spec changes (decision D-M2-3): coordinates render from pre-existing fields, the platform has no push signal when wire coordinates become available, and a failed collect carries no failure reason. This is the deferred spec surface, landing spec-first so the webdev consumption PR can replay it via
update_schema.sh.Overview
PaymentSwiftAccountInfo: addsaccountHolderName(required — remitting banks match the beneficiary name, and every enabled collection account carries it) andbankAddress(optional).referencemoves out ofrequired: SWIFT collections are attributed by the destination account number/IBAN, not a memo.INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED: newWebhookTypevalue in the internal-account webhook family, fired when an account'sfundingPaymentInstructionschange (coordinates became servable, or were withdrawn). Payload is the full internal account, same as the existing family members. Path docs + a SWIFT example added.IncomingTransactionFailureReason: addsCOLLECTION_FAILED(inbound bank-rail collection failed after arrival — screening rejection or unresolved RFI; funds returned to sender). Additive for generated clients.PENDING) are informational — the synchronous approval mechanism and 5-second window do not apply, because the funds have already moved interbank.PaymentAccountTypegainsSWIFT_ACCOUNT(thefundingPaymentInstructionsdiscriminator already maps this value; the enum contradicted it);SwiftAccountInfoBasedocuments the accountNumber/IBAN co-presence invariant in prose (at least one present, both legal — live Tazapay collection accounts expose both identifiers, observed in the dev E2E 2026-08-14). A structuralanyOfenforcement was tried (aab23ff) and reverted (082bf7f): the base schema is shared withSwiftExternalAccountCreateInfo, a client-authored create-request body, so the constraint would tighten the existing request contract, and the Stainless preview builds regressed on it (grid-typescript/kotlin build failures, duplicate generated types in python/php). The invariant binds the producer and is enforced where the shape is constructed.openapi.yamlandmintlify/openapi.yamlare the regenerated bundles (npm run build:openapi).oasdiff report, mapped
All 41 flagged errors are the two deliberate changes above, fanned out across every path that transitively embeds
PaymentSwiftAccountInfo:response-property-became-optionalonreference— the intended relaxation. No producer has ever constructed this shape (nothing serves SWIFT payment instructions until the webdev consumption PR), so no client can observe a field disappearing that it previously received.new-required-request-propertyonaccountHolderName— these are webhook request bodies, i.e. payloads Grid sends to platforms. The "required" obligation binds the sender (us), not receivers; for platforms it is a new field that is always present. Same no-producer-yet argument applies.The
SWIFT_ACCOUNT/COLLECTION_FAILEDenum-value warnings are the standard additive-enum notes; this repo does not usex-extensible-enum.Test Plan
npm run lint:openapipasses: redocly lint + spectral, 0 errors; the new properties carry descriptions and examples peropenapi/README.md, and no new warnings are attributable to these lines.Rollout
Spec-only.
accountHolderNameis required on a shape nothing constructs today (webdev M2 renders SWIFT instructions from existing fields and starts constructing the new shape only in the consumption PR, where the field is guaranteed before render).referencerequired→optional is the one loosening: generated clients make the field nullable, which matches reality (it was never meaningful for SWIFT attribution). All other changes are additive enum values and docs.