Cancel Payments When Plans Change

Sometimes payments need to be stopped - a customer changes their mind, duplicate payment detected, or wrong beneficiary details. Inventi handles the cancellation protocol with the beneficiary bank on your behalf.

What happens when you cancel a payment:

You submit a cancellation request via API
Inventi sends a cancellation request to the beneficiary or correspondent bank
That bank accepts or rejects the request
You receive the outcome via webhook

Cancellation is a request, not a guarantee. The other bank may accept or reject it based on whether funds have been credited.

One Endpoint, Every Scheme

Cancel payments handles SEPA CT/Instant, SEPA Direct Debit, SWIFT and T2. You do not declare the scheme - it is derived from the payments you reference. All payments in one request must belong to the same scheme, so send one request per scheme.

SWIFT and T2 payments can only be cancelled through this endpoint. The older per-scheme endpoints are limited to SEPA and SEPA Direct Debit, and remain available for existing integrations.

For what is specific to SWIFT - the correspondent capability check and the message flow - see Cancel SWIFT payments.

API Reference

Cancel Payments

Initiate a cancellation request

Cancellation Status Webhook

Track cancellation lifecycle

Get Cancellation Request

Retrieve cancellation details

List Cancellation Requests

Search cancellation requests

How It Works

Request Flow

You submit a cancellation request naming one or more payments
Each payment is assessed on its own and comes back ACCEPTED or REJECTED
For an accepted payment that has already been sent, a cancellation request goes to the beneficiary or correspondent bank
You receive webhook updates as the request progresses

Not Yet Sent vs Already Sent

ACCEPTED means two different things, and the difference matters.Not yet sent (Created, To sign, Signed): the payment is cancelled outright. Its status becomes Cancelled, nothing goes to the other bank, and no cancellation request is created - so there is nothing to track and no cancellation webhook. You get a payment-status-change webhook instead. This is final.Already sent (Sent to clear, Accepted, Completed): a cancellation request is created and sent. ACCEPTED means the message went out, not that the money is coming back.

Possible Outcomes

Once the request is with the other bank, it can:

Accept: funds come back as a payment return - a new linked inbound transaction; the original settled payment stays Completed
Refuse: the bank declines to return the funds (CANCELLATION_REFUSED)

Never assume cancellation succeeded until the webhook indicates PAYMENT_RETURNED. On SWIFT in particular, an accepted cancellation only means the correspondent agreed - the funds move in a separate message that may arrive much later.

Initiate Cancellation

curl -X POST https://api.pgw-sandbox.finventi.com/v3/payments/cancellations \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "CUST",
    "paymentIds": [12345, 12346]
  }'

{
  "results": [
    { "paymentId": 12345, "status": "ACCEPTED" },
    {
      "paymentId": 12346,
      "status": "REJECTED",
      "error": "Cancellation is not supported for correspondent DEUTDEFFXXX (transaction 12346)"
    }
  ]
}

You get 200 OK even when every payment was rejected. Always inspect results rather than relying on the status code.

The reason must be valid for the derived scheme, and whether you may send additionalComment depends on it too. See the API reference for the per-scheme tables.

Cancellation Statuses

In Progress
Final States

Status	Description
`CANCELLATION_IN_PROGRESS`	Opening status - request sent, awaiting the other bank
`RETURNING`	The other bank agreed; funds not back yet

CANCELLATION_CREATED is legacy and no longer set for new requests, but older ones may still carry it.

Status	Description
`PAYMENT_RETURNED`	Funds returned - a new linked return transaction is created (success outcome)
`CANCELLATION_REFUSED`	The other bank refused to return the funds
`CANCELLATION_REJECTED`	The clearing system rejected the cancellation request itself, usually a validation error
`PROCESSING_FAILED`	Processing failed - the request needs attention

CANCELLATION_REJECTED is distinct from CANCELLATION_REFUSED: the request never reached the other bank. Fix the error and send a new request.Historical cancellation requests may also show the legacy statuses CANCELLATION_ACCEPTED and CANCELLATION_COMPLETED - these are no longer emitted for new requests.

Scheme Differences

Every scheme opens at CANCELLATION_IN_PROGRESS, but the paths from there are not the same.

	SEPA CT / Instant	SWIFT
Counterparty	Clearing system	Correspondent bank
`PROCESSING_FAILED`	Possible	Not used
Eligibility check before accepting	None	The correspondent must support recalls

REFUSING appears in the status list but belongs to inbound cancellations - it means you are refusing someone else’s request. It never occurs on a cancellation you initiated.

Track Both States

Cancellation and transaction states are independent. Monitor both via webhooks.

Cancellation Accepted

Cancellation: RETURNING → PAYMENT_RETURNEDTransaction: original stays Completed; a new linked payment return transaction credits the funds back

Cancellation Refused

Cancellation: → CANCELLATION_REFUSEDTransaction: CompletedPayment settles normally

SWIFT-Specific Conditions

A SWIFT payment that has already been sent is checked against the correspondent bank before the cancellation is accepted. Not every correspondent supports recalls, so some payments are rejected at submission with no message ever sent.

This check is a live lookup and it fails safe: a correspondent that cannot be reached at that moment is treated as not supporting cancellation. If you see this rejection for a correspondent you expect to work, retry before treating it as permanent.

Retrying

The endpoint takes no Idempotency-Key and does not need one. A payment whose cancellation is already in flight comes back REJECTED, so replaying a batch after a partial failure processes only what did not go through the first time.

Do not submit two cancellation requests for the same payment concurrently. Retry after the previous response, not alongside it.

Data Model

string

required

Original transaction reference

string

required

Cancellation request identifier

string

required

Track separately from transaction status

array

required

Append-only for audit

Integration Checklist

Inspect every result

Read results on every response. A 200 does not mean every payment was accepted

Handle cancellation webhooks

Upsert by cancellationId to track cancellation state separately from transaction state

Link cancellation to transaction

Maintain the relationship between trx_id and cancellationId in your database

Display states separately

Show cancellation progress independently from transaction status in your UI

Wait for completion

Only consider a cancellation final when the webhook indicates PAYMENT_RETURNED, CANCELLATION_REFUSED or CANCELLATION_REJECTED

What’s Next?

You now understand exception handling for outbound payments. Complete your integration with inbound exceptions and reconciliation:

Respond to Cancellations

Handle incoming cancellation requests

Return Inbound Payments

Return funds when you can’t credit the beneficiary

Track and Reconcile

Monitor transactions and reconcile with statements

Getting Started

Integration Guide

Account Management

SEPA Instant/SCT

SEPA Direct Debit

SWIFT Payments

Payment Information

Investigations (Preview)

Nostro Accounts

Bank Information

Webhooks

Cancel Outbound Payments

Cancel Payments When Plans Change

One Endpoint, Every Scheme

API Reference

Cancel Payments

Cancellation Status Webhook

Get Cancellation Request

List Cancellation Requests

How It Works

Initiate Cancellation

Cancellation Statuses

Scheme Differences

Track Both States

Cancellation Accepted

Cancellation Refused

SWIFT-Specific Conditions

Retrying

Data Model

Integration Checklist

What’s Next?

Respond to Cancellations

Return Inbound Payments

Track and Reconcile

​Cancel Payments When Plans Change

​One Endpoint, Every Scheme

​API Reference

Cancel Payments

Cancellation Status Webhook

Get Cancellation Request

List Cancellation Requests

​How It Works

​Initiate Cancellation

​Cancellation Statuses

​Scheme Differences

​Track Both States

Cancellation Accepted

Cancellation Refused

​SWIFT-Specific Conditions

​Retrying

​Data Model

​Integration Checklist

​What’s Next?

Respond to Cancellations

Return Inbound Payments

Track and Reconcile

Cancel Payments When Plans Change

One Endpoint, Every Scheme

API Reference

How It Works

Initiate Cancellation

Cancellation Statuses

Scheme Differences

Track Both States

SWIFT-Specific Conditions

Retrying

Data Model

Integration Checklist

What’s Next?