diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 7105216fe..9da320371 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -17064,10 +17064,47 @@ components: 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: 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. + 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 | OutgoingTransaction: title: Outgoing Transaction allOf: diff --git a/mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx b/mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx index c9ed40fa3..7b53be784 100644 --- a/mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx +++ b/mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx @@ -237,7 +237,7 @@ Outgoing payment webhooks use the format `OUTGOING_PAYMENT.`. 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. diff --git a/mintlify/snippets/error-handling.mdx b/mintlify/snippets/error-handling.mdx index c388b5bb5..3f155eb24 100644 --- a/mintlify/snippets/error-handling.mdx +++ b/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 diff --git a/openapi.yaml b/openapi.yaml index 7105216fe..9da320371 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -17064,10 +17064,47 @@ components: 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: 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. + 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 | OutgoingTransaction: title: Outgoing Transaction allOf: diff --git a/openapi/components/schemas/transactions/OutgoingTransactionFailureReason.yaml b/openapi/components/schemas/transactions/OutgoingTransactionFailureReason.yaml index 8af526f7a..41d43e1e3 100644 --- a/openapi/components/schemas/transactions/OutgoingTransactionFailureReason.yaml +++ b/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 |