> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finventi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Respond to cancellation request
> Accepts or rejects an inbound cancellation request for a SEPA or SWIFT payment.
This API is in preview and subject to change.
## Overview
Answers a cancellation request another bank sent you. One endpoint covers both outcomes: set
`responseCode` to `ACCEPTED` to return the funds, or `REJECTED` to decline.
It is the only way to respond to a **SWIFT** cancellation request. The v1 endpoints
[Accept cancellation request](/payments/api/sepa/cancellation-request-accept) and
[Reject cancellation request](/payments/api/sepa/cancellation-request-reject) return
`405 ILLEGAL_TRANSACTION_METHOD` for SWIFT, and remain available for SEPA Direct Debit.
## Scheme coverage
| Schema | Supported |
| ----------------------- | ------------------------------------------- |
| `SEPA` (CT and Instant) | Yes |
| `SWIFT` | Yes, once enabled for your tenant |
| `SDD` | No - use the v1 accept and reject endpoints |
| `T2` | No |
An unsupported schema returns `409 UNSUPPORTED_CANCELLATION_SCHEMA`.
Inbound SWIFT cancellation is released per tenant. Until it is enabled for yours, a SWIFT
cancellation request returns `403 FEATURE_DISABLED`. Contact your integration manager to be
switched on.
## What to send in `responseDetails`
Which fields you must supply depends on the response code and the schema.
| Field | When to send it |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rejectionReasonCode` | Required for a SEPA rejection. Not used for SWIFT |
| `swiftRejectionReasonCode` | Required for a SWIFT rejection. Not used for SEPA |
| `additionalInformation` | Required for a SEPA rejection, 1-1300 characters. Optional for SWIFT and capped at 105 characters, except with reason `ARDT`, where it must be absent |
| `feeAmount` | Optional when accepting a SEPA request, in minor currency units and non-negative. Must be absent or zero for SWIFT |
A fee must be smaller than the transaction amount, and fees are not accepted for schemas that do
not support them.
### Rejecting with `ARDT`
`ARDT` says the payment was already returned, and CBPR+ requires the returned payment's UETR in
`additionalInformation` - it refuses the `camt.029` without one.
The platform supplies it. Send the reason on its own:
```json Reject with ARDT theme={null}
{
"responseCode": "REJECTED",
"responseDetails": {
"swiftRejectionReasonCode": "ARDT"
}
}
```
The UETR used is the cancelled payment's, which is the identifier the whole payment chain travels
under, the return included. Sending `additionalInformation` yourself with `ARDT` is rejected with
`400 VALIDATION_ERROR` rather than overridden, so you are never left believing you set a value that
was replaced. The same error means the payment carries no UETR to send.
Every other SWIFT reason code takes `additionalInformation` as optional free text.
## Errors
A 4xx response means the cancellation request is unchanged.
| Status | Code | Cause |
| ------ | -------------------------------------------------------- | -------------------------------------------------------------------- |
| 400 | `ILLEGAL_CANCELLATION_REQUEST_STATUS` | The request is no longer in a state that accepts a response |
| 400 | `ILLEGAL_CANCELLATION_REASON` | Rejection reason not valid for the derived schema |
| 400 | `VALIDATION_ERROR` | `additionalInformation` missing, too long, or sent where not allowed |
| 400 | `NEGATIVE_FEE_AMOUNT` | `feeAmount` is below zero |
| 400 | `FEE_AMOUNT_GREATER_THAN_OR_EQUAL_TO_TRANSACTION_AMOUNT` | `feeAmount` is not smaller than the payment amount |
| 400 | `FEE_NOT_SUPPORTED_FOR_SCHEMA` | The derived schema does not accept a fee |
| 400 | `CANCELLATION_CHANNEL_BIC_MISSING` | The response cannot be addressed - the channel BIC is absent |
| 400 | `VALID_RETURN_EXISTS` | A return already exists for the payment |
| 400 | `ILLEGAL_TRANSACTION_DIRECTION` | The payment is not inbound |
| 400 | `CANCELLATION_REQUEST_TRANSACTION_NOT_FOUND` | The request has no linked payment |
| 403 | `FEATURE_DISABLED` | Inbound SWIFT cancellation is not enabled for your tenant |
| 404 | `CANCELLATION_REQUEST_NOT_FOUND` | Unknown cancellation request id |
| 405 | `ILLEGAL_TRANSACTION_METHOD` | The payment method cannot be handled here |
| 409 | `UNSUPPORTED_CANCELLATION_SCHEMA` | Responding is not supported for this schema |
## Tracking the outcome
Accepting sends a pacs.004 return; rejecting sends a camt.029. Either way, follow the
[cancellation webhook](/payments/webhooks/payment-cancellation-status-change) for the resulting
status changes.
## OpenAPI
````yaml post /v3/cancellation-requests/{id}:respond
openapi: 3.1.0
info:
description: >
# General info
## Base API URL for environments:
* TEST: https://api.pgw-sandbox.finventi.com
* PROD: https://api.pgw.finventi.com
# Authentication
NOTE: IP whitelisting is mandatory to gain access to our APIs in both
TEST and PROD environments. To register your IPs, please contact
`connectors-support@inventi.lt`.
Our API uses OAuth 2.0 for authentication. To access the API, you need to
obtain a bearer token from the authorization server.
### Obtain a Bearer Token
To get a bearer token, use the following cURL command:
```
curl -X POST \
--location
'/realms//protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=api-sepa-gateway-client' \
--data-urlencode 'client_secret='
```
where:
`` is either `https://auth.sandbox.finventi.com/` (TEST) or
`https://auth.finventi.com/` (PROD).
`` is a value of TenantID that was assigned by INVENTI team
during initial configuration and could be found in Configuration Matrix that
was shared to your representative.
`` is a value that can be obtained by logging into SEPA
Dashboard UI and going to User Management -> Clients ->
`api-sepa-gateway-client` -> Credentials -> Client Secret.
NOTE: The token is valid for 45 minutes.
### Include the Bearer Token in Requests
Include the obtained token in the `Authorization` header of your API
requests with the `Bearer` prefix:
```
Authorization: Bearer
```
### Example Request:
```
curl --location --request POST
'https://api.pgw-sandbox.finventi.com/gateway/createSepaPmt' \
--header 'Authorization: Bearer ' \
```
# Idempotency
In our API, we support idempotency for certain endpoints to ensure that
repeated requests have the same effect as a single request.
Idempotent endpoints allow you to safely retry requests without worrying
about unintended side effects, such as duplicate resource creation or
modification. \
To achieve idempotency, you need to include the **Idempotency-Key** header
in your requests to the supported endpoints.
If the provided idempotency key corresponds to an existing database object,
the response will retrieve the data of the existing object instead of
creating a new one.
## Idempotency-Key Header
The **Idempotency-Key** header is used to uniquely identify a request and
associate it with a specific operation. While the header value can be any
string, we recommend using a UUID (Universally Unique Identifier) for
uniqueness within the scope of the endpoint. This allows you to easily
generate a unique key for each request.
### Example Request
```
curl --location --request POST
'https://api.pgw-sandbox.finventi.com/gateway/createSepaPmt' \
--header 'Idempotency-Key: 123e4567-e89b-12d3-a456-426655440000' \
```
## Supported endpoints:
* /gateway/createSepaPmt
# Webhooks
## Signature Verification
### Introduction
To ensure the authenticity and integrity of webhooks sent from our system,
each webhook includes a digital signature. This signature allows the
receiver to verify that the payload has not been altered during
transmission. Verifying the signature confirms the webhook's origin and
ensures its data integrity.
Each webhook includes the signature in the `finventi-signature-N` HTTP
header, where `N` represents the version of the signature. The current
version is `1` (`finventi-signature-1`). When public keys are rotated, new
header versions are issued, ensuring backward compatibility for clients
until their code is updated.
The signature should be verified using the RSASSA-PKCS1-v1.5 algorithm and
the appropriate public key, based on the environment.
### Environment Public Keys
Use the corresponding public key based on the environment in which you are
verifying the webhook (current version - `1`)
#### Test Environment Public Key
```text
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvoc7GrFbduCeSVxFPJ3l
a0NRa0caUqBddQAOUxuHTOuShOvdKbxRYc5u1vb9YNLJWjx4XSHESp8Q7oocqXt8
+weBFsk/kAtJ4zjbYPY1PvAOLe+WObdxxZtfwzpwVxbtP6GQk5aUi2HbITe3EDf/
7WEmvnAcWm++Mo6+GSh2Ky1t6o4htrx1lH2gYVg0iRHx1W9lLXjMl/5oLi1C6dtx
TnBmXMlN/NT5YYU4lVlXQBZzS7a8ZgwosfW+v1uCimzbGcWytmmcFISjSNqkYaeg
IXDYwKLwlsWtm975ln6UL20KcSt7ia+Lpuv7cdxJlOY95y0ds/PCw1x0HEPxU+44
swIDAQAB
-----END PUBLIC KEY-----
```
#### Production Environment Public Key
```text
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA1pTRk8oUoGAAgXE8Gni8
xvG2MJz6uYkZcNlXhPTrsxfqD4W5uDZOhy7APLz47Plcv+XL45kO0BFgjYHDRASx
IIb6K5+YVyf9p1biLdZgf047wxwuC65bT6ddhuSX9FrMEtgPvghltSSfTZjdwVck
QNE2JEV7vcIfq3ke5US+SP+6AHIcPyXypslp50CtO8wpZG+pz7rSdOoiRFTMhzVZ
efDetRcnFv6DoAdapOiNVG9MBPqnE+BT5mnAlgF6V551ZJFOMhFvm/cLtP3Gj2a9
/zNeCT1ZXHIuqxwrBUy/R8RSKJJIBWUbJEHF+pcPite+MgJm529Bt6K4mGCv1Nzv
GwIDAQAB
-----END PUBLIC KEY-----
```
### Additional Headers
Each webhook includes the following HTTP headers to assist in verifying the
signature:
* `finventi-signature-N`: Each webhook contains the signature.
* `finventi-signature-timestamp`: A UNIX timestamp (UTC) indicating when the
webhook was sent.
* `finventi-receiver-tenant-id`: The tenant ID for the webhook recipient.
These headers must be used during the signature verification process to
ensure consistency.
### Signature Verification Process
To verify the authenticity of the webhook, the following steps must be
performed:
1. Concatenate the following components in the specified order, separated by
periods (.):
* The request body
* The tenant ID from `finventi-receiver-tenant-id`
* The timestamp from `finventi-signature-timestamp`
Example:
```text
{"trx_id":10300003,"end_to_end_id":"NOTPROVIDED","type":"Payment","direction":"OUTBOUND","amount":1,"currency":"EUR","status":"Created","updated_at":"2024-09-20T13:46:32.092083Z"}.demo1.1726839992
```
2. Hash the concatenated string using the SHA-256 algorithm.
3. Base64 decode the received finventi-signature-v header to obtain the
signature.
4. Verify the signature using
[RSASSA-PKCS1-v1_5](https://datatracker.ietf.org/doc/html/rfc8017#section-8.2.2)
with the hashed data, decoded signature, and the latest public key.
### Code Example (Node.js)
```js
const crypto = require('crypto');
const signatureBase64 =
"GtZFu1uNFqOir8eDkar7+d/S+FtwQpk4mPGCuByKhJG29K1u7ynbVhkrDF8c3TqyX9wYHxpOa94FsgW2I4CnLh+B24LqL7WVSuACOL6GoSjfKeXP00NSp0ps8QYbVaJ8Ys6E4FePhp+7piAACkIP5vZ91JCLQ8lz36KRJlOnByQMTBH6j924n1GwZiZfbMojOGmMhLA0h8jWgTIeuvYPswiZXZXp0vpqJfWmdoqiU1ldoausTNFyoVwFuuzkxPv1VHvWeEeWirObUv3wNpyAnLnqomDgR7pe/9dDV0bkq5r0JkRhnbPCEFE/zzHeDgZ957hv8Oq3wJkGJarZ0NvPLw=="
const signature = Buffer.from(signatureBase64, 'base64');
const publicKey = `-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvoc7GrFbduCeSVxFPJ3l
a0NRa0caUqBddQAOUxuHTOuShOvdKbxRYc5u1vb9YNLJWjx4XSHESp8Q7oocqXt8
+weBFsk/kAtJ4zjbYPY1PvAOLe+WObdxxZtfwzpwVxbtP6GQk5aUi2HbITe3EDf/
7WEmvnAcWm++Mo6+GSh2Ky1t6o4htrx1lH2gYVg0iRHx1W9lLXjMl/5oLi1C6dtx
TnBmXMlN/NT5YYU4lVlXQBZzS7a8ZgwosfW+v1uCimzbGcWytmmcFISjSNqkYaeg
IXDYwKLwlsWtm975ln6UL20KcSt7ia+Lpuv7cdxJlOY95y0ds/PCw1x0HEPxU+44
swIDAQAB
-----END PUBLIC KEY-----`;
const body =
`{"trx_id":10300003,"end_to_end_id":"NOTPROVIDED","type":"Payment","direction":"OUTBOUND","amount":1,"currency":"EUR","status":"Created","updated_at":"2024-09-20T13:46:32.092083Z"}`;
const tenantId = "demo1"
const timestamp = "1726839992";
const dataToVerify = Buffer.from(body + '.' + tenantId + '.' + timestamp);
const isVerified = crypto.verify(
"sha256",
dataToVerify,
{
key: publicKey,
padding: crypto.constants.RSA_PKCS1_PADDING,
},
signature
);
console.log("Verification successful:", isVerified);
```
## Payment status change webhook
Payment status changes can send notifications using webhook to clients
provided HTTP POST endpoint.
Notifications are sent when payment/payment return status changes to one of
the following statuses: Created, To sign, Signed, Accepted, Completed, Some
problems, Cancelled, Rejected.
There is retry mechanism - if an endpoint fails, the notification will be
repeatedly sent until it is successfully delivered. During this retry
process, all other notifications will be held back and will only be
delivered once the initially blocked notification is successfully sent.
Request is sent in json format.
### Request Body Example:
```json
{
"trx_id": 2018845,
"end_to_end_id": "2302231660139326",
"type": "Payment",
"direction": "OUTBOUND",
"amount": 10657, (CENTS)
"currency": "EUR",
"status": "Created",
"updated_at": "2023-02-23 07:49:37.524808" (date&time when status was updated),
"debtor_iban": "LT543210010000000003",
"creditor_iban": "LT123450010000000004"
}
```
| Body parameter | Type |
|-------------------|-------|
| **trx_id** | **Integer** |
| **end_to_end_id** | **String** |
| **type** | **String** classifier.
Available values:
"Payment", "Payment return", "Payment cancellation", "CSM fees", "Reverse
payment", "Adjustment" |
| **direction** | **Enum**.
Available values: "INBOUND",
"OUTBOUND" |
| **amount** | **Integer** |
| **currency** | **String** classifier.
Available values:
"EUR" |
| **status** | **String** classifier.
Available values:
"Created", "To sign", "Signed", "Accepted", "Completed", "Some problems",
"Cancelled", "Rejected", "Pending confirmation" |
| **updated_at** | **DateTime** |
| **debtor_iban** | **String** |
| **creditor_iban** | **String** |
## Payment cancellation status change webhook
Payment cancellation status changes can send notifications using webhook to
clients provided HTTP POST endpoint.
Notifications are sent when payment cancellation status changes to one of
the following statuses: CANCELLATION_IN_PROGRESS, CANCELLATION_ACCEPTED,
CANCELLATION_REJECTED, CANCELLATION_COMPLETED.
There is retry mechanism - if an endpoint fails, the notification will be
repeatedly sent until it is successfully delivered. During this retry
process, all other notifications will be held back and will only be
delivered once the initially blocked notification is successfully sent.
Request is sent in json format.
### Request Body Example:
```json
{
"cancellationId": 102,
"trxId": "2018845",
"direction": "OUTBOUND",
"reason": "CUST",
"status": "CANCELLATION_IN_PROGRESS",
}
```
| Body parameter | Type |
|-------------------|-------|
| **cancellationId** | **Integer** |
| **trxId** | **Integer** |
| **direction** | **Enum**.
Available values: "INBOUND",
"OUTBOUND" |
| **reason** | **Enum**.
Available values: "DUPL", "CUST",
"FRAD", "TECH", "AC03", "AM09", "AGNT", "COVR", "CURR", "CUTA", "DS24",
"FRNA", "FRTR", "INDM", "SYAD", "UPAY","AC01", "AC04", "AC06", "AC13",
"AG01", "AG02", "AM01", "AM04", "AM05", "CNOR", "DNOR", "MD01", "MD02",
"MD07", "MS02", "MS03", "RC01", "RR01", "RR02", "RR04", "SL01", "BE05",
"FF01", "DT01", "ED05", "PY01" |
| **status** | **Enum**.
Available values:
"CANCELLATION_CREATED", "CANCELLATION_IN_PROGRESS", "RETURNING", "REFUSING",
"PAYMENT_RETURNED", "CANCELLATION_REFUSED", "PROCESSING_FAILED",
"CANCELLATION_COMPLETED", "CANCELLATION_REJECTED", "CANCELLATION_ACCEPTED" |
### Cancellation request processing statuses
The table below standardises how you track SEPA cancellation requests from
start to finish. Each status maps to specific inbound/outbound ISO-20022
messages, giving you clear, machine-readable checkpoints for monitoring and
automating your cancellation workflow.
| Status name | Description |
| ----------- | ---------------- |
| CANCELLATION_CREATED | Cancellation request successfully created and
validated by the Payment Gateway system. |
| CANCELLATION_IN_PROGRESS | The camt.056 payment cancellation request is
received from the clearing system and waiting for the User activities. Can
be accepted and payment will be returned or rejected. |
| RETURNING | User decides to return the funds. The pacs.004 payment return
message is sent to the initiator of the payment cancellation request. The
intermediary cancellation request status, which doesn't allow to execute any
actions until the final status of the payment return will be set. |
| REFUSING | User rejects to return the funds. The camt.029 resolution of
investigation message is sent to the initiator of the payment cancellation
request. The intermediary cancellation request status, which doesn't allow
to execute any actions until the final status of the resolution of
investigation will be set. |
| PAYMENT_RETURNED | Incoming cancellation: The pacs.004 payment return
message successfully delivered to the beneficiary bank. This is the final
processing status, which doest allow to perform any actions with the
cancellation request.
Outgoing cancellation: The payment return
pacs.004 message, following the sent cancellation request is received from
the clearing system. The transaction based on the payment return message is
successfully created in system, its data linked with the respective
cancellation request and the original outbound payment. |
| CANCELLATION_REFUSED | Incoming cancellation: The camt.029 resolution of
investigation message successfully delivered to the beneficiary bank. This
is the final processing status, which doest allow to perform any actions
with the cancellation request.
Outgoing cancellation: The resolution of
investigation camt.029 message, following the sent cancellation request is
received from the clearing system. The payment return refusal data are
indicated for the related cancellation request. |
| PROCESSING_FAILED | The state which indicates that there was an error
during processing of the response for the cancellation request message. This
state allows to reprocess the cancellation request after the errors will be
eliminated. |
| CANCELLATION_COMPLETED | Incoming cancellation: The payment return
transaction completed successfully. If failed, the status will be changed to
the CANCELLATION_IN_PROGRESS and it is possible to reprocess the
cancellation request.
Outgoing cancellation: The pacs.004 payment
return message following cancellation request is received from the clearing
system. |
| CANCELLATION_REJECTED | The payment cancellation request camt.056 message
was rejected by the clearing system due to errors. The state allows to
initiated additional cancellation request after the errors will be
eliminated. |
| CANCELLATION_ACCEPTED | The payment cancellation request camt.056 message
successfully delivered to the beneficiary bank. |
# External code sets
## Private identification codes
| Identification code | Definition |
|-------------------|-------|
| **ARNU** | **Number assigned by a social security agency to identify a non-resident person.** |
| **CCPT** | **Number assigned by an authority to identify the passport number of a person.** |
| **CUST** | **Number assigned by an issuer to identify a customer.** |
| **DRLC** | **Number assigned by an authority to identify a driver's license.** |
| **EMPL** | **Number assigned by a registration authority to an employee.** |
| **NIDN** | **Number assigned by an authority to identify the national identity number of a person.** |
| **SOSE** | **Number assigned by an authority to identify the social security number of a person.** |
| **TXID** | **Number assigned by a tax authority to identify a person.** |
## Organisation identification codes
| Identification code | Definition |
|-------------------|-------|
| **BANK** | **Unique and unambiguous assignment made by a specific bank or similar financial institution to identify a relationship as defined between the bank and its client.** |
| **CBID** | **A unique identification number assigned by a central bank to identify an organisation.** |
| **CHID** | **A unique identification number assigned by a clearing house to identify an organisation.** |
| **CINC** | **A unique identification number assigned by a designated authority to a certificate of incorporation and used to identify an organisation.** |
| **COID** | **Country authority given organisation identification (e.g., corporate registration number).** |
| **CUST** | **Number assigned by an issuer to identify a customer. Number assigned by a party to identify a creditor or debtor relationship.** |
| **DUNS** | **A unique identification number provided by Dun & Bradstreet to identify an organisation.** |
| **EMPL** | **Number assigned by a registration authority to an employer.** |
| **GS1G** | **Global Location Number. A non-significant reference number used to identify legal entities, functional entities, or physical entities according to GS1 numbering scheme rules.The number is used to retrieve detailed information that is linked to it.** |
| **SREN** | **The SIREN number is a 9 digit code assigned by INSEE, the French National Institute for Statistics and Economic Studies, to identify an organisation in France.** |
| **SRET** | **The SIRET number is a 14 digit code assigned by INSEE, the French National Institute for Statistics and Economic Studies, to identify an organisation unit in France. It consists of the SIREN number, followed by a five digit classification number, to identify the local geographical unit of that entity.** |
| **TXID** | **Number assigned by a tax authority to identify an organisation.** |
title: SEPA Payment Gateway
version: '1.0'
servers:
- description: Payment Platform sandbox environment
url: https://api.pgw-sandbox.finventi.com
security: []
tags:
- description: >-
Manage payment investigations. Supports two types: Claim Non-Receipt
(camt.027) for outbound SEPA CT payments, and Payment Status Request
(pacs.028) for outbound SEPA INST payments. Inbound investigations
received from counterparties can be searched, viewed, and resolved via
:resolve API (camt.029). A stalled SEPA CT claim non-receipt can also be
chased with a pacs.028 reminder via the :remind API; such a reminder is
excluded from search and from the per-payment list, and is returned inside
the claim it belongs to, in claimNonReceiptDetails.reminders. Fetched
directly by its own id it reads back as type PAYMENT_STATUS_REQUEST with
schema SEPA.
name: Investigations
paths:
/v3/cancellation-requests/{id}:respond:
post:
tags:
- SEPA Credit Transfer / SEPA Instant Credit Transfer
- SWIFT Payment Transfer
summary: Respond to a cancellation request
description: >
Accepts or rejects a single cancellation request received from another
bank.
The cancellation schema is derived from the payment the cancellation
request refers to rather
than declared in the request.
`responseCode=ACCEPTED` creates a payment return for the original
payment — pacs.004 for both
SEPA and SWIFT. A non-negative `feeAmount` below the payment amount may
be charged for SEPA;
SWIFT returns are always full-amount, so a non-zero fee is rejected.
`responseCode=REJECTED` answers with a negative camt.029. SEPA
rejections take
`rejectionReasonCode` plus a mandatory `additionalInformation` (1..1300
characters); SWIFT
rejections take `swiftRejectionReasonCode`, with `additionalInformation`
optional for every
reason code and capped at 105 characters.
`ARDT` is the exception: CBPR+ requires the returned payment's UETR in
`additionalInformation`
there, and the platform fills it in with the cancelled payment's UETR.
Send `additionalInformation`
with `ARDT` and the request is rejected rather than overridden.
operationId: respondToCancellationRequest
parameters:
- description: Cancellation request ID.
example: 123
in: path
name: id
required: true
schema:
format: int64
type: integer
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RespondToCancellationRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CancellationRequestResponse'
description: Cancellation request response processed
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The rejection reason is missing or not valid for the derived schema,
`additionalInformation` is missing where required, sent where not
accepted or too long, a fee was supplied for a schema that does not
support one, or the cancellation request is not in a respondable
state
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Tenant does not have an access to the resource
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Cancellation request is not found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The cancellation request refers to a payment whose schema cannot be
responded to
components:
schemas:
RespondToCancellationRequest:
properties:
responseCode:
description: >-
Response code indicating acceptance or rejection of the cancellation
request
oneOf:
- $ref: '#/components/schemas/CancellationResponseCode'
- type: 'null'
responseDetails:
$ref: '#/components/schemas/CancellationResponseDetails'
description: >-
Response details; which fields are required depends on the response
code and the payment schema
required:
- responseCode
- responseDetails
type: object
CancellationRequestResponse:
properties:
additionalComment:
description: Cancellation request additional comment.
type:
- string
- 'null'
createdAt:
description: Cancellation request creation date time (ISO-8601 format).
format: date-time
type:
- string
- 'null'
direction:
description: Cancellation request transaction direction.
enum:
- OUTBOUND
- INBOUND
type: string
externalTransactionReferenceId:
description: >-
ID of the external transaction reference from cancellation request,
if present.
format: int64
type:
- integer
- 'null'
id:
description: Cancellation request ID.
format: int64
type: integer
reason:
description: Cancellation request reason.
enum:
- DUPL
- CUST
- FRAD
- TECH
- AC03
- AM09
- AGNT
- COVR
- CURR
- CUTA
- DS24
- FRNA
- FRTR
- INDM
- SYAD
- UPAY
- NARR
- AC01
- AC04
- AC06
- AC13
- AG01
- AG02
- AM01
- AM04
- AM05
- CNOR
- DNOR
- MD01
- MD02
- MD07
- MS02
- MS03
- RC01
- RR01
- RR02
- RR03
- RR04
- SL01
- BE05
- FF01
- DT01
- ED05
- PY01
type: string
rejectionAdditionalReason:
description: Cancellation request rejection additional reason.
type:
- string
- 'null'
rejectionReason:
description: Cancellation request rejection reason.
type:
- string
- 'null'
rejectionSepaMessageId:
description: Cancellation request rejection SEPA message ID.
type:
- string
- 'null'
returnTransactionId:
description: Cancellation request return transaction ID.
format: int64
type:
- integer
- 'null'
sepaCancellationId:
description: Cancellation request original ID (cxlId).
type:
- string
- 'null'
sepaMessageId:
description: Cancellation request sepa message ID.
type: string
status:
description: Cancellation request status.
enum:
- CANCELLATION_CREATED
- CANCELLATION_IN_PROGRESS
- CANCELLATION_REFUSED
- PAYMENT_RETURNED
- PROCESSING_FAILED
- REFUSING
- RETURNING
- CANCELLATION_COMPLETED
- CANCELLATION_REJECTED
- CANCELLATION_ACCEPTED
type: string
transactionId:
description: Cancellation request transaction ID.
format: int64
type:
- integer
- 'null'
required:
- direction
- id
- reason
- sepaMessageId
- status
type: object
ErrorResponse:
description: Error response
properties:
code:
description: Code of error
type: string
data:
description: 'Error data '
oneOf:
- $ref: '#/components/schemas/ErrorResponseData'
- type: 'null'
message:
description: Error message
type:
- string
- 'null'
required:
- code
type: object
CancellationResponseCode:
description: 'Cancellation request response code: ACCEPTED or REJECTED'
enum:
- ACCEPTED
- REJECTED
type: string
CancellationResponseDetails:
properties:
additionalInformation:
description: |-
Additional description of the response.
Required for SEPA rejections (1..1300 characters). For SWIFT rejections it is optional and
capped at 105 characters, except with reason ARDT, where it must be absent: CBPR+ requires
the returned payment's UETR there and the platform fills it in.
type:
- string
- 'null'
feeAmount:
description: >-
Fee amount (minor currency units) charged for accepting the
cancellation request.
Must be non-negative. SEPA only — must be absent or zero for SWIFT cancellation requests.
minimum: 0
type:
- integer
- 'null'
rejectionReasonCode:
description: >-
camt.029 rejection reason for SEPA cancellation requests. Required
when responseCode=REJECTED and the payment schema is SEPA.
oneOf:
- $ref: '#/components/schemas/CancellationRejectReason'
- type: 'null'
swiftRejectionReasonCode:
description: >-
camt.029 rejection reason for SWIFT cancellation requests. Required
when responseCode=REJECTED and the payment schema is SWIFT.
oneOf:
- $ref: '#/components/schemas/CancellationStatusReasonCode'
- type: 'null'
type: object
ErrorResponseData:
description: Error wrapper containing all occurred errors
properties:
errors:
description: All occurred errors
items:
$ref: '#/components/schemas/ErrorResponseViolation'
type: array
message:
description: Generic message for occurred errors
type:
- string
- 'null'
required:
- errors
type: object
CancellationRejectReason:
enum:
- AC04
- AM04
- ARDT
- CUST
- LEGL
- NOAS
- NOOR
type: string
CancellationStatusReasonCode:
enum:
- NOOR
- NOAS
- ARDT
- CUST
- AGNT
- LEGL
- AC04
- AM04
- RQDA
- INDM
type: string
ErrorResponseViolation:
description: Single error wrapper
properties:
code:
description: Error code
type:
- string
- 'null'
field_name:
description: Field name which failed
type: string
message:
description: Error message
type:
- string
- 'null'
value:
description: Value which was invalid
type:
- string
- 'null'
type: object
````