From 05b5744a29de51130e5fcc22912a439b85118f45 Mon Sep 17 00:00:00 2001 From: Bolt Agent Date: Mon, 24 Aug 2026 23:49:28 +0000 Subject: [PATCH] docs(transactions): document the cancel 501 and add a CANCELED status Co-Authored-By: AaryamanBhute --- mintlify/changelog.mdx | 15 ++++++++++ mintlify/openapi.yaml | 18 +++++++++--- openapi.yaml | 18 +++++++++--- .../OutgoingTransactionStatus.yaml | 2 ++ .../webhooks/OutgoingPaymentWebhook.yaml | 1 + .../schemas/webhooks/WebhookType.yaml | 1 + .../transactions_{transactionId}_cancel.yaml | 28 ++++++++++++++----- 7 files changed, 68 insertions(+), 15 deletions(-) diff --git a/mintlify/changelog.mdx b/mintlify/changelog.mdx index ea908e117..47df8f365 100644 --- a/mintlify/changelog.mdx +++ b/mintlify/changelog.mdx @@ -11,6 +11,21 @@ changes and roadmap, [book a live demo](https://www.lightspark.com/contact) or +## 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 diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 51644742f..837108d80 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -4706,10 +4706,10 @@ paths: $ref: '#/components/schemas/Error500' /transactions/{transactionId}/cancel: 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. - 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. + 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. 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 @@ -4730,7 +4730,7 @@ paths: $ref: '#/components/schemas/CancelTransactionRequest' 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: @@ -4765,6 +4765,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Error500' + '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/Error501' /crypto/estimate-withdrawal-fee: post: summary: Estimate crypto withdrawal fee @@ -21775,6 +21781,7 @@ components: - PROCESSING - COMPLETED - FAILED + - CANCELED description: | Status of an outgoing payment transaction. @@ -21786,6 +21793,7 @@ components: | `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 | OutgoingRateDetails: description: 'Details about the rate and fees for an outgoing transaction or quote. Note: `counterpartyFixedFee` is denominated in the receiving currency, so its equivalent value in the sending currency fluctuates with the FX rate. As a result, the total fee on a subsequent quote for the same transfer may differ even if the underlying fee structure is unchanged.' type: object @@ -25481,6 +25489,7 @@ components: - OUTGOING_PAYMENT.COMPLETED - OUTGOING_PAYMENT.FAILED - OUTGOING_PAYMENT.EXPIRED + - OUTGOING_PAYMENT.CANCELED - OUTGOING_PAYMENT.REFUND_PENDING - OUTGOING_PAYMENT.REFUND_COMPLETED - OUTGOING_PAYMENT.REFUND_FAILED @@ -25629,6 +25638,7 @@ components: - OUTGOING_PAYMENT.COMPLETED - OUTGOING_PAYMENT.FAILED - OUTGOING_PAYMENT.EXPIRED + - OUTGOING_PAYMENT.CANCELED - OUTGOING_PAYMENT.REFUND_PENDING - OUTGOING_PAYMENT.REFUND_COMPLETED - OUTGOING_PAYMENT.REFUND_FAILED diff --git a/openapi.yaml b/openapi.yaml index 51644742f..837108d80 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -4706,10 +4706,10 @@ paths: $ref: '#/components/schemas/Error500' /transactions/{transactionId}/cancel: 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. - 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. + 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. 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 @@ -4730,7 +4730,7 @@ paths: $ref: '#/components/schemas/CancelTransactionRequest' 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: @@ -4765,6 +4765,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Error500' + '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/Error501' /crypto/estimate-withdrawal-fee: post: summary: Estimate crypto withdrawal fee @@ -21775,6 +21781,7 @@ components: - PROCESSING - COMPLETED - FAILED + - CANCELED description: | Status of an outgoing payment transaction. @@ -21786,6 +21793,7 @@ components: | `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 | OutgoingRateDetails: description: 'Details about the rate and fees for an outgoing transaction or quote. Note: `counterpartyFixedFee` is denominated in the receiving currency, so its equivalent value in the sending currency fluctuates with the FX rate. As a result, the total fee on a subsequent quote for the same transfer may differ even if the underlying fee structure is unchanged.' type: object @@ -25481,6 +25489,7 @@ components: - OUTGOING_PAYMENT.COMPLETED - OUTGOING_PAYMENT.FAILED - OUTGOING_PAYMENT.EXPIRED + - OUTGOING_PAYMENT.CANCELED - OUTGOING_PAYMENT.REFUND_PENDING - OUTGOING_PAYMENT.REFUND_COMPLETED - OUTGOING_PAYMENT.REFUND_FAILED @@ -25629,6 +25638,7 @@ components: - OUTGOING_PAYMENT.COMPLETED - OUTGOING_PAYMENT.FAILED - OUTGOING_PAYMENT.EXPIRED + - OUTGOING_PAYMENT.CANCELED - OUTGOING_PAYMENT.REFUND_PENDING - OUTGOING_PAYMENT.REFUND_COMPLETED - OUTGOING_PAYMENT.REFUND_FAILED diff --git a/openapi/components/schemas/transactions/OutgoingTransactionStatus.yaml b/openapi/components/schemas/transactions/OutgoingTransactionStatus.yaml index e23f5e263..7330103f6 100644 --- a/openapi/components/schemas/transactions/OutgoingTransactionStatus.yaml +++ b/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 | diff --git a/openapi/components/schemas/webhooks/OutgoingPaymentWebhook.yaml b/openapi/components/schemas/webhooks/OutgoingPaymentWebhook.yaml index 4163eb87d..f19ac64d1 100644 --- a/openapi/components/schemas/webhooks/OutgoingPaymentWebhook.yaml +++ b/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 diff --git a/openapi/components/schemas/webhooks/WebhookType.yaml b/openapi/components/schemas/webhooks/WebhookType.yaml index d60b445e4..e7fdbdaee 100644 --- a/openapi/components/schemas/webhooks/WebhookType.yaml +++ b/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 diff --git a/openapi/paths/transactions/transactions_{transactionId}_cancel.yaml b/openapi/paths/transactions/transactions_{transactionId}_cancel.yaml index 7d2899ee5..579a6b12b 100644 --- a/openapi/paths/transactions/transactions_{transactionId}_cancel.yaml +++ b/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