feat: add granular counterparty payout failure reasons

mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx

@@ -237,7 +237,7 @@ Outgoing payment webhooks use the format `OUTGOING_PAYMENT.<STATUS>`. The webhoo
   "data": {
     "id": "Transaction:...",
     "status": "FAILED",
-    "failureReason": "INVALID_BANK_ACCOUNT"
+    "failureReason": "ACCOUNT_INVALID"
   }
 }
 ```
@@ -394,10 +394,19 @@ Use for reconciliation and reporting.
 |----------------|-------------|----------|
 | `QUOTE_EXPIRED` | Quote expired before execution | Create new quote |
 | `QUOTE_EXECUTION_FAILED` | Error executing the quote | Create new quote |
-| `INSUFFICIENT_BALANCE` | Source account lacks funds | Fund account, retry |
-| `LIGHTNING_PAYMENT_FAILED` | Lightning network payment could not be routed | Retry or use alternative rail |
+| `EXECUTION_FAILED_POST_DEBIT` | Execution failed after debit; funds are refunded automatically | Retry with a new quote |
+| `SETTLEMENT_FAILED` | The settlement leg failed | Retry or use alternative rail |
 | `FUNDING_AMOUNT_MISMATCH` | Funding amount doesn't match expected amount | Verify amounts and retry |
-| `COUNTERPARTY_POST_TX_FAILED` | Post-transaction processing at counterparty failed | Contact support |
+| `TIMEOUT` | Transaction didn't complete within its processing window | Retry with a new quote |
+| `MANUAL_REFUND` | Transaction was refunded manually | Contact support |
+| `LSP_OPERATIONAL_FAILURE` | Lightspark-internal operational issue | Contact Lightspark |
+| `PAYOUT_RETURNED` | Receiving bank returned or reversed the payout | Verify details and retry |
+| `LIMIT_EXCEEDED` | Payout exceeds a partner limit | Reduce amount or contact support |
+| `ACCOUNT_CANNOT_RECEIVE` | Recipient account can't accept the payment | Use a different account |
+| `ACCOUNT_INVALID` | Recipient account details are wrong or not found | Correct recipient details |
+| `COMPLIANCE_REJECTED` | Payout partner rejected on compliance grounds | Contact support |
+
+The `failureReason` field on a transaction may return additional values, including deprecated reasons (`LIGHTNING_PAYMENT_FAILED`, `COUNTERPARTY_POST_TX_FAILED`) retained for historical transactions.
 
 When a transaction fails, a refund is initiated automatically. Track the refund via the `refund` object on the transaction and `OUTGOING_PAYMENT.REFUND_*` webhook events. See [Refund Object](#refund-object) above.
 

mintlify/snippets/error-handling.mdx

@@ -144,7 +144,17 @@ When a transaction fails, the `failureReason` field provides specific details:
 
 - `QUOTE_EXPIRED` - Quote expired before execution
 - `QUOTE_EXECUTION_FAILED` - Error executing the quote
+- `EXECUTION_FAILED_POST_DEBIT` - Execution failed after debit; funds are refunded automatically
+- `SETTLEMENT_FAILED` - The settlement leg failed
 - `FUNDING_AMOUNT_MISMATCH` - Funding amount doesn't match expected amount
+- `TIMEOUT` - Transaction didn't complete within its processing window
+- `MANUAL_REFUND` - Transaction was refunded manually
+- `LSP_OPERATIONAL_FAILURE` - Lightspark-internal operational issue; contact Lightspark
+- `PAYOUT_RETURNED` - Receiving bank returned or reversed the payout
+- `LIMIT_EXCEEDED` - Payout exceeds a partner limit
+- `ACCOUNT_CANNOT_RECEIVE` - Recipient account can't accept the payment
+- `ACCOUNT_INVALID` - Recipient account details are wrong or not found
+- `COMPLIANCE_REJECTED` - Payout partner rejected on compliance grounds
 
 ### Incoming payment failures
 

openapi/components/schemas/transactions/OutgoingTransactionFailureReason.yaml

@@ -2,10 +2,44 @@ type: string
 enum:
   - QUOTE_EXPIRED
   - QUOTE_EXECUTION_FAILED
-  - LIGHTNING_PAYMENT_FAILED
+  - EXECUTION_FAILED_POST_DEBIT
+  - SETTLEMENT_FAILED
   - FUNDING_AMOUNT_MISMATCH
+  - TIMEOUT
+  - MANUAL_REFUND
+  - LSP_OPERATIONAL_FAILURE
+  - PAYOUT_RETURNED
+  - LIMIT_EXCEEDED
+  - ACCOUNT_CANNOT_RECEIVE
+  - ACCOUNT_INVALID
+  - COMPLIANCE_REJECTED
+  - LIGHTNING_PAYMENT_FAILED
   - COUNTERPARTY_POST_TX_FAILED
-description: >-
+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
   state, this field is omitted.
+
+  When a payout partner rejects or fails a payment, one of the granular payout
+  reasons (`PAYOUT_RETURNED`, `LIMIT_EXCEEDED`, `ACCOUNT_CANNOT_RECEIVE`,
+  `ACCOUNT_INVALID`, `COMPLIANCE_REJECTED`) is returned when available.
+  `COUNTERPARTY_POST_TX_FAILED` is a coarse fallback used only when no granular
+  reason is available.
+
+  | Reason | Description |
+  |--------|-------------|
+  | `QUOTE_EXPIRED` | The quote was not executed before its expiry window |
+  | `QUOTE_EXECUTION_FAILED` | The quote could not be executed |
+  | `EXECUTION_FAILED_POST_DEBIT` | Execution failed after funds were debited. The amount is refunded automatically |
+  | `SETTLEMENT_FAILED` | The settlement leg failed |
+  | `FUNDING_AMOUNT_MISMATCH` | The funds received did not match the expected amount |
+  | `TIMEOUT` | The transaction did not complete within its processing window |
+  | `MANUAL_REFUND` | The transaction was refunded manually |
+  | `LSP_OPERATIONAL_FAILURE` | A Lightspark-internal operational issue (for example, insufficient operational balance). Not a client error — contact Lightspark to resolve |
+  | `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_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 `SETTLEMENT_FAILED`. The Lightning settlement leg failed |
+  | `COUNTERPARTY_POST_TX_FAILED` | Deprecated — coarse fallback retained for historical transactions when no granular payout reason is available |