diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index a3a220f5e..cc0e17ecf 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -21110,18 +21110,45 @@ components: enum: - QUOTE_EXPIRED - QUOTE_EXECUTION_FAILED - - LIGHTNING_PAYMENT_FAILED - FUNDING_AMOUNT_MISMATCH - - COUNTERPARTY_POST_TX_FAILED - SCA_NOT_COMPLETED - - EXECUTION_FAILED_POST_DEBIT - - SETTLEMENT_FAILED - - TIMEOUT - - MANUAL_REFUND - 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. + - 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. + + 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. + + `SCA_NOT_COMPLETED` means the customer did not satisfy the Strong Customer + Authentication challenge before it expired, so the transaction was never + authorized and no funds were moved. Only occurs for customers in a region + where SCA is required (e.g. the EU). Create a new quote to try again, and have + the customer authorize it while the challenge is live. - `SCA_NOT_COMPLETED` means the customer did not satisfy the Strong Customer Authentication challenge before it expired, so the transaction was never authorized and no funds were moved. Only occurs for customers in a region where SCA is required (e.g. the EU). Create a new quote to try again, and have the customer authorize it while the challenge is live. + | Reason | Description | + |--------|-------------| + | `QUOTE_EXPIRED` | The quote was not executed before its expiry window | + | `QUOTE_EXECUTION_FAILED` | The quote could not be executed. Covers any internal failure on the way to settlement, whether or not funds were debited — a debited amount is refunded automatically | + | `FUNDING_AMOUNT_MISMATCH` | The funds received did not match the expected amount | + | `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_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 | RailSelectionMode: type: string enum: diff --git a/mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx b/mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx index e338e7a46..8bc4b93e8 100644 --- a/mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx +++ b/mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx @@ -252,7 +252,7 @@ Outgoing payment webhooks use the format `OUTGOING_PAYMENT.`. The webhoo "data": { "id": "Transaction:...", "status": "FAILED", - "failureReason": "INVALID_BANK_ACCOUNT" + "failureReason": "ACCOUNT_INVALID" } } ``` @@ -436,11 +436,15 @@ Use for reconciliation and reporting. | Failure Reason | Description | Recovery | |----------------|-------------|----------| | `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 | +| `QUOTE_EXECUTION_FAILED` | Error executing the quote; a debited amount is refunded automatically | Create new quote | | `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 | +| `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 230624118..6d3b16202 100644 --- a/mintlify/snippets/error-handling.mdx +++ b/mintlify/snippets/error-handling.mdx @@ -144,8 +144,13 @@ When a transaction fails, the `failureReason` field provides specific details: **Common outgoing failure reasons:** - `QUOTE_EXPIRED` - Quote expired before execution -- `QUOTE_EXECUTION_FAILED` - Error executing the quote +- `QUOTE_EXECUTION_FAILED` - Error executing the quote; a debited amount is refunded automatically - `FUNDING_AMOUNT_MISMATCH` - Funding amount doesn't match expected amount +- `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 a3a220f5e..cc0e17ecf 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -21110,18 +21110,45 @@ components: enum: - QUOTE_EXPIRED - QUOTE_EXECUTION_FAILED - - LIGHTNING_PAYMENT_FAILED - FUNDING_AMOUNT_MISMATCH - - COUNTERPARTY_POST_TX_FAILED - SCA_NOT_COMPLETED - - EXECUTION_FAILED_POST_DEBIT - - SETTLEMENT_FAILED - - TIMEOUT - - MANUAL_REFUND - 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. + - 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. + + 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. + + `SCA_NOT_COMPLETED` means the customer did not satisfy the Strong Customer + Authentication challenge before it expired, so the transaction was never + authorized and no funds were moved. Only occurs for customers in a region + where SCA is required (e.g. the EU). Create a new quote to try again, and have + the customer authorize it while the challenge is live. - `SCA_NOT_COMPLETED` means the customer did not satisfy the Strong Customer Authentication challenge before it expired, so the transaction was never authorized and no funds were moved. Only occurs for customers in a region where SCA is required (e.g. the EU). Create a new quote to try again, and have the customer authorize it while the challenge is live. + | Reason | Description | + |--------|-------------| + | `QUOTE_EXPIRED` | The quote was not executed before its expiry window | + | `QUOTE_EXECUTION_FAILED` | The quote could not be executed. Covers any internal failure on the way to settlement, whether or not funds were debited — a debited amount is refunded automatically | + | `FUNDING_AMOUNT_MISMATCH` | The funds received did not match the expected amount | + | `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_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 | RailSelectionMode: type: string enum: diff --git a/openapi/components/schemas/transactions/OutgoingTransactionFailureReason.yaml b/openapi/components/schemas/transactions/OutgoingTransactionFailureReason.yaml index 0147fa707..8fe12beb6 100644 --- a/openapi/components/schemas/transactions/OutgoingTransactionFailureReason.yaml +++ b/openapi/components/schemas/transactions/OutgoingTransactionFailureReason.yaml @@ -2,22 +2,42 @@ type: string enum: - QUOTE_EXPIRED - QUOTE_EXECUTION_FAILED - - LIGHTNING_PAYMENT_FAILED - FUNDING_AMOUNT_MISMATCH - - COUNTERPARTY_POST_TX_FAILED - SCA_NOT_COMPLETED - - EXECUTION_FAILED_POST_DEBIT - - SETTLEMENT_FAILED - - TIMEOUT - - MANUAL_REFUND -description: >- + - 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. + 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. `SCA_NOT_COMPLETED` means the customer did not satisfy the Strong Customer Authentication challenge before it expired, so the transaction was never authorized and no funds were moved. Only occurs for customers in a region where SCA is required (e.g. the EU). Create a new quote to try again, and have the customer authorize it while the challenge is live. + + | Reason | Description | + |--------|-------------| + | `QUOTE_EXPIRED` | The quote was not executed before its expiry window | + | `QUOTE_EXECUTION_FAILED` | The quote could not be executed. Covers any internal failure on the way to settlement, whether or not funds were debited — a debited amount is refunded automatically | + | `FUNDING_AMOUNT_MISMATCH` | The funds received did not match the expected amount | + | `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_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 |