diff --git a/mintlify/api-reference/sandbox-manual-cancellations.mdx b/mintlify/api-reference/sandbox-manual-cancellations.mdx new file mode 100644 index 000000000..bfaa808d5 --- /dev/null +++ b/mintlify/api-reference/sandbox-manual-cancellations.mdx @@ -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` + + +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). + diff --git a/mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx b/mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx index eeac2c0b1..59ab785df 100644 --- a/mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx +++ b/mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx @@ -415,6 +415,8 @@ Payment is cancelled while still processing, and the refund succeeds: 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. + +To test this flow in sandbox, see [Sandbox Manual Cancellations](/api-reference/sandbox-manual-cancellations). diff --git a/mintlify/ramps/platform-tools/sandbox-testing.mdx b/mintlify/ramps/platform-tools/sandbox-testing.mdx index 5149f8ba3..592d99d9c 100644 --- a/mintlify/ramps/platform-tools/sandbox-testing.mdx +++ b/mintlify/ramps/platform-tools/sandbox-testing.mdx @@ -234,7 +234,7 @@ curl -X POST 'https://api.lightspark.com/grid/2025-10-13/customers/external-acco ``` -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. ### Step 3: Create and execute off-ramp quote diff --git a/mintlify/snippets/sandbox-quote-patterns.mdx b/mintlify/snippets/sandbox-quote-patterns.mdx index 82c2e452b..d2d79cd29 100644 --- a/mintlify/snippets/sandbox-quote-patterns.mdx +++ b/mintlify/snippets/sandbox-quote-patterns.mdx @@ -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` |