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,46 @@
+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:
+  - type
+  - currency
+  - sweepRule
+properties:
+  customerId:
+    type: string
+    description: >-
+      The customer the account is created for. Omit it to create a
+      platform-owned account. The account holder must already have a verified
+      account in the same currency, which is where funds land when a sweep
+      cannot be completed. Platform-owned rule-based accounts are not available
+      yet, so omitting this is currently rejected.
+    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 account holder,
+  with a routing rule attached, so incoming payments can be attributed to a
+  specific payer and swept 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 swept.
+  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 swept. 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 swept.
+  purposeOfPayment:
+    allOf:
+      - $ref: ../quotes/PurposeOfPayment.yaml
+    description: The purpose of payment applied to each sweep.
+    example: SELF
+  description:
+    type: string
+    description: >-
+      Free-form description recorded on each sweep. Not delivered to the
+      recipient.
+    example: Rent sweep
+  remittanceInformation:
+    type: string
+    description: >-
+      Free-form information that travels with each sweep to the recipient.
+    example: Unit 4B March
+  platformFeeOverride:
+    allOf:
+      - $ref: ../quotes/PlatformFeeOverride.yaml
+    description: >-
+      Fee terms applied to every sweep 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 swept.
+required:
+  - accountId
+properties:
+  accountId:
+    type: string
+    description: The account that receives the swept funds.
+    example: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123
+  paymentRail:
+    allOf:
+      - $ref: ../common/PaymentRail.yaml
+    description: >-
+      The rail each sweep is sent over. Null when a rail is selected
+      automatically per sweep, 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 sweeps its incoming payments to.
+additionalProperties: false
+required:
+  - accountId
+properties:
+  accountId:
+    type: string
+    description: >-
+      Reference to the account that receives the swept funds. May be an
+      external account or another internal account, but never a `RULE_BASED`
+      internal account — that account's own rule would sweep the funds on
+      again. The destination may be denominated in a different currency, in
+      which case the sweep is converted at the prevailing rate.
+    example: ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965
+  paymentRail:
+    description: >-
+      The payment rail to use when sweeping to an external account. Must be
+      one of the rails supported by the destination account. If omitted, a rail
+      is selected automatically for each sweep. 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 swept 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 swept.
+  purposeOfPayment:
+    allOf:
+      - $ref: ../quotes/PurposeOfPayment.yaml
+    description: >-
+      The purpose of payment applied to each sweep. Required by some
+      destination geographies.
+    example: SELF
+  description:
+    type: string
+    maxLength: 255
+    description: >-
+      Free-form description recorded on each sweep. Not delivered to the
+      recipient; use `remittanceInformation` for that.
+    example: Rent sweep
+  remittanceInformation:
+    type: string
+    maxLength: 1024
+    description: >-
+      Free-form information that travels with each sweep 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/transactions/IncomingTransaction.yaml

@@ -29,3 +29,19 @@ allOf:
       failureReason:
         $ref: ./IncomingTransactionFailureReason.yaml
         description: If the transaction failed, this field provides the reason for failure.
+      sweepFailureReason:
+        allOf:
+          - $ref: ./SweepFailureReason.yaml
+        description: >-
+          Set when this payment settled into a rule-based account but was not
+          swept to the destination of the account's rule. The deposit itself
+          succeeded, so the transaction still completes; this says why the
+          destination was not paid. Omitted for any other account.
+      sweepCanonicalAccountId:
+        type: string
+        description: >-
+          The account holder's own account in the same currency the funds were
+          moved to when a sweep could not be completed — the customer's, or the
+          platform's for a platform-owned rule-based account. A rule-based
+          account never holds a balance. Present whenever
+          `sweepFailureReason` is.

openapi/components/schemas/transactions/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 swept 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 sweep. |
+  | `QUOTE_FAILED` | Grid could not price the sweep to the destination. |
+  | `EXECUTION_FAILED` | The sweep was priced but the resulting payment did not go through. |

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