Skip to content

docs(sandbox): move the manual cancellation suffixes to their own page #1193

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 1 commit into from
Oct 16, 2026
Merged

docs(sandbox): move the manual cancellation suffixes to their own page #1193

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
46 changes: 46 additions & 0 deletions mintlify/api-reference/sandbox-manual-cancellations.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
---
hidden: true
title: "Sandbox Manual Cancellations"
description: "Simulate a payout that is cancelled and refunded on your customer's request"
icon: "/images/icons/hammer.svg"
"og:image": "/images/og/og-api-reference.png"
---

A manual cancellation happens when your customer asks for a payout to be
cancelled, and the sender is refunded. Use these suffixes on the external
account a quote pays out to. They work the same way as the
[quote destination test patterns](/api-reference/sandbox-testing#creating-quotes).

| Suffix | Behavior |
|--------|----------|
| **006** | Cancelled after completion — the payment completes, then about two minutes later the sender is refunded |
| **008** | Cancelled while processing — the sender is refunded about a minute after execution, then the payment completes about two minutes later |

In both cases the refund has `reason: USER_CANCELLATION`, and the transaction
status stays `COMPLETED`. Check the transaction's `refund` object to see that
the sender got the money back.

## Webhook order

**006 — cancelled after completion:**

1. `OUTGOING_PAYMENT.PENDING`
2. `OUTGOING_PAYMENT.PROCESSING`
3. `OUTGOING_PAYMENT.COMPLETED`
4. `OUTGOING_PAYMENT.REFUND_PENDING`
5. `OUTGOING_PAYMENT.REFUND_COMPLETED`

**008 — cancelled while processing:**

1. `OUTGOING_PAYMENT.PENDING`
2. `OUTGOING_PAYMENT.PROCESSING`
3. `OUTGOING_PAYMENT.REFUND_PENDING`
4. `OUTGOING_PAYMENT.REFUND_COMPLETED`
5. `OUTGOING_PAYMENT.COMPLETED`

<Info>
With **008**, `OUTGOING_PAYMENT.COMPLETED` arrives after the refund settles.
This means the payout was delivered even though the sender was refunded. See
the Manual Cancellation flow in
[Transaction Lifecycle](/platform-overview/core-concepts/transaction-lifecycle).
</Info>
2 changes: 2 additions & 0 deletions mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -415,6 +415,8 @@ Payment is cancelled while still processing, and the refund succeeds:
<Info>
In the manual cancellation flow, `OUTGOING_PAYMENT.COMPLETED` fires after the refund settles. This indicates the payout provider ultimately delivered the original payment despite the cancellation attempt. Your system should check the transaction's `refund` object to determine whether the payment was refunded or delivered.
</Info>

To test this flow in sandbox, see [Sandbox Manual Cancellations](/api-reference/sandbox-manual-cancellations).
</Tab>
</Tabs>

Expand Down
2 changes: 1 addition & 1 deletion mintlify/ramps/platform-tools/sandbox-testing.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -234,7 +234,7 @@ curl -X POST 'https://api.lightspark.com/grid/2025-10-13/customers/external-acco
```

<Note>
In sandbox, you can use special account number patterns to test different scenarios. The **last 3 digits** determine the behavior, and the meaning depends on how the account is used. This account is the destination of the off-ramp quote below, so the quote patterns apply: **002** (quote execution failed), **003** (long payment), **004** (counterparty delivery failed), **005** (receiving bank returned the payment), **006** (user cancellation), **007** (payout and refund failed), **008** (user cancellation while processing). Any other ending succeeds normally. See "Quote destination test patterns" below for the full table.
In sandbox, you can use special account number patterns to test different scenarios. The **last 3 digits** determine the behavior, and the meaning depends on how the account is used. This account is the destination of the off-ramp quote below, so the quote patterns apply: **002** (quote execution failed), **003** (long payment), **004** (counterparty delivery failed), **005** (receiving bank returned the payment), **007** (payout and refund failed). Any other ending succeeds normally. See "Quote destination test patterns" below for the full table.

@greptile-apps greptile-apps Bot Oct 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Unlisted endings can trigger refunds

Removing 006 and 008 makes “Any other ending succeeds normally” incorrect. Both endings still trigger refunds, as the new page explains. The shared quote table also labels unlisted endings as successful payments. Developers choosing an unlisted suffix for a normal sandbox payout can therefore trigger a cancellation instead. Exclude these endings from both fallback descriptions without restoring them to the main table.

Prompt To Fix With AI 
This is a comment left during a code review.
Path: mintlify/ramps/platform-tools/sandbox-testing.mdx
Line: 237

Comment:
**Unlisted endings can trigger refunds**

Removing `006` and `008` makes “Any other ending succeeds normally” incorrect. Both endings still trigger refunds, as the new page explains. The shared quote table also labels unlisted endings as successful payments. Developers choosing an unlisted suffix for a normal sandbox payout can therefore trigger a cancellation instead. Exclude these endings from both fallback descriptions without restoring them to the main table.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

</Note>

### Step 3: Create and execute off-ramp quote
Expand Down
2 changes: 0 additions & 2 deletions mintlify/snippets/sandbox-quote-patterns.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,7 @@ When creating a quote with an external account destination, the account number s
| **003** | Long payment — completes after approximately 6 minutes |
| **004** | Counterparty delivery failed |
| **005** | Receiving bank returned the payment — completes, then fails with `failureReason: PAYOUT_RETURNED` |
| **006** | User cancellation |
| **007** | Payout and refund failed |
| **008** | User cancellation while processing — the payment is refunded about a minute after execution, before it reaches the destination |
| **010** | Payout rejected by compliance screening — fails with `failureReason: COMPLIANCE_REJECTED` |
| **011** | Invalid recipient account details — fails with `failureReason: ACCOUNT_INVALID` |
| **012** | Recipient account cannot receive the payout — fails with `failureReason: ACCOUNT_CANNOT_RECEIVE` |
Expand Down
Loading