docs(transactions): document the cancel 501 and add a CANCELED transaction status

mintlify/changelog.mdx

@@ -11,6 +11,21 @@ changes and roadmap, [book a live demo](https://www.lightspark.com/contact) or
 
 <Update label="August 2026">
 
+## Cancel a pending ACH transfer
+
+Call off an ACH push or pull that hasn't settled yet—for example a payment initiated
+outside the receiving bank's processing window.
+
+- `POST /transactions/{transactionId}/cancel` forwards the request to the banking
+  partner settling the transfer, with an optional `reason` for your own records.
+- A `200` means the partner accepted the request; it confirms asynchronously, so the
+  transaction may still report its pre-cancellation status when the call returns. Once
+  confirmed, the transaction reaches the new terminal `CANCELED` status and no funds
+  moved.
+- A transfer the partner has already processed returns `409 TRANSACTION_NOT_CANCELLABLE`.
+  Rails that cannot be withdrawn once submitted—wires and RTP—are never cancellable.
+- Rails whose partner exposes no cancellation facility return `501 NOT_IMPLEMENTED`.
+
 ## Assess your own fees on every transaction
 
 Charge your customers a platform fee and keep the margin—Grid collects it for you and

openapi/components/schemas/transactions/OutgoingTransactionStatus.yaml

@@ -6,6 +6,7 @@ enum:
   - PROCESSING
   - COMPLETED
   - FAILED
+  - CANCELED
 description: |
   Status of an outgoing payment transaction.
 
@@ -17,3 +18,4 @@ description: |
   | `PROCESSING` | Executing the quote after receiving funds |
   | `COMPLETED` | Payout successfully reached the destination |
   | `FAILED` | Something went wrong — accompanied by a `failureReason` |
+  | `CANCELED` | The transfer was cancelled at the platform's request via `POST /transactions/{transactionId}/cancel` before it settled, so no funds moved |

openapi/components/schemas/webhooks/OutgoingPaymentWebhook.yaml

@@ -15,6 +15,7 @@ allOf:
           - OUTGOING_PAYMENT.COMPLETED
           - OUTGOING_PAYMENT.FAILED
           - OUTGOING_PAYMENT.EXPIRED
+          - OUTGOING_PAYMENT.CANCELED
           - OUTGOING_PAYMENT.REFUND_PENDING
           - OUTGOING_PAYMENT.REFUND_COMPLETED
           - OUTGOING_PAYMENT.REFUND_FAILED

openapi/components/schemas/webhooks/WebhookType.yaml

@@ -6,6 +6,7 @@ enum:
   - OUTGOING_PAYMENT.COMPLETED
   - OUTGOING_PAYMENT.FAILED
   - OUTGOING_PAYMENT.EXPIRED
+  - OUTGOING_PAYMENT.CANCELED
   - OUTGOING_PAYMENT.REFUND_PENDING
   - OUTGOING_PAYMENT.REFUND_COMPLETED
   - OUTGOING_PAYMENT.REFUND_FAILED

openapi/paths/transactions/transactions_{transactionId}_cancel.yaml

@@ -1,16 +1,17 @@
 post:
-  summary: Cancel a bank transfer
+  summary: Cancel an ACH transfer
   description: >
-    Request cancellation of a pending bank transfer — an ACH transfer (push or
-    pull) or a wire — before it has settled, for example a payment or
-    collection initiated outside of the receiving bank's processing window.
+    Request cancellation of a pending ACH transfer — a push or a pull — before
+    it has settled, for example a payment or collection initiated outside of
+    the receiving bank's processing window.
 
     Whether a transfer can still be cancelled is determined by the banking
     partner that is settling it: the request is forwarded to the partner's own
     cancellation facility, and a transfer that the partner has already
     processed (or that is otherwise past its cancellation window) cannot be
-    cancelled. Cancellation applies to bank-rail transfers; requests for
-    transaction types that cannot be cancelled are rejected.
+    cancelled. Rails that cannot be withdrawn once submitted — wires and RTP —
+    are never cancellable, and requests for transaction types that cannot be
+    cancelled are rejected.
   operationId: cancelTransaction
   tags:
     - Transactions
@@ -31,7 +32,10 @@ post:
           $ref: ../../components/schemas/transactions/CancelTransactionRequest.yaml
   responses:
     '200':
-      description: Cancellation requested successfully
+      description: >-
+        The banking partner accepted the cancellation request. The transfer
+        reaches its cancelled state once the partner confirms it, so the
+        transaction returned here may still report its pre-cancellation status.
       content:
         application/json:
           schema:
@@ -68,3 +72,13 @@ post:
         application/json:
           schema:
             $ref: ../../components/schemas/errors/Error500.yaml
+    '501':
+      description: >-
+        Cancellation is not yet available for the payment rail settling this
+        transfer. Support is being rolled out per rail and per banking partner;
+        transfers on a rail that is not covered yet return
+        `501 NOT_IMPLEMENTED`. Track availability in the Grid changelog.
+      content:
+        application/json:
+          schema:
+            $ref: ../../components/schemas/errors/Error501.yaml