feat: add rule-based internal accounts and the sweep failure webhook

openapi/components/schemas/customers/InternalAccount.yaml

@@ -32,6 +32,19 @@ properties:
     description: Payment instructions for funding the account
     items:
       $ref: ../common/PaymentInstructions.yaml
+  label:
+    type: string
+    maxLength: 255
+    description: >-
+      The platform-supplied label recorded when the account was created. Null
+      for accounts that carry none.
+    example: invoice-4417
+  sweepRule:
+    allOf:
+      - $ref: SweepRule.yaml
+    description: >-
+      The routing rule attached to this account. Null for accounts that carry
+      no rule, which is every account other than a `RULE_BASED` one.
   privateEnabled:
     type: boolean
     description: >-

openapi/components/schemas/customers/InternalAccountCreateRequest.yaml

@@ -0,0 +1,44 @@
+title: Internal Account Create Request
+type: object
+description: >-
+  Request body for `POST /internal-accounts`. Only `RULE_BASED`
+  accounts can be created directly, and they always carry a `sweepRule`.
+additionalProperties: false
+required:
+  - customerId
+  - type
+  - currency
+properties:
+  customerId:
+    type: string
+    description: >-
+      The customer the account is created for. The customer must already have a
+      verified account in the same currency, which is where funds land when a
+      forward cannot be completed.
+    example: Customer:019542f5-b3e7-1d02-0000-000000000001
+  type:
+    allOf:
+      - $ref: ./InternalAccountType.yaml
+    description: >-
+      Must be `RULE_BASED`. `INTERNAL_FIAT`, `INTERNAL_CRYPTO`, and
+      `EMBEDDED_WALLET` accounts are provisioned automatically when a customer
+      is created or approved, so they cannot be created through this endpoint.
+    example: RULE_BASED
+  currency:
+    type: string
+    description: >-
+      Currency code the account is denominated in (ISO 4217). Rule-based
+      accounts are currently available in `USD` only.
+    example: USD
+  label:
+    type: string
+    maxLength: 255
+    description: >-
+      Your own name for the account, echoed back on reads. Useful for
+      identifying which payer the account was issued for.
+    example: invoice-4417
+  sweepRule:
+    allOf:
+      - $ref: ./SweepRuleRequest.yaml
+    description: >-
+      The routing rule for the account. Required when `type` is `RULE_BASED`.

openapi/components/schemas/customers/InternalAccountType.yaml

@@ -4,6 +4,7 @@ enum:
   - INTERNAL_FIAT
   - INTERNAL_CRYPTO
   - EMBEDDED_WALLET
+  - RULE_BASED
 description: >-
   Classification of an internal account.
 
@@ -17,3 +18,8 @@ description: >-
   - `EMBEDDED_WALLET`: A self-custodial Embedded Wallet provisioned for the
   customer. Outbound transfers require a session signature produced by the
   customer's device — see the Embedded Wallets guide.
+
+  - `RULE_BASED`: 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. Created with
+  `POST /internal-accounts`.

openapi/components/schemas/customers/SweepRule.yaml

@@ -0,0 +1,52 @@
+title: Sweep Rule
+type: object
+description: >-
+  The routing rule attached to a rule-based account. Returned on the account
+  rather than as a resource of its own, because the rule has no lifecycle apart
+  from the account.
+required:
+  - destination
+properties:
+  destination:
+    allOf:
+      - $ref: SweepRuleDestination.yaml
+    description: Where funds that settle into this account are forwarded.
+  minimumAmount:
+    allOf:
+      - $ref: ../common/CurrencyAmount.yaml
+    description: >-
+      The smallest balance the corridor to the destination can carry,
+      denominated in this account's own currency. A settled balance below it is
+      not forwarded. Zero means no floor applies, which is the case for a
+      same-currency internal destination: that movement is a book transfer with
+      no rail, fee, or conversion to justify one. This is current configuration
+      rather than a moving estimate — it changes only when the platform's or
+      Grid's configuration changes, so there is nothing to re-poll.
+  maximumAmount:
+    allOf:
+      - $ref: ../common/CurrencyAmount.yaml
+    description: >-
+      The largest balance the corridor to the destination can carry. Null means
+      no ceiling applies. A settled balance above it is not forwarded.
+  purposeOfPayment:
+    allOf:
+      - $ref: ../quotes/PurposeOfPayment.yaml
+    description: The purpose of payment applied to each forward.
+    example: SELF
+  description:
+    type: string
+    description: >-
+      Free-form description recorded on each forward. Not delivered to the
+      recipient.
+    example: Rent forwarding
+  remittanceInformation:
+    type: string
+    description: >-
+      Free-form information that travels with each forward to the recipient.
+    example: Unit 4B March
+  platformFeeOverride:
+    allOf:
+      - $ref: ../quotes/PlatformFeeOverride.yaml
+    description: >-
+      Fee terms applied to every forward this rule drives. Null when the
+      platform's configured fees apply.

openapi/components/schemas/customers/SweepRuleDestination.yaml

@@ -0,0 +1,18 @@
+title: Sweep Rule Destination
+type: object
+description: >-
+  Where a rule-based account's credits are forwarded.
+required:
+  - accountId
+properties:
+  accountId:
+    type: string
+    description: The account that receives the forwarded funds.
+    example: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
+  paymentRail:
+    allOf:
+      - $ref: ../common/PaymentRail.yaml
+    description: >-
+      The rail each forward is sent over. Null when a rail is selected
+      automatically per forward, in which case none is resolved ahead of time.
+    example: ACH

openapi/components/schemas/customers/SweepRuleDestinationRequest.yaml

@@ -0,0 +1,25 @@
+title: Sweep Rule Destination Request
+type: object
+description: >-
+  The account a rule-based account forwards its incoming payments to.
+additionalProperties: false
+required:
+  - accountId
+properties:
+  accountId:
+    type: string
+    description: >-
+      Reference to the account that receives the forwarded funds. May be an
+      external account or another internal account, but never a `RULE_BASED`
+      internal account — that account's own rule would forward the funds on
+      again. The destination may be denominated in a different currency, in
+      which case the forward is converted at the prevailing rate.
+    example: ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
+  paymentRail:
+    description: >-
+      The payment rail to use when forwarding to an external account. Must be
+      one of the rails supported by the destination account. If omitted, a rail
+      is selected automatically for each forward. Not accepted when the
+      destination is an internal account, which settles without a payment rail.
+    allOf:
+      - $ref: ../common/PaymentRail.yaml

openapi/components/schemas/customers/SweepRuleRequest.yaml

@@ -0,0 +1,40 @@
+title: Sweep Rule Request
+type: object
+description: >-
+  The routing rule attached to a rule-based account. Every payment that settles
+  into the account is forwarded to the rule's destination, carrying the payment
+  metadata configured here.
+additionalProperties: false
+required:
+  - destination
+properties:
+  destination:
+    allOf:
+      - $ref: ./SweepRuleDestinationRequest.yaml
+    description: Where funds that settle into this account are forwarded.
+  purposeOfPayment:
+    allOf:
+      - $ref: ../quotes/PurposeOfPayment.yaml
+    description: >-
+      The purpose of payment applied to each forward. Required by some
+      destination geographies.
+    example: SELF
+  description:
+    type: string
+    maxLength: 255
+    description: >-
+      Free-form description recorded on each forward. Not delivered to the
+      recipient; use `remittanceInformation` for that.
+    example: Rent forwarding
+  remittanceInformation:
+    type: string
+    maxLength: 1024
+    description: >-
+      Free-form information that travels with each forward to the recipient.
+      The field this populates depends on the payment rail: for ACH it
+      populates the Addenda record, for FedNow and RTP it populates the
+      remittanceInformation field, and for wires it populates the OBI
+      (Originator to Beneficiary Information) / beneficiary information. Only
+      printable ASCII characters are accepted, because the underlying rails
+      carry nothing else.
+    example: Unit 4B March

openapi/components/schemas/webhooks/SweepFailure.yaml

@@ -0,0 +1,61 @@
+title: Sweep Failure
+type: object
+description: >-
+  A payment that settled into a rule-based account but did not reach the
+  destination of the account's rule.
+required:
+  - sourceAccountId
+  - destinationAccountId
+  - amount
+  - incomingTransactionId
+  - reason
+  - outcome
+properties:
+  sourceAccountId:
+    type: string
+    description: The rule-based internal account the payment settled into.
+    example: InternalAccount:019542f5-b3e7-1d02-0000-000000000005
+  destinationAccountId:
+    type: string
+    description: >-
+      The destination configured on the account's rule, which the funds did not
+      reach.
+    example: ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
+  amount:
+    allOf:
+      - $ref: ../common/CurrencyAmount.yaml
+    description: The amount that could not be forwarded.
+  incomingTransactionId:
+    type: string
+    description: >-
+      The transaction that brought the funds into the rule-based account.
+      Delivery of this event is at-least-once, so deduplicate on this value.
+    example: Transaction:019542f5-b3e7-1d02-0000-000000000010
+  sendTransactionId:
+    type:
+      - string
+      - 'null'
+    description: >-
+      The outgoing transaction created for the forward, when the forward got
+      far enough to create one. Null when the forward was never attempted. Use
+      it to correlate this event with the `OUTGOING_PAYMENT.FAILED` event for
+      the same forward rather than counting the failure twice.
+    example: Transaction:019542f5-b3e7-1d02-0000-000000000011
+  reason:
+    allOf:
+      - $ref: ./SweepFailureReason.yaml
+    description: Why the forward could not be completed.
+    example: BELOW_MINIMUM
+  outcome:
+    allOf:
+      - $ref: ./SweepFailureOutcome.yaml
+    description: Where the funds ended up.
+    example: MOVED_TO_CANONICAL_ACCOUNT
+  canonicalAccountId:
+    type:
+      - string
+      - 'null'
+    description: >-
+      The customer's account in the same currency that the funds were moved to.
+      Null when `outcome` is `HELD_IN_RULE_BASED_ACCOUNT`.
+    example: InternalAccount:019542f5-b3e7-1d02-0000-000000000006

openapi/components/schemas/webhooks/SweepFailureOutcome.yaml

@@ -0,0 +1,11 @@
+type: string
+enum:
+  - MOVED_TO_CANONICAL_ACCOUNT
+  - HELD_IN_RULE_BASED_ACCOUNT
+description: |
+  Where the funds ended up after the forward failed.
+
+  | Outcome | Description |
+  |---------|-------------|
+  | `MOVED_TO_CANONICAL_ACCOUNT` | The funds were moved to the customer's account in the same currency, identified by `canonicalAccountId`. |
+  | `HELD_IN_RULE_BASED_ACCOUNT` | The funds remain in the rule-based account. Grid retries the move when the next payment settles into the account. |

openapi/components/schemas/webhooks/SweepFailureReason.yaml

@@ -0,0 +1,17 @@
+type: string
+enum:
+  - BELOW_MINIMUM
+  - ABOVE_MAXIMUM
+  - NO_ELIGIBLE_RAIL
+  - QUOTE_FAILED
+  - EXECUTION_FAILED
+description: |
+  Why the payment could not be forwarded to the rule's destination.
+
+  | Reason | Description |
+  |--------|-------------|
+  | `BELOW_MINIMUM` | The amount is below the smallest amount the corridor to the destination can carry. |
+  | `ABOVE_MAXIMUM` | The amount is above the largest amount the corridor to the destination can carry. |
+  | `NO_ELIGIBLE_RAIL` | No payment rail available to the destination could carry the forward. |
+  | `QUOTE_FAILED` | Grid could not price the forward to the destination. |
+  | `EXECUTION_FAILED` | The forward was priced but the resulting payment did not go through. |

openapi/components/schemas/webhooks/SweepWebhook.yaml

@@ -0,0 +1,12 @@
+allOf:
+  - $ref: ./BaseWebhook.yaml
+  - type: object
+    required:
+      - data
+    properties:
+      data:
+        $ref: ./SweepFailure.yaml
+      type:
+        type: string
+        enum:
+          - SWEEP.FAILED

openapi/components/schemas/webhooks/WebhookType.yaml

@@ -40,6 +40,7 @@ enum:
   - CARD_TRANSACTION.SETTLED
   - CARD_TRANSACTION.REFUNDED
   - CARD_TRANSACTION.EXCEPTION
+  - SWEEP.FAILED
   - TEST
 description: >-
   Type of webhook event in OBJECT.EVENT dot-notation. The part before the dot

openapi/paths/customers/customers_internal_accounts.yaml

@@ -28,8 +28,9 @@ get:
       in: query
       description: >-
         Filter by internal account type. Use `EMBEDDED_WALLET` to find the
-        self-custodial wallet provisioned for a customer, or `INTERNAL_FIAT` /
-        `INTERNAL_CRYPTO` for the platform-managed holding accounts.
+        self-custodial wallet provisioned for a customer, `INTERNAL_FIAT` /
+        `INTERNAL_CRYPTO` for the platform-managed holding accounts, or
+        `RULE_BASED` for the additional account numbers issued for a customer.
       required: false
       schema:
         $ref: ../../components/schemas/customers/InternalAccountType.yaml