Skip to content

feat!: granular counterparty payout failure reasons#689

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JasonCWang merged 6 commits into from
Aug 13, 2026
Merged

feat!: granular counterparty payout failure reasons #689

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
1ff8fcd
feat(openapi): add counterparty payout failure reasons
JasonCWang Jul 7, 2026
90bf844
docs(openapi): sync outgoing failure reasons with send enum
JasonCWang Jul 14, 2026
2b11381
docs: sync outgoing payment failure reasons in MDX with enum
JasonCWang Jul 14, 2026
69fd0d8
docs(openapi): drop unqualified "no funds were debited" claim
JasonCWang Jul 14, 2026
50287f2
feat(openapi): drop LSP_OPERATIONAL_FAILURE from the public enum
JasonCWang Aug 13, 2026
6b40894
feat(openapi)!: drop internal-only outgoing failure reasons
JasonCWang Aug 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 36 additions & 9 deletions mintlify/openapi.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

14 changes: 9 additions & 5 deletions mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -252,7 +252,7 @@ Outgoing payment webhooks use the format `OUTGOING_PAYMENT.<STATUS>`. The webhoo
"data": {
"id": "Transaction:...",
"status": "FAILED",
"failureReason": "INVALID_BANK_ACCOUNT"
"failureReason": "ACCOUNT_INVALID"
}
}
```
Expand DownExpand Up@@ -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.

Expand Down
7 changes: 6 additions & 1 deletion mintlify/snippets/error-handling.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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

Expand Down
45 changes: 36 additions & 9 deletions openapi.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

34 changes: 27 additions & 7 deletions openapi/components/schemas/transactions/OutgoingTransactionFailureReason.yaml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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 |
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all 
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
feat!: granular counterparty payout failure reasons by JasonCWang · Pull Request #689 · lightsparkdev/grid-api · GitHub
Skip to content
feat!: granular counterparty payout failure reasons#689

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

JasonCWang
merged 6 commits into

from

Aug 13, 2026
 Merged


feat!: granular counterparty payout failure reasons
#689
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
1ff8fcd

feat(openapi): add counterparty payout failure reasons


JasonCWang Jul 7, 2026
90bf844

docs(openapi): sync outgoing failure reasons with send enum


JasonCWang Jul 14, 2026
2b11381

docs: sync outgoing payment failure reasons in MDX with enum


JasonCWang Jul 14, 2026
69fd0d8

docs(openapi): drop unqualified "no funds were debited" claim


JasonCWang Jul 14, 2026
50287f2

feat(openapi): drop LSP_OPERATIONAL_FAILURE from the public enum


JasonCWang Aug 13, 2026
6b40894

feat(openapi)!: drop internal-only outgoing failure reasons


JasonCWang Aug 13, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


45 changes: 36 additions & 9 deletions
mintlify/openapi.yaml

View file


Open in desktop


Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.


14 changes: 9 additions & 5 deletions
mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -252,7 +252,7 @@ Outgoing payment webhooks use the format `OUTGOING_PAYMENT.<STATUS>`. The webhoo
 "data": {
 "id": "Transaction:...",
 "status": "FAILED",
 "failureReason": "INVALID_BANK_ACCOUNT"
 "failureReason": "ACCOUNT_INVALID"
 }
}
```
Expand DownExpand Up@@ -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.

Expand Down

7 changes: 6 additions & 1 deletion
mintlify/snippets/error-handling.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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

Expand Down

45 changes: 36 additions & 9 deletions
openapi.yaml

View file


Open in desktop


Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.


34 changes: 27 additions & 7 deletions
openapi/components/schemas/transactions/OutgoingTransactionFailureReason.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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 |
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Force GitHub README to respect dark mode
(function() {
var style = document.createElement('style');
style.textContent = '
.markdown-body {
color-scheme: dark light;
}
.markdown-body pre { background: #161b22 !important; }
.markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }
.markdown-body table th, .markdown-body table td { border-color: #30363d !important; }
.markdown-body img { background: #0d1117; }
.markdown-body blockquote { border-left-color: #8b949e; }
.markdown-body hr { border-color: #30363d; }
';
document.head.appendChild(style);
})();
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
feat!: granular counterparty payout failure reasons by JasonCWang · Pull Request #689 · lightsparkdev/grid-api · GitHub
Skip to content
feat!: granular counterparty payout failure reasons#689

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

JasonCWang
merged 6 commits into

from

Aug 13, 2026
 Merged


feat!: granular counterparty payout failure reasons
#689
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
1ff8fcd

feat(openapi): add counterparty payout failure reasons


JasonCWang Jul 7, 2026
90bf844

docs(openapi): sync outgoing failure reasons with send enum


JasonCWang Jul 14, 2026
2b11381

docs: sync outgoing payment failure reasons in MDX with enum


JasonCWang Jul 14, 2026
69fd0d8

docs(openapi): drop unqualified "no funds were debited" claim


JasonCWang Jul 14, 2026
50287f2

feat(openapi): drop LSP_OPERATIONAL_FAILURE from the public enum


JasonCWang Aug 13, 2026
6b40894

feat(openapi)!: drop internal-only outgoing failure reasons


JasonCWang Aug 13, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


45 changes: 36 additions & 9 deletions
mintlify/openapi.yaml

View file


Open in desktop


Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.


14 changes: 9 additions & 5 deletions
mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -252,7 +252,7 @@ Outgoing payment webhooks use the format `OUTGOING_PAYMENT.<STATUS>`. The webhoo
 "data": {
 "id": "Transaction:...",
 "status": "FAILED",
 "failureReason": "INVALID_BANK_ACCOUNT"
 "failureReason": "ACCOUNT_INVALID"
 }
}
```
Expand DownExpand Up@@ -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.

Expand Down

7 changes: 6 additions & 1 deletion
mintlify/snippets/error-handling.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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

Expand Down

45 changes: 36 additions & 9 deletions
openapi.yaml

View file


Open in desktop


Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.


34 changes: 27 additions & 7 deletions
openapi/components/schemas/transactions/OutgoingTransactionFailureReason.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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 |
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Highlight search terms from Google/DuckDuckGo/Bing referrer
(function() {
var ref = document.referrer;
var terms = [];
if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {
var url = new URL(ref);
var q = url.searchParams.get('q') || url.searchParams.get('p');
if (q) {
terms = q.split(/\s+/).filter(function(t) { return t.length > 2; });
}
}
if (terms.length === 0) return;
var style = document.createElement('style');
style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';
document.head.appendChild(style);
function highlight(node) {
if (node.nodeType === 3) { // text node
var text = node.textContent;
var found = false;
terms.forEach(function(term) {
var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi');
if (regex.test(text)) {
found = true;
var frag = document.createDocumentFragment();
var parts = text.split(regex);
parts.forEach(function(part, i) {
if (i % 2 === 0) {
frag.appendChild(document.createTextNode(part));
} else {
var span = document.createElement('span');
span.className = 'userscript-highlight';
span.textContent = part;
frag.appendChild(span);
}
});
node.parentNode.replaceChild(frag, node);
}
});
} else if (node.nodeType === 1 && node.childNodes) { // element
var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];
if (!skipTags.includes(node.tagName)) {
Array.from(node.childNodes).forEach(highlight);
}
}
}
highlight(document.body);
// Re-highlight on dynamic content
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1 || node.nodeType === 3) highlight(node);
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
feat!: granular counterparty payout failure reasons by JasonCWang · Pull Request #689 · lightsparkdev/grid-api · GitHub
Skip to content
feat!: granular counterparty payout failure reasons#689

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

JasonCWang
merged 6 commits into

from

Aug 13, 2026
 Merged


feat!: granular counterparty payout failure reasons
#689
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
1ff8fcd

feat(openapi): add counterparty payout failure reasons


JasonCWang Jul 7, 2026
90bf844

docs(openapi): sync outgoing failure reasons with send enum


JasonCWang Jul 14, 2026
2b11381

docs: sync outgoing payment failure reasons in MDX with enum


JasonCWang Jul 14, 2026
69fd0d8

docs(openapi): drop unqualified "no funds were debited" claim


JasonCWang Jul 14, 2026
50287f2

feat(openapi): drop LSP_OPERATIONAL_FAILURE from the public enum


JasonCWang Aug 13, 2026
6b40894

feat(openapi)!: drop internal-only outgoing failure reasons


JasonCWang Aug 13, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


45 changes: 36 additions & 9 deletions
mintlify/openapi.yaml

View file


Open in desktop


Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.


14 changes: 9 additions & 5 deletions
mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -252,7 +252,7 @@ Outgoing payment webhooks use the format `OUTGOING_PAYMENT.<STATUS>`. The webhoo
 "data": {
 "id": "Transaction:...",
 "status": "FAILED",
 "failureReason": "INVALID_BANK_ACCOUNT"
 "failureReason": "ACCOUNT_INVALID"
 }
}
```
Expand DownExpand Up@@ -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.

Expand Down

7 changes: 6 additions & 1 deletion
mintlify/snippets/error-handling.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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

Expand Down

45 changes: 36 additions & 9 deletions
openapi.yaml

View file


Open in desktop


Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.


34 changes: 27 additions & 7 deletions
openapi/components/schemas/transactions/OutgoingTransactionFailureReason.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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 |
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Strip utm_, fbclid, gclid, etc. from all links on page
(function() {
var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',
'ref', 'ref_src', 'source', 'medium', 'campaign'];
function cleanUrl(url) {
try {
var u = new URL(url, window.location.origin);
var changed = false;
trackingParams.forEach(function(p) {
if (u.searchParams.has(p)) {
u.searchParams.delete(p);
changed = true;
}
});
return changed ? u.toString() : url;
} catch (e) {
return url;
}
}
function cleanLinks() {
document.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
cleanLinks();
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1) {
if (node.tagName === 'A') cleanLinks();
node.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '
feat!: granular counterparty payout failure reasons by JasonCWang · Pull Request #689 · lightsparkdev/grid-api · GitHub
Skip to content
feat!: granular counterparty payout failure reasons#689

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

JasonCWang
merged 6 commits into

from

Aug 13, 2026
 Merged


feat!: granular counterparty payout failure reasons
#689
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
1ff8fcd

feat(openapi): add counterparty payout failure reasons


JasonCWang Jul 7, 2026
90bf844

docs(openapi): sync outgoing failure reasons with send enum


JasonCWang Jul 14, 2026
2b11381

docs: sync outgoing payment failure reasons in MDX with enum


JasonCWang Jul 14, 2026
69fd0d8

docs(openapi): drop unqualified "no funds were debited" claim


JasonCWang Jul 14, 2026
50287f2

feat(openapi): drop LSP_OPERATIONAL_FAILURE from the public enum


JasonCWang Aug 13, 2026
6b40894

feat(openapi)!: drop internal-only outgoing failure reasons


JasonCWang Aug 13, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


45 changes: 36 additions & 9 deletions
mintlify/openapi.yaml

View file


Open in desktop


Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.


14 changes: 9 additions & 5 deletions
mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -252,7 +252,7 @@ Outgoing payment webhooks use the format `OUTGOING_PAYMENT.<STATUS>`. The webhoo
 "data": {
 "id": "Transaction:...",
 "status": "FAILED",
 "failureReason": "INVALID_BANK_ACCOUNT"
 "failureReason": "ACCOUNT_INVALID"
 }
}
```
Expand DownExpand Up@@ -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.

Expand Down

7 changes: 6 additions & 1 deletion
mintlify/snippets/error-handling.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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

Expand Down

45 changes: 36 additions & 9 deletions
openapi.yaml

View file


Open in desktop


Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.


34 changes: 27 additions & 7 deletions
openapi/components/schemas/transactions/OutgoingTransactionFailureReason.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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 |
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Auto-enable theater mode on YouTube
(function() {
function tryTheater() {
var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]');
if (btn && !btn.classList.contains('activated')) {
btn.click();
}
}
// Try immediately
tryTheater();
// Try after navigation (SPA)
var lastUrl = location.href;
setInterval(function() {
if (location.href !== lastUrl) {
lastUrl = location.href;
setTimeout(tryTheater, 500);
}
}, 1000);
// Also try on player load
var observer = new MutationObserver(tryTheater);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
feat!: granular counterparty payout failure reasons by JasonCWang · Pull Request #689 · lightsparkdev/grid-api · GitHub
Skip to content
feat!: granular counterparty payout failure reasons#689

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

JasonCWang
merged 6 commits into

from

Aug 13, 2026
 Merged


feat!: granular counterparty payout failure reasons
#689
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
1ff8fcd

feat(openapi): add counterparty payout failure reasons


JasonCWang Jul 7, 2026
90bf844

docs(openapi): sync outgoing failure reasons with send enum


JasonCWang Jul 14, 2026
2b11381

docs: sync outgoing payment failure reasons in MDX with enum


JasonCWang Jul 14, 2026
69fd0d8

docs(openapi): drop unqualified "no funds were debited" claim


JasonCWang Jul 14, 2026
50287f2

feat(openapi): drop LSP_OPERATIONAL_FAILURE from the public enum


JasonCWang Aug 13, 2026
6b40894

feat(openapi)!: drop internal-only outgoing failure reasons


JasonCWang Aug 13, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


45 changes: 36 additions & 9 deletions
mintlify/openapi.yaml

View file


Open in desktop


Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.


14 changes: 9 additions & 5 deletions
mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -252,7 +252,7 @@ Outgoing payment webhooks use the format `OUTGOING_PAYMENT.<STATUS>`. The webhoo
 "data": {
 "id": "Transaction:...",
 "status": "FAILED",
 "failureReason": "INVALID_BANK_ACCOUNT"
 "failureReason": "ACCOUNT_INVALID"
 }
}
```
Expand DownExpand Up@@ -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.

Expand Down

7 changes: 6 additions & 1 deletion
mintlify/snippets/error-handling.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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

Expand Down

45 changes: 36 additions & 9 deletions
openapi.yaml

View file


Open in desktop


Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.


34 changes: 27 additions & 7 deletions
openapi/components/schemas/transactions/OutgoingTransactionFailureReason.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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 |
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Remove or un-stick sticky/fixed headers that block content
(function() {
function unstick() {
document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) {
if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {
el.style.position = 'static';
el.style.top = 'auto';
el.style.zIndex = 'auto';
}
});
}
unstick();
var observer = new MutationObserver(unstick);
observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });
})();
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
})();
feat!: granular counterparty payout failure reasons by JasonCWang · Pull Request #689 · lightsparkdev/grid-api · GitHub
Skip to content
feat!: granular counterparty payout failure reasons#689

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

JasonCWang
merged 6 commits into

from

Aug 13, 2026
 Merged


feat!: granular counterparty payout failure reasons
#689
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
1ff8fcd

feat(openapi): add counterparty payout failure reasons


JasonCWang Jul 7, 2026
90bf844

docs(openapi): sync outgoing failure reasons with send enum


JasonCWang Jul 14, 2026
2b11381

docs: sync outgoing payment failure reasons in MDX with enum


JasonCWang Jul 14, 2026
69fd0d8

docs(openapi): drop unqualified "no funds were debited" claim


JasonCWang Jul 14, 2026
50287f2

feat(openapi): drop LSP_OPERATIONAL_FAILURE from the public enum


JasonCWang Aug 13, 2026
6b40894

feat(openapi)!: drop internal-only outgoing failure reasons


JasonCWang Aug 13, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


45 changes: 36 additions & 9 deletions
mintlify/openapi.yaml

View file


Open in desktop


Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.


14 changes: 9 additions & 5 deletions
mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -252,7 +252,7 @@ Outgoing payment webhooks use the format `OUTGOING_PAYMENT.<STATUS>`. The webhoo
 "data": {
 "id": "Transaction:...",
 "status": "FAILED",
 "failureReason": "INVALID_BANK_ACCOUNT"
 "failureReason": "ACCOUNT_INVALID"
 }
}
```
Expand DownExpand Up@@ -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.

Expand Down

7 changes: 6 additions & 1 deletion
mintlify/snippets/error-handling.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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

Expand Down

45 changes: 36 additions & 9 deletions
openapi.yaml

View file


Open in desktop


Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.


34 changes: 27 additions & 7 deletions
openapi/components/schemas/transactions/OutgoingTransactionFailureReason.yaml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -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 |
Loading