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,48 @@
+title: Internal Account Create Request
+type: object
+description: >-
+  Request body for `POST /internal-accounts`. Only `RULE_BASED` accounts can be
+  created today, and they are rejected without a `sweepRule` — the type and its
+  rule are created together or not at all.
+additionalProperties: false
+required:
+  - type
+  - currency
+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`,
+      which is the only type this endpoint creates today: a rule-based account
+      with no rule has no meaning, so the two are written together.

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: >-
+      **In this rule-based account's currency, not the destination's.** The
+      smallest balance the corridor to the destination can carry; a settled
+      balance below it is not swept. Zero means no floor, which is the case for
+      a same-currency internal destination — a book transfer with no rail, fee
+      or conversion to justify one. Configuration rather than a moving
+      estimate, so there is nothing to re-poll.
+  maximumAmount:
+    allOf:
+      - $ref: ../common/CurrencyAmount.yaml
+    description: >-
+      **In this rule-based account's currency, not the destination's.** The
+      largest balance the corridor to the destination can carry; a settled
+      balance above it is not swept. Null means no ceiling.
+  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

@@ -4,7 +4,6 @@ allOf:
   - type: object
     required:
       - type
-      - receivedAmount
     properties:
       type:
         type: string
@@ -14,7 +13,10 @@ allOf:
         $ref: ./TransactionSourceOneOf.yaml
       receivedAmount:
         $ref: ../common/CurrencyAmount.yaml
-        description: Amount received in the recipient's currency
+        description: >-
+          Amount received in the recipient's currency. This is only absent for
+          rule-based account sweeps if the sweep couldn't be quoted. It's always
+          present otherwise.
       fees:
         type: integer
         format: int64

openapi/components/schemas/transactions/IncomingTransactionFailureReason.yaml

@@ -10,6 +10,8 @@ enum:
   - QUOTE_EXECUTION_FAILED
   - COMPLIANCE_REJECTED
   - COLLECTION_FAILED
+  - SWEEP_AMOUNT_OUT_OF_RANGE
+  - SWEEP_QUOTE_FAILED
 description: >-
   Reason for failure of an incoming transaction. This is used to provide more
   context on why a transaction failed. If the transaction is not in a failed
@@ -20,3 +22,13 @@ description: >-
   information, on either the collection provider's side or Grid's. Failed
   collections are returned to the sender per the collection provider's
   process.
+
+  A payment that settled into a rule-based account but could not be swept to the
+  destination of the account's rule fails with one of the `SWEEP_*` reasons. A
+  rule-based account never holds a balance, so the funds are moved to the account
+  holder's own account in the same currency. SWEEP_AMOUNT_OUT_OF_RANGE means the
+  amount was outside the band the corridor to the destination can carry — the
+  rule's minimumAmount and maximumAmount give the current band — and
+  SWEEP_QUOTE_FAILED that Grid could not price it. A sweep that was priced and
+  then failed on the way to settlement reports QUOTE_EXECUTION_FAILED, the same
+  as any other payment.

openapi/components/schemas/transactions/OutgoingTransactionFailureReason.yaml

@@ -12,6 +12,8 @@ enum:
   - COMPLIANCE_REJECTED
   - LIGHTNING_PAYMENT_FAILED
   - COUNTERPARTY_POST_TX_FAILED
+  - SWEEP_AMOUNT_OUT_OF_RANGE
+  - SWEEP_QUOTE_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
@@ -38,8 +40,15 @@ description: |
   | `SCA_NOT_COMPLETED` | The customer did not complete the Strong Customer Authentication challenge before it expired |
   | `PAYOUT_RETURNED` | The receiving bank accepted the payout and then returned or reversed it |
   | `LIMIT_EXCEEDED` | The payout exceeds a recipient-, account-, or corridor-level limit at the partner |
-  | `ACCOUNT_CANNOT_RECEIVE` | The account exists but can't accept this payment — dormant, frozen, restricted, or the currency isn't supported for that account |
+  | `ACCOUNT_CANNOT_RECEIVE` | The account exists but can't accept this payment — dormant, frozen, restricted, or the currency or payment rail isn't supported for that account. A sweep whose rule names a rail the destination cannot accept reports this |
   | `ACCOUNT_INVALID` | The recipient account couldn't be found or the details are wrong — bad IBAN/account number, beneficiary not found, or account closed |
   | `COMPLIANCE_REJECTED` | The payout partner rejected the recipient on compliance grounds — sanctions, watchlist, or KYC/AML screening |
   | `LIGHTNING_PAYMENT_FAILED` | Deprecated — superseded by `QUOTE_EXECUTION_FAILED`. The Lightning settlement leg failed |
   | `COUNTERPARTY_POST_TX_FAILED` | Deprecated — coarse fallback retained for historical transactions when no granular payout reason is available |
+  | `SWEEP_AMOUNT_OUT_OF_RANGE` | The amount was outside the range the corridor to the rule's destination can carry — below its minimum or above its maximum. The rule's `minimumAmount` and `maximumAmount` give the current band |
+  | `SWEEP_QUOTE_FAILED` | Grid could not price the sweep to the rule's destination. A sweep that was priced and then failed on the way to settlement reports `QUOTE_EXECUTION_FAILED`, the same as any other payout |
+
+  The `SWEEP_*` reasons apply to a payment that settled into a rule-based
+  account and could not be swept onward. A rule-based account never holds a
+  balance, so the funds are moved to the account holder's own account in the
+  same currency.

openapi/paths/agents/agents_me_internal-accounts.yaml

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

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