feat: add rule-based internal accounts and the sweep failure webhook - #835
feat: add rule-based internal accounts and the sweep failure webhook#835ls-bolt[bot] wants to merge 2 commits into
Conversation
|
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
|
a0a2b64 to
3ada236
Compare
github-actions
Bot
added
breaking-change
This stack of pull requests is managed by Graphite. Learn more about stacking. |
✱ 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-kotlin studio · code · diff
✅ grid-php studio · code · diff
✅ grid-openapi studio · code · diff
✅ grid-ruby studio · code · diff
✅ grid-go studio · code · diff
✅ grid-python 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. |
The create verb belongs on the bare collection: the body carries an optional customerId, so a /customers/ path would describe a request that may name no customer. The customer and platform paths keep their GETs -- a listing has to pick a population, a create does not. The response also gains label and sweepRule, with the SweepRule and SweepRuleDestination schemas they need. Without them a rule-based account could not express its own rule in any response. Both are output-only, and the band is derived from the corridor at read time rather than stored, so what a platform reads is what the forward will enforce. There is deliberately no sweepRule.id -- the rule has no lifecycle apart from its account. Edited under openapi/ and rebuilt: the root openapi.yaml and the mintlify copy are bundler output, so editing those alone would have been reverted by the next build.
82e6e81 to
0c1fe9f
Compare
2 participants
Summary
Adds the API surface for rule-based internal accounts — an additional account number for an existing customer with a routing rule attached, so incoming payments can be attributed to a specific payer and forwarded automatically.
Every schema change the feature needs is bundled here, in one reviewable PR, rather than arriving in pieces.
What's added
RULE_BASEDonInternalAccountType, plus the same value as atypefilter onGET /customers/internal-accounts.POST /internal-accounts— the create verb lives on the bare collection, not under/customers/: the body carries an optionalcustomerId, so a customer-scoped path would describe a request that may name no customer. The listing paths keep theirGETs, since a list has to pick a population and a create does not. The body takestypeandcurrency, an optionallabel, and asweepRuledescribing where funds are forwarded: adestination(account id plus an optional payment rail) and optionalpurposeOfPayment,description, andremittanceInformation.Idempotency-Keyis required, matching the other endpoints that mint something irreversible.Only
RULE_BASEDis creatable. The other account types are provisioned automatically when a customer is created or approved, so the endpoint rejects them with a specific message rather than a generic error.SWEEP.FAILEDwebhook — fired whenever a settled payment does not reach the rule's destination, including when the balance is below the corridor minimum and is returned to the payer instead. The payload carries both transaction ids, areason, and anoutcome, so an integrator can distinguish "this payment failed" from "and therefore this amount went somewhere else."Delivery is at-least-once and a redelivery carries a new event id, so the payload documents deduplicating on
incomingTransactionId.labelandsweepRuleon theInternalAccountresponse. A rule-based account can now show what it is: the label recorded at creation, and the rule itself — destination, the derivedminimumAmount/maximumAmountband, purpose, remittance and any fee override. Both are output-only, and the band is derived from the corridor at read time rather than stored, so what a platform reads is what the forward will actually enforce. There is deliberately nosweepRule.id: the rule has no lifecycle apart from its account, and publishing an id would invite a resource that does not exist.Two decisions worth a second opinion
DESTINATION_UNAVAILABLEis not included. It appeared in the original design, but nothing in the implementation can produce it — rail validation raises a single condition thatNO_ELIGIBLE_RAILalready covers. Publishing a value that never arrives costs a permanently un-removable enum member (adding one is non-breaking; removing one is not) and generates a dead case in every SDK. Adding it later, if a rail ever produces it, is free. Happy to reserve it if you'd rather.ABOVE_MAXIMUMis included and wasn't in the original design. A balance over the corridor ceiling would otherwise be submitted whole, rejected, and stranded; it now takes the same return path as any other non-success outcome, and this is how the platform is told.What's deliberately not here
GET /customers/internal-accounts/{id}andDELETEwere in the original design but are not implemented. Speccing them now would generate SDK methods that 405, so they're left for whenever the endpoints land.Verification
make lintpasses with 0 errors, and zero warnings or informational findings on any schema added here. All 1,971$refs resolve, none dangling.Everything is edited under
openapi/and the bundles regenerated withmake build—openapi.yamlandmintlify/openapi.yamlare output, so a source-only change would be reverted by the next build and a bundle-only change would be reverted just as silently. The route move adds a source path file (openapi/paths/internal_accounts.yaml) split out of the customers path, and the response fields add two source schemas (SweepRule.yaml,SweepRuleDestination.yaml).