> ## 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.
# Create SEPA Direct Debit payment
> Creates a SEPA Direct Debit payment and submits it to the clearing system.
## Overview
This endpoint creates SEPA Direct Debit payments for collecting funds from customer accounts. The payment is validated and submitted to the clearing system for processing.
## Settlement Date
The `settlementDate` is the exact day the debtor is charged - the collection settles on that day. You choose it when creating the payment.
You choose settlement date when creating the payment, and collection cannot be the same day you submit the request. It must be at least the next business day (Submissions accepted up to 11:30AM EEST if settlement day is set for tomorrow) and no more than 14 calendar days ahead.
## Mandate
`mandateInformation` carries the reference data for the direct-debit mandate agreed between the creditor and the debtor. **Holding a valid mandate is the creditor's responsibility** - Inventi does not verify it.
## Creditor Identifier
`creditor.id` carries the SEPA Creditor Identifier (CI) - the scheme-wide identifier of the party collecting the funds. Together with the mandate reference (`mandateInformation.id`) it uniquely identifies the mandate: the debtor's bank uses this pair to match every collection against the signed mandate, so both values must match the mandate exactly. Collections with an incorrect CI are returned with reason code `BE05` (originator not identified) or `MD01` (no valid mandate).
A creditor obtains the CI once, before signing the first mandate, and keeps it permanently - it stays the same even if the creditor later starts collecting through a different payment service provider.
For creditors registered in Lithuania, the CI is issued by the creditor's payment service provider and is constructed from the creditor's existing registration data:
| Positions | Content |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1-2 | ISO country code (`LT`) |
| 3-4 | Check digits, calculated according to ISO 7064 Mod 97-10 (the same algorithm as for an IBAN) |
| 5-7 | Creditor Business Code - freely chosen by the creditor to distinguish business lines, `ZZZ` if not used |
| 8-16 | Legal entities: the 9-digit legal entity code issued by the State Enterprise Centre of Registers. Private persons: `P` followed by a number assigned by the creditor's payment service provider |
Example: `LT11ZZZ123456789`
Creditors registered in other SEPA countries receive their CI under their own national rules - in some countries it is issued by the national bank or a business registry rather than the creditor's payment service provider. See the EPC [Creditor Identifier Overview](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/creditor-identifier-overview) for the country-by-country issuance process and format.
## OpenAPI
````yaml post /v1/createSepaDDPayment
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:
/v1/createSepaDDPayment:
post:
tags:
- SEPA Direct Debit
summary: Create payment
description: Creates Sepa Direct Debit payment and sends it to CSM.
operationId: createSepaDDPaymentRequest
parameters:
- description: >-
Unique identifier in scope of payment creation endpoints required to
prevent unintended duplicate direct debit payments
in: header
name: Idempotency-Key
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSepaDirectDebitPaymentRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSepaDirectDebitPaymentResponse'
description: A new SEPA direct debit payment has been created
'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
components:
schemas:
CreateSepaDirectDebitPaymentRequest:
properties:
amount:
description: Amount in minor currency units
type: integer
creditor:
$ref: '#/components/schemas/CreditorRequest'
description: Party on the credit side of the transaction to which the tax applies
currencyIsoCode:
description: For SEPA Direct Debit payments, only allowed value is 'EUR'
type: string
debtor:
$ref: '#/components/schemas/DebtorRequest'
description: Party that owes an amount of money to the (ultimate) creditor
endToEndId:
description: >-
Unique identification, as assigned by the initiating party, to
unambiguously identify the transaction. \
This identification is passed on, unchanged, throughout the entire end-to-end chain
maxLength: 35
minLength: 1
type: string
mandateInformation:
$ref: '#/components/schemas/MandateInformationRequest'
description: >-
Provides further details of the direct debit mandate signed between
the creditor and the debtor.
purpose:
$ref: '#/components/schemas/PurposeRequest'
description: >-
Underlying reason for the payment transaction. Usage: Purpose is
used by the end-customers, that is initiating
party, (ultimate) debtor, (ultimate) creditor to provide information concerning the nature of the payment. Purpose
is a content element, which is not used for processing by any of the agents involved in the payment chain.
sequenceType:
description: >-
Identifies the direct debit sequence, such as first, recurrent,
final or one-off.
enum:
- FRST
- RCUR
- FNAL
- OOFF
type: string
settlementDate:
description: >-
Date on which the amount of money ceases to be available to the
agent that owes it and when the amount of money \
becomes available to the agent to which it is due.
format: date
type: string
ultimateCreditor:
$ref: '#/components/schemas/UltimatePartyRequest'
description: Ultimate party to which an amount of money is due.
ultimateDebtor:
$ref: '#/components/schemas/UltimatePartyRequest'
description: >-
Ultimate party that owes an amount of money to the (ultimate)
creditor, in this case, to the taxing authority.
required:
- amount
- creditor
- currencyIsoCode
- debtor
- mandateInformation
- sequenceType
- settlementDate
type: object
CreateSepaDirectDebitPaymentResponse:
properties:
result:
$ref: '#/components/schemas/CreateSepaDirectDebitPaymentResult'
description: Result of sepa direct debit payment request creation
required:
- result
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
CreditorRequest:
properties:
address:
$ref: '#/components/schemas/PostalAddressRequest'
description: >-
Information that locates and identifies a specific address, as
defined by postal services.
iban:
description: Creditor (Recipient) Account (IBAN)
minLength: 1
type: string
id:
description: >-
Identification is used to identify either an organisation or a
private person.
type: string
name:
description: Creditor (Recipient) Name
maxLength: 70
minLength: 1
type: string
required:
- iban
- id
- name
type: object
DebtorRequest:
properties:
address:
$ref: '#/components/schemas/PostalAddressRequest'
description: >-
Information that locates and identifies a specific address, as
defined by postal services.
bic:
description: |-
Business identification code of the organisation - BIC. \
If not provided, system will try to resolve it automatically, in cases where system failed to find BIC automatically and there was no BIC provided error will be thrown
type: string
iban:
description: >-
International Bank Account Number (IBAN) - identifier used
internationally by financial institutions to uniquely identify the
account of a customer
minLength: 1
type: string
name:
description: >-
Name by which a party is known and which is usually used to identify
that party
maxLength: 70
minLength: 1
type: string
organisationIdentification:
$ref: '#/components/schemas/OrganisationIdentificationRequest'
description: Unique and unambiguous way to identify an organisation.
privateIdentification:
$ref: '#/components/schemas/PrivateIdentificationRequest'
description: >-
Unique and unambiguous identification of a person, for example a
passport number.
required:
- iban
- name
type: object
MandateInformationRequest:
properties:
amendmentInformation:
$ref: '#/components/schemas/AmendmentInformationRequest'
description: Mandate elements that have been modified.
dateOfSignature:
description: >-
Date on which the direct debit mandate has been signed by the
debtor.
format: date
type: string
eSignature:
description: >-
Additional security provisions, such as a digital signature, as
provided by the debtor.
maxLength: 1025
minLength: 1
type: string
id:
description: >-
Unique identification, as assigned by the creditor, to unambiguously
identify the mandate.
maxLength: 35
minLength: 1
type: string
required:
- dateOfSignature
- id
type: object
PurposeRequest:
properties:
information:
description: >-
Underlying reason for the payment transaction, as published in an
external purpose code list.
maxLength: 4
minLength: 1
type: string
structured:
$ref: '#/components/schemas/StructuredPurposeRequest'
description: >-
Information supplied to enable the matching/reconciliation of an
entry with the items that the payment is intended to settle, such as
commercial invoices in an accounts' receivable system, in a
structured form.
unstructured:
description: >-
Information supplied to enable the matching/reconciliation of an
entry with the items that the payment is intended to settle, such as
commercial invoices in an accounts' receivable system, in an
unstructured form.
maxLength: 140
minLength: 1
type: string
type: object
UltimatePartyRequest:
properties:
name:
description: Ultimate party Name
maxLength: 70
minLength: 1
type: string
organisationIdentification:
$ref: '#/components/schemas/OrganisationIdentificationRequest'
description: Unique and unambiguous way to identify an organisation.
privateIdentification:
$ref: '#/components/schemas/PrivateIdentificationRequest'
description: >-
Unique and unambiguous identification of a person, for example a
passport number.
type: object
CreateSepaDirectDebitPaymentResult:
properties:
amount:
description: Amount in minor currency units
type: integer
creditor:
$ref: '#/components/schemas/CreditorResult'
description: Party on the credit side of the transaction to which the tax applies
currencyIsoCode:
description: For SEPA Direct Debit payments, only allowed value is 'EUR'
type: string
debtor:
$ref: '#/components/schemas/DebtorResult'
description: Party that owes an amount of money to the (ultimate) creditor
endToEndId:
description: >-
Unique identification, as assigned by the initiating party, to
unambiguously identify the transaction.
This identification is passed on, unchanged, throughout the entire end-to-end chain
type: string
id:
description: Transaction ID
format: int64
type: integer
mandateInformation:
$ref: '#/components/schemas/MandateInformationResult'
description: >-
Provides further details of the direct debit mandate signed between
the creditor and the debtor.
purpose:
$ref: '#/components/schemas/PurposeResult'
description: >-
Underlying reason for the payment transaction. Usage: Purpose is
used by the end-customers, that is initiating
party, (ultimate) debtor, (ultimate) creditor to provide information concerning the nature of the payment. Purpose
is a content element, which is not used for processing by any of the agents involved in the payment chain.
sequenceType:
description: >-
Identifies the direct debit sequence, such as first, recurrent,
final or one-off.
type: string
settlementDate:
description: >-
Date on which the amount of money ceases to be available to the
agent that owes it and when the amount of money
becomes available to the agent to which it is due.
format: date
type: string
ultimateCreditor:
$ref: '#/components/schemas/UltimateCreditorResult'
description: Ultimate party to which an amount of money is due.
ultimateDebtor:
$ref: '#/components/schemas/UltimateDebtorResult'
description: >-
Ultimate party that owes an amount of money to the (ultimate)
creditor, in this case, to the taxing authority.
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
PostalAddressRequest:
properties:
addressLine:
description: >-
Additional address information. Field can be used along with country
field, no other field is permitted to be
used in combination with this particular field.
maxLength: 70
minLength: 1
type: string
buildingName:
description: Name of the building or house.
maxLength: 35
minLength: 1
type: string
buildingNumber:
description: Number that identifies the position of a building on a street.
maxLength: 16
minLength: 1
type: string
country:
description: 2 characters ISO code of country
maxLength: 2
minLength: 2
type: string
countrySubDivision:
description: Identifies a subdivision of a country such as state, region, county.
maxLength: 35
minLength: 1
type: string
department:
description: Identification of a division of a large organisation or building.
maxLength: 70
minLength: 1
type: string
districtName:
description: Identifies a subdivision within a country sub-division.
maxLength: 35
minLength: 1
type: string
floor:
description: Floor or storey within a building.
maxLength: 70
minLength: 1
type: string
postBox:
description: >-
Numbered box in a post office, assigned to a person or organisation,
where letters are kept until called for.
maxLength: 16
minLength: 1
type: string
postCode:
description: >-
Identifier consisting of a group of letters and/or numbers that is
added to a postal address to assist the sorting of mail.
maxLength: 16
minLength: 1
type: string
room:
description: Building room number.
maxLength: 35
minLength: 1
type: string
streetName:
description: Name of a street or thoroughfare.
maxLength: 70
minLength: 1
type: string
subDepartment:
description: >-
Identification of a sub-division of a large organisation or
building.
maxLength: 70
minLength: 1
type: string
townLocationName:
description: Specific location name within the town.
maxLength: 35
minLength: 1
type: string
townName:
description: >-
Name of a built-up area, with defined boundaries, and a local
government.
maxLength: 35
minLength: 1
type: string
type: object
OrganisationIdentificationRequest:
description: Organisation identification
properties:
bic:
description: Business identification code of the organisation.
type: string
lei:
description: >-
Legal entity identification as an alternate identification for a
party.
type: string
otherIdentification:
$ref: '#/components/schemas/OrganisationOtherIdentificationRequest'
description: >-
Unique identification of an organisation, as assigned by an
institution, using an identification scheme.
type: object
PrivateIdentificationRequest:
description: Private (person) identification
properties:
birthInformation:
$ref: '#/components/schemas/BirthInformationRequest'
description: Date and place of birth of a person.
otherIdentification:
$ref: '#/components/schemas/PrivateOtherIdentificationRequest'
description: >-
Unique identification of a person, as assigned by an institution,
using an identification scheme.
type: object
AmendmentInformationRequest:
properties:
creditorCode:
description: Unique and unambiguous identification of a person.
maxLength: 35
minLength: 1
type: string
debtorIban:
description: Debtor iban
maxLength: 34
minLength: 3
type: string
originalMandateId:
description: >-
Unique identification, as assigned by the creditor, to unambiguously
identify the original mandate.
maxLength: 35
minLength: 1
type: string
required:
- creditorCode
type: object
StructuredPurposeRequest:
properties:
issuer:
description: Entity that assigns the credit reference type.
maxLength: 35
minLength: 1
type: string
reference:
description: >-
Unique reference, as assigned by the creditor, to unambiguously
refer to the payment transaction.
Usage: If available, the initiating party should provide this reference in the structured remittance
information, to enable reconciliation by the creditor upon receipt of the amount of money. If the business
context requires the use of a creditor reference or a payment remit identification, and only one identifier can
be passed through the end-to-end chain, the creditor's reference or payment remittance identification should be
quoted in the end-to-end transaction identification.
maxLength: 35
minLength: 1
type: string
type: object
CreditorResult:
properties:
address:
$ref: '#/components/schemas/PostalAddressResult'
description: >-
Information that locates and identifies a specific address, as
defined by postal services.
bankName:
description: Creditor bank name
type: string
bic:
description: Business identification code of the organisation - BIC
type: string
iban:
description: Creditor (Recipient) Account (IBAN)
type: string
id:
description: >-
Private Identification is used to identify either an organisation or
a private person.
type: string
name:
description: Creditor (Recipient) Name
type: string
required:
- id
type: object
DebtorResult:
properties:
address:
$ref: '#/components/schemas/PostalAddressResult'
description: >-
Information that locates and identifies a specific address, as
defined by postal services.
bankName:
description: Debtor bank name
type: string
bic:
description: Business identification code of the organisation - BIC
type: string
iban:
description: >-
International Bank Account Number (IBAN) - identifier used
internationally by financial institutions to uniquely identify the
account of a customer
type: string
name:
description: >-
Name by which a party is known and which is usually used to identify
that party
type: string
organisationIdentification:
$ref: '#/components/schemas/OrganisationIdentificationResult'
description: Unique and unambiguous way to identify an organisation.
privateIdentification:
$ref: '#/components/schemas/PrivateIdentificationResult'
description: >-
Unique and unambiguous identification of a person, for example a
passport number.
required:
- iban
type: object
MandateInformationResult:
properties:
amendmentInformation:
$ref: '#/components/schemas/AmendmentInformationResult'
description: Mandate elements that have been modified.
dateOfSignature:
description: >-
Date on which the direct debit mandate has been signed by the
debtor.
format: date
type: string
eSignature:
description: >-
Additional security provisions, such as a digital signature, as
provided by the debtor.
type: string
id:
description: >-
Unique identification, as assigned by the creditor, to unambiguously
identify the mandate.
type: string
type: object
PurposeResult:
properties:
information:
description: >-
Underlying reason for the payment transaction, as published in an
external purpose code list.
type: string
structured:
$ref: '#/components/schemas/StructuredResult'
description: >-
Information supplied to enable the matching/reconciliation of an
entry with the items that the payment is intended to settle, such as
commercial invoices in an accounts' receivable system, in a
structured form.
unstructured:
description: >-
Information supplied to enable the matching/reconciliation of an
entry with the items that the payment is intended to settle, such as
commercial invoices in an accounts' receivable system, in an
unstructured form.
type: string
type: object
UltimateCreditorResult:
properties:
name:
description: Ultimate Creditor Name
type: string
organisationIdentification:
$ref: '#/components/schemas/OrganisationIdentificationResult'
description: Unique and unambiguous way to identify an organisation.
privateIdentification:
$ref: '#/components/schemas/PrivateIdentificationResult'
description: >-
Unique and unambiguous identification of a person, for example a
passport number.
type: object
UltimateDebtorResult:
properties:
name:
description: Ultimate Debtor Name
type: string
organisationIdentification:
$ref: '#/components/schemas/OrganisationIdentificationResult'
description: Unique and unambiguous way to identify an organisation.
privateIdentification:
$ref: '#/components/schemas/PrivateIdentificationResult'
description: >-
Unique and unambiguous identification of a person, for example a
passport number.
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
OrganisationOtherIdentificationRequest:
description: Other identification scheme for organisation
properties:
id:
description: Unique and unambiguous identification.
maxLength: 35
minLength: 1
type: string
issuer:
description: Entity that assigns the identification.
maxLength: 35
minLength: 1
type: string
scheme:
$ref: '#/components/schemas/OrganisationSchemeRequest'
description: Name of the identification scheme.
required:
- id
- scheme
type: object
BirthInformationRequest:
description: Date and place of birth information
properties:
city:
description: City where a person was born.
maxLength: 35
minLength: 1
type: string
country:
description: Country where a person was born (ISO 3166-1 alpha-2).
type: string
date:
description: Date on which a person is born.
format: date
type: string
province:
description: Province where a person was born.
maxLength: 35
minLength: 1
type: string
required:
- city
- country
- date
type: object
PrivateOtherIdentificationRequest:
description: Other identification scheme for private person
properties:
id:
description: Unique and unambiguous identification.
maxLength: 35
minLength: 1
type: string
issuer:
description: Entity that assigns the identification.
maxLength: 35
minLength: 1
type: string
scheme:
$ref: '#/components/schemas/PrivateSchemeRequest'
description: Name of the identification scheme.
required:
- id
- scheme
type: object
PostalAddressResult:
properties:
addressLine:
description: Additional address information
type: string
buildingName:
description: Name of the building or house.
type: string
buildingNumber:
description: Number that identifies the position of a building on a street.
type: string
country:
description: 2 characters ISO code of country
type: string
countrySubDivision:
description: Identifies a subdivision of a country such as state, region, county.
type: string
department:
description: Identification of a division of a large organisation or building.
type: string
districtName:
description: Identifies a subdivision within a country sub-division.
type: string
floor:
description: Floor or storey within a building.
type: string
postBox:
description: >-
Numbered box in a post office, assigned to a person or organisation,
where letters are kept until called for.
type: string
postCode:
description: >-
Identifier consisting of a group of letters and/or numbers that is
added to a postal address to assist the sorting of mail.
type: string
room:
description: Building room number.
type: string
streetName:
description: Name of a street or thoroughfare.
type: string
subDepartment:
description: >-
Identification of a sub-division of a large organisation or
building.
type: string
townLocationName:
description: Specific location name within the town.
type: string
townName:
description: >-
Name of a built-up area, with defined boundaries, and a local
government.
type: string
type: object
OrganisationIdentificationResult:
properties:
bic:
description: Business identification code of the organisation.
type: string
lei:
description: >-
Legal entity identification as an alternate identification for a
party.
type: string
otherIdentification:
$ref: '#/components/schemas/OtherIdentificationResult'
description: >-
Unique identification of an organisation, as assigned by an
institution, using an identification scheme.
type: object
PrivateIdentificationResult:
properties:
birthInformation:
$ref: '#/components/schemas/BirthInformationResult'
description: Date and place of birth of a person.
otherIdentification:
$ref: '#/components/schemas/OtherIdentificationResult'
description: >-
Unique identification of a person, as assigned by an institution,
using an identification scheme.
type: object
AmendmentInformationResult:
properties:
creditorCode:
description: Unique and unambiguous identification of a person.
type: string
debtorIban:
description: Debtor iban
type: string
originalMandateId:
description: >-
Unique identification, as assigned by the creditor, to unambiguously
identify the original mandate.
type: string
type: object
StructuredResult:
properties:
issuer:
description: Entity that assigns the credit reference type.
type: string
reference:
description: >-
Unique reference, as assigned by the creditor, to unambiguously
refer to the payment transaction.
Usage: If available, the initiating party should provide this reference in the structured remittance
information, to enable reconciliation by the creditor upon receipt of the amount of money. If the business
context requires the use of a creditor reference or a payment remit identification, and only one identifier can
be passed through the end-to-end chain, the creditor's reference or payment remittance identification should be
quoted in the end-to-end transaction identification.
type: string
type: object
OrganisationSchemeRequest:
description: Code or proprietary identification scheme name for organisation
properties:
code:
description: Name of the identification scheme, in a coded form.
enum:
- BANK
- BDID
- BOID
- CBID
- CHID
- CINC
- COID
- CUST
- DUNS
- EMPL
- GS1G
- SREN
- SRET
- TXID
type: string
proprietary:
description: Name of the identification scheme, in a free text form.
maxLength: 35
minLength: 1
type: string
type: object
PrivateSchemeRequest:
description: Code or proprietary identification scheme name for private person
properties:
code:
description: Name of the identification scheme, in a coded form.
enum:
- ARNU
- BANK
- CCPT
- CUST
- DRLC
- EMPL
- NIDN
- POID
- SOSE
- TELE
- TXID
type: string
proprietary:
description: Name of the identification scheme, in a free text form.
maxLength: 35
minLength: 1
type: string
type: object
OtherIdentificationResult:
properties:
id:
description: Unique and unambiguous identification.
type: string
issuer:
description: Entity that assigns the identification.
type: string
scheme:
$ref: '#/components/schemas/CodeOrProprietaryResult'
description: Name of the identification scheme.
type: object
BirthInformationResult:
properties:
city:
description: City where a person was born.
type: string
country:
description: Country where a person was born.
type: string
date:
description: Date on which a person is born.
format: date
type: string
province:
description: Province where a person was born.
type: string
type: object
CodeOrProprietaryResult:
properties:
code:
description: >-
Name of the identification scheme, in a coded form as published in
an external list.
type: string
proprietary:
description: Name of the identification scheme, in a free text form.
type: string
type: object
````