> ## 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.
# Review inbound SWIFT payment
> Completes or returns an inbound SWIFT payment held for manual review.
## Overview
Use this endpoint to resolve an inbound SWIFT payment held for manual review.
The payment must be in `Accepted` status with the `pending_review` status reason. Manual review must be enabled for inbound SWIFT payments on your tenant.
## Review actions
* `COMPLETE` completes the original payment. The `200` response contains the original payment in `Completed` status.
* `RETURN` completes the original payment and creates an outbound return. The `200` response contains the newly created Payment return transaction.
## Returning the payment
When `action` is `RETURN`, provide a `returnReason`. The supported SWIFT return reasons are:
* `AC01`
* `AC04`
* `AC06`
* `AG01`
* `BE04`
* `BE08`
* `CUST`
* `DUPL`
* `FRAD`
* `MD07`
* `NARR`
* `RR04`
You can use `additionalInfo` to provide free-text return reason information, up to 105 characters.
* When `returnReason` is `NARR`, `additionalInfo` is required and must not be blank.
* For every other supported reason, `additionalInfo` is optional.
## Completing the payment
When `action` is `COMPLETE`, omit both `returnReason` and `additionalInfo`.
## OpenAPI
````yaml post /v3/payments/{id}/review-action
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).
name: Investigations
paths:
/v3/payments/{id}/review-action:
post:
tags:
- Payments Information
summary: Resolve an inbound payment held for review
description: >-
Mark an accepted inbound payment as completed, or return it. Returns the
resulting payment.
operationId: reviewAction
parameters:
- in: path
name: id
required: true
schema:
format: int64
type: integer
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ReviewActionRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetPaymentV3Response'
description: Review action processed; resulting payment returned
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Bad request
'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: Payment not found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Payment already has a return which is not rejected
components:
schemas:
ReviewActionRequest:
properties:
action:
enum:
- COMPLETE
- RETURN
type: string
additionalInfo:
description: >-
SWIFT return reason details. Required for NARR and optional for
every other return reason.
maxLength: 105
minLength: 0
type: string
isAdditionalInfoValid:
type: boolean
isReturnReasonValid:
type: boolean
returnReason:
description: >-
Return reason code. Required when action is RETURN, must be absent
when action is COMPLETE.
enum:
- AC01
- AC04
- AC06
- AG01
- BE04
- BE08
- DUPL
- MD07
- CUST
- RR04
- FRAD
- NARR
example: AC01
type: string
required:
- action
- isAdditionalInfoValid
- isReturnReasonValid
type: object
GetPaymentV3Response:
properties:
categoryPurposeCode:
description: Category purpose code (e.g. SALA, TAXS, GOVT)
enum:
- BONU
- CASH
- CBLK
- CCRD
- CORT
- DCRD
- DIVI
- DVPM
- EPAY
- FCIN
- FCOL
- GOVT
- HEDG
- ICCP
- IDCP
- INTC
- INTE
- LOAN
- MP2B
- MP2P
- OTHR
- PENS
- RPRE
- RRCT
- RVPM
- SALA
- SECU
- SSBE
- SUPP
- TAXS
- TRAD
- TREA
- VATX
- WHLD
type: string
chargesAndAdjustments:
$ref: '#/components/schemas/ChargesAndAdjustments'
description: >-
Return-only charges and adjustments. Populated only for
payment_return / payment_cancellation transactions; absent
otherwise.
createdAt:
description: Time and date when the payment was created (UTC)
example: '2025-11-21T12:46:54.321667Z'
format: date-time
type: string
creditor:
$ref: '#/components/schemas/Party'
description: Creditor (recipient) party information
debtor:
$ref: '#/components/schemas/Party'
description: Debtor (sender) party information
directDebit:
$ref: '#/components/schemas/DirectDebit'
description: SEPA direct debit fields, present only for SDD payments
direction:
description: Payment direction
enum:
- OUTBOUND
- INBOUND
example: OUTBOUND
type: string
endToEndId:
description: End-to-end identifier assigned by the originator
type: string
id:
description: Unique payment identifier
example: 10300007
format: int64
type: integer
instructedAmount:
description: Instructed payment amount in minor currency units (cents)
example: 100
type: integer
instructedCurrency:
description: Instructed payment currency ISO code
example: EUR
type: string
instructionId:
description: Instruction identifier
type: string
messageId:
description: Message identifier
type: string
metadata:
description: Client-defined metadata values assigned when the payment was created
items:
type: string
type: array
originBic:
description: Return / rejection originator BIC
type: string
originName:
description: Return / rejection originator name
type: string
originReasonCode:
description: Return / rejection reason code
example: AC04
type: string
originReasonInfo:
description: Return / rejection reason information
type: string
parentPaymentId:
description: >-
Parent payment identifier, present for returns / reversals /
cancellations
format: int64
type: integer
parentTransactionAmount:
description: Original (parent) transaction amount in minor currency units (cents)
type: integer
purpose:
description: Unstructured remittance information (free text)
example: 'Invoice #12345'
type: string
purposeCode:
description: ISO 20022 purpose code (e.g. SUPP, SALA, TAXS)
type: string
scheme:
description: >-
Payment scheme. `SEPA_CT` — SEPA Credit Transfer, `SEPA_INST` — SEPA
Instant Credit Transfer, `SEPA_DD` — SEPA Direct Debit, `SWIFT` —
SWIFT cross-border payment.
enum:
- SEPA_CT
- SEPA_INST
- SEPA_DD
- SWIFT
- T2
example: SEPA_CT
type: string
settlementAmount:
description: Settlement amount in minor currency units (cents)
example: 100
type: integer
settlementCurrency:
description: Settlement currency ISO code
example: EUR
type: string
settlementDate:
description: Settlement date
format: date
type: string
status:
description: Current payment status
enum:
- CREATED
- TO_SIGN
- SIGNED
- SENT_TO_CLEAR
- COMPLETED
- CANCELLED
- REJECTED
- ACCEPTED
- SOME_PROBLEMS
- PENDING_CONFIRMATION
example: COMPLETED
type: string
statusReason:
$ref: '#/components/schemas/StatusReason'
description: Reason for the current status
structuredReference:
$ref: '#/components/schemas/StructuredReference'
description: Structured remittance reference
swift:
$ref: '#/components/schemas/Swift'
description: SWIFT-specific fields, present only for SWIFT payments
t2:
$ref: '#/components/schemas/T2'
description: T2-specific fields, present only for T2 payments
type:
description: Payment type
enum:
- PAYMENT
- PAYMENT_CANCELLATION
- PAYMENT_RETURN
- REVERSE_PAYMENT
- CSM_FEES
- ADJUSTMENT
example: PAYMENT
type: string
ultimateCreditor:
$ref: '#/components/schemas/UltimateParty'
description: Ultimate creditor party information
ultimateDebtor:
$ref: '#/components/schemas/UltimateParty'
description: Ultimate debtor party information
updatedAt:
description: Time and date when the payment was last updated (UTC)
example: '2025-11-21T12:46:54.612954Z'
format: date-time
type: string
required:
- createdAt
- creditor
- debtor
- direction
- endToEndId
- id
- instructedAmount
- instructedCurrency
- metadata
- scheme
- settlementAmount
- settlementCurrency
- status
- type
type: object
ErrorResponse:
description: Error response
properties:
code:
description: Code of error
type: string
data:
$ref: '#/components/schemas/ErrorResponseData'
description: 'Error data '
message:
description: Error message
type: string
required:
- code
type: object
ChargesAndAdjustments:
properties:
compensation:
description: Compensation amount in minor currency units (cents)
example: 25
type: integer
returnCharges:
description: Return charges amount in minor currency units (cents)
example: 50
type: integer
unaccountedTax:
description: Unaccounted tax amount in minor currency units (cents)
type: integer
type: object
Party:
properties:
account:
$ref: '#/components/schemas/Account'
description: Party account — either iban or other (mutually exclusive)
address:
$ref: '#/components/schemas/Address'
description: Party postal address
agent:
$ref: '#/components/schemas/Agent'
description: Party agent (bank / EMI / payment institution)
name:
description: Party name
type: string
organisationIdentification:
$ref: '#/components/schemas/OrganisationIdentification'
description: >-
Organisation identification (mutually exclusive with
privateIdentification)
privateIdentification:
$ref: '#/components/schemas/PrivateIdentification'
description: >-
Private identification (mutually exclusive with
organisationIdentification)
required:
- account
- agent
type: object
DirectDebit:
properties:
amendmentIndicator:
description: Indicates whether the mandate has been amended
type: boolean
amendmentInformationDetails:
$ref: '#/components/schemas/MandateAmendmentDetails'
description: Mandate amendment details, present when amendmentIndicator is true
eSignature:
type: string
writeOnly: true
esignature:
type: string
mandateId:
description: Mandate identifier
example: MANDATE-2026-001
type: string
sequenceType:
description: Mandate sequence type
enum:
- FRST
- RCUR
- FNAL
- OOFF
example: RCUR
type: string
signatureDate:
description: Mandate signature date
example: '2026-01-15'
format: date
type: string
type: object
StatusReason:
properties:
code:
description: Status reason code
example: ACSC
type: string
message:
description: Status reason message
example: Accepted settlement completed
type: string
type: object
StructuredReference:
properties:
issuer:
description: Reference issuer
example: ISO
type: string
reference:
description: Reference code
example: RF123456
type: string
type: object
Swift:
properties:
businessMessageId:
description: Business message identifier
example: BIZ-MSG-001
type: string
charges:
$ref: '#/components/schemas/SwiftCharges'
description: Charges information
messageDefinition:
description: Message definition identifier
example: pacs.008.001.08
type: string
receiverBic:
description: Receiver BIC
type: string
senderBic:
description: Sender BIC
type: string
settlementAccount:
$ref: '#/components/schemas/SettlementAccount'
description: Settlement account (SttlmAcct) — IBAN or other identification
settlementMethod:
description: Settlement method (INDA, INGA, COVE)
enum:
- INDA
- INGA
- COVE
type: string
uetr:
description: Universally unique end-to-end transaction reference
type: string
type: object
T2:
properties:
uetr:
description: >-
UETR of the payment. For payment returns, contains the UETR of the
original payment being returned.
example: a1b2c3d4-1111-4222-8333-000000000001
type: string
type: object
UltimateParty:
properties:
name:
description: Ultimate party name
type: string
organisationIdentification:
$ref: '#/components/schemas/OrganisationIdentification'
description: >-
Organisation identification (mutually exclusive with
privateIdentification)
privateIdentification:
$ref: '#/components/schemas/PrivateIdentification'
description: >-
Private identification (mutually exclusive with
organisationIdentification)
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
required:
- errors
type: object
Account:
properties:
iban:
description: International Bank Account Number
type: string
other:
$ref: '#/components/schemas/OtherAccount'
description: Non-IBAN account identification
type: object
Address:
properties:
country:
description: Country ISO code
example: LT
type: string
line:
description: Unstructured address line — present when structured is absent
type: string
structured:
$ref: '#/components/schemas/StructuredAddress'
description: Structured address — present when line is absent
town:
description: Town / city name
example: Vilnius
type: string
type: object
Agent:
properties:
bic:
description: Bank Identifier Code (BIC)
example: DEMOLT1XXXX
type: string
name:
description: Agent name
type: string
type: object
OrganisationIdentification:
properties:
bic:
description: BIC code
type: string
lei:
description: Legal Entity Identifier
type: string
otherIdentification:
$ref: '#/components/schemas/OtherIdentification'
description: Other identification
type: object
PrivateIdentification:
properties:
birthInformation:
$ref: '#/components/schemas/BirthInformation'
description: Birth information
otherIdentification:
$ref: '#/components/schemas/OtherIdentification'
description: Other identification (e.g. national ID)
type: object
MandateAmendmentDetails:
properties:
originalCreditorSchemeId:
description: Original creditor scheme identifier
type: string
originalDebtorAccount:
description: Original debtor IBAN
type: string
originalMandateId:
description: Original mandate identifier
type: string
type: object
SwiftCharges:
properties:
bearer:
description: Charge bearer (SHAR, DEBT, CRED, SLEV)
enum:
- CRED
- DEBT
- SHAR
- SLEV
example: SHAR
type: string
items:
description: Charge items
items:
$ref: '#/components/schemas/SwiftChargeItem'
type: array
required:
- items
type: object
SettlementAccount:
properties:
currency:
description: Settlement account currency ISO code
example: EUR
type: string
iban:
description: Settlement account IBAN — mutually exclusive with other
type: string
other:
$ref: '#/components/schemas/OtherAccount'
description: >-
Non-IBAN settlement account identification — mutually exclusive with
iban
type: object
ErrorResponseViolation:
description: Single error wrapper
properties:
code:
description: Error code
type: string
field_name:
description: Field name which failed
type: string
message:
description: Error message
type: string
value:
description: Value which was invalid
type: string
type: object
OtherAccount:
properties:
id:
description: Account identifier
type: string
issuer:
description: Account issuer
type: string
scheme:
$ref: '#/components/schemas/Scheme'
description: Account scheme
type: object
StructuredAddress:
properties:
buildingName:
description: Building name
type: string
buildingNumber:
description: Building number
type: string
countrySubDivision:
description: Country sub-division
type: string
department:
description: Department
type: string
districtName:
description: District name
type: string
floor:
description: Floor
type: string
postBox:
description: Post box
type: string
postCode:
description: Post code
type: string
room:
description: Room
type: string
street:
description: Street name
type: string
subDepartment:
description: Sub-department
type: string
townLocationName:
description: Town location name
type: string
type: object
OtherIdentification:
properties:
id:
description: Identifier value
type: string
issuer:
description: Identifier issuer
type: string
scheme:
$ref: '#/components/schemas/Scheme'
description: Identification scheme
type: object
BirthInformation:
properties:
city:
description: City of birth
type: string
country:
description: Country of birth
type: string
date:
description: Date of birth
type: string
province:
description: Province of birth
type: string
type: object
SwiftChargeItem:
properties:
amount:
description: Charge amount in minor currency units (cents)
example: 50
type: integer
bic:
description: Charging agent BIC
type: string
currency:
description: Charge currency ISO code
example: EUR
type: string
required:
- amount
- currency
type: object
Scheme:
properties:
code:
description: Scheme code from external code sets
type: string
proprietary:
description: Proprietary scheme
type: string
type: object
````