swagger: '2.0'
info:
description: >
# Common information
The SEPA Direct Debit schemes create for the first time a payment instrument that can be used for both domestic and
cross-border collections throughout the EU countries.
Pros for creditors:
* Collection of domestic and cross-border direct debits across EU countries
* Ability to determine the exact date of collection
* Payment completion within a pre-determined time cycle
* Straightforward reconciliation of payments received
* Ability to automate exception handling (refunds, returns, rejects)
Pros for debtors:
* Simple means of paying bills throughout EU countries
* Easy reconciliation of debits on account statements
* No-questions-asked, fast and simple refund procedure
The scheme operates transactions in the euro. The scheme allows a creditor to collect funds from a debtor’s account
provided that a signed mandate has been granted by the debtor to the creditor. The debtor and the creditor must each
hold an account with a credit institution located within SEPA.
The credit institution executing the direct debit transaction must be a scheme participant. The scheme may be used
for single or recurrent direct debit collections, the amounts are not limited.
# Introduction
This service enables clients to initiate and accept SEPA Direct Debit payments. In includes an API for Creditor and
for Debtor roles, which allows to initiate Payments and Refunds, accept payments and create Chargebacks. The API
also includes an Event Notification mechanism to stay notified about the state changes of Payments, Refunds and
about incoming Payments.
The service implements an API-first design with most management functions available via a Management API.
An Administration portal is also available for managing critical system configuration.
A Sandbox environment is available for testing the integration with the API. Sandbox functions fully emulate the
SEPA Direct Debit functionality in an isolated environment for testing and debugging purposes.
The next chapters outline the characteristics of the API.
## API style and protocol
The SEPA Direct Debit service is available as a RESTful HTTP-based API, compatible with the OpenAPI Specification.
Resource objects are coded in JSON and include relative hypermedia links to related resources. In addition, each
resource may contain client-defined metadata in the form of key-value pairs.
The path in the URI is prefixed with ``/sandbox`` or ``/live``, depending on the operations mode, and also
includes the API major version. The path also includes the ``/creditor`` or ``/debtor`` component, differentiating
the client roles.
## Event Notifications
When a change in a Payment's status occurs, the system notifies the client about the event. The notification
mechanism is implemented as HTTP Webhooks. A webhook URI for receiving event notifications for about a particular
object can be specified during its creation.
The system supports event notifications about such objects:
* **Payments**
* **Refunds**
* **Chargebacks**
## Security
Access to the API requires usage of OpenID Token-based Authorization. The initial Client Credentials are obtained
when performing Dynamic Client Registration.
In Live mode, usage of a Client Certificate is mandatory, when establishing a TLS connection. Client Certificates
can be set up in the Administrator's portal, or through the Management API, based on the client's CSRs.
In Live mode, for Webhooks, a Webhook Client Certificate must be set up in the system. This certificate is used
by the system when invoking a Webhook. Webhook Client Certificates can be set up in the Administrator's portal,
or through the Management API, based on the system-generated CSR.
## API functions
**Creditor Operations API** functions' goal is to allow the client to implement a SEPA Direct Debit payment flow,
in a Creditor role. These functions are presented in the section _Creditor Operations API_.
**Debtor Operations API** functions' goal is to allow the client to implement a SEPA Direct Debit payment flow, in a
Debtor role. These functions are presented in the section _Debtor Operations API_.
**Management API** functions' goal is to provide the client with means to set up, manage and configure the service.
Such functions facilitate an API-first approach, and allow the client to integrate these management actions into the
client's own software modules or graphical user interfaces.
* Dynamically register a Client.
* Set up Client Certificates, and Webhook Client Certificates.
* Query aggregated statistics.
## Sandbox environment
The Sandbox environment provides a means for testing out the full functionality of the API, but without actually
projecting anything towards the SEPA Direct Debit scheme. A mock engine handles the requests, and enables the
client to test the integration before switching to live operations. The Sandbox also allows to simulate Events,
which allows to test out your system's reactions to the Webhook based Event Notifications about Payments, Refunds or
Chargebacks.
# Creating an Integration
The following sequence of steps outlines the process of creating a technical integration with the API for SEPA
Direct Debits.
1. To start integrating, enroll your application client using the Dynamic Client Registration feature. You will
obtain client credentials.
2. To access the Administration portal, register a user there. Then, the user can be tied to a registered application
client.
3. Test the API integration, using the Sandbox environment.
To start using the Live service, you need to perform these additional steps.
4. Set up a Client Certificate for calling the API.
5. Set up a Webhook Client Certificate.
# Creditor Operations API
This chapter describes the typical Use Cases for a Creditor, with examples of API calls. It does not specify all
possible paths and outcomes, but demonstrates the look and feel of the API and the general capabilities of it.
1. **Create a Payment**
2. **Verify creditor and accounts**
3. **Receive Payment Status**
4. **Cancel a Payment**
5. **Create a Refund**
6. **Receive Refund Status**
These use cases are depicted together on the following diagram.
These activities are described in the next chapters.
## Create a Payment
To initiate a Payment, the Creditor must provide essential information, including the account information, the
instructed amount, remittance and information about the Mandate.
The ``Creditor-Notification-URI`` header in the request specifies the URI of a webhook, which will receive event
notifications about the particular initiated payment.
_Example API request:_
```http
POST /sandbox/creditor-api/v1/payments HTTP/1.1
Content-Type: application/json
Creditor-Notification-URI: https://creditor.de/webhooks/paymentchanges
Authorization: Bearer cd759c15-8716-43f0-9be4-ed30e9b35695
{
"instructedAmount": {
"amount": "1000",
"currency": "EUR"
},
"debtorAccount": {
"iban": "DE89370400440532013000"
},
"debtorName": "",
"creditorAccount": {
"iban": "DE69423180036469843312"
},
"creditorName": "",
"creditorAgent": "",
"creditorAgentName": "",
"creditorId": "DE452399865083",
"endToEndIdentification": "123-ZXCV-890",
"requestedExecutionDate": "2021-06-01",
"remittanceInformationStructured": {
"reference": ""
},
"mandateInformation": {
"mandateId": "",
"recurringIndicator": true,
"amount": "",
"currency": ""
},
"metadata": {
"anyKey": "value"
}
}
```
An internal ID of the Payment is generated and returned in the response.
Initial status is also returned.
## Verify creditor and accounts
The system will call back to the client to verify the effective state of the Creditor and of the creditor's
Accounts. This callback may occur multiple times during the processing of a payment, and the client must host an
endpoint, which will be called by the system.
_Example API request:_
```http
POST {client-creditor-verify-url} HTTP/1.1
Content-Type: application/json
{
"creditor": {
"creditorId": "",
"creditorName": "",
"creditorAddress": {
"streetName": "",
"buildingNumber": "",
"townName": "",
"postCode": "",
"country": ""
}
},
"account": {
"iban": "",
"currency": "",
"ownerName": "",
"name": "",
"bic": "",
"status": "enabled"
}
}
```
The client shall respond with a 204 HTTP Status in case of a successful creditor and account check.
## Receive Payment Status
When creating a Payment, the client specifies a ``Creditor-Notification-URI`` header during
the payment initiation request, the system will post event notifications to that specific URI. Essentially, events,
which change the state of a particular payment, are posted back to the client, to the specified URI.
In the chapter _"Create a Payment"_, the payment initiation request example contained a
``Creditor-Notification-URI`` header. The following snippet provides an example of an event notification, which is
sent by the system to the client, when the Payment has been settled with the Creditor.
_Example payment settlement notification:_
```http
POST {client-notification-url} HTTP/1.1
Content-Type: application/json
{
"paymentId": "3d9bbfe2-1942-4036-b1e3-d49e65c26a29",
"transactionStatus": "ACCC",
"event": {
"name": "SettledWithCreditor",
"timestamp": "2021-06-02T12:00:00Z"
},
"_links": {
"payment": {
"href": "/sandbox/creditor-api/v1/payments/3d9bbfe2-1942-4036-b1e3-d49e65c26a29"
}
}
}
```
The receiver must acknowledge with a 204 HTTP Status code, in case of successful processing.
## Cancel a Payment
To cancel (reverse) a payment, the following request can be used. The reason code should be specified, e.g.
"MD05" - "Collection not due".
_Example API request:_
```http
DELETE /sandbox/creditor-api/v1/payments/3d9bbfe2-1942-4036-b1e3-d49e65c26a29 HTTP/1.1
Content-Type: application/json
Authorization: Bearer cd759c15-8716-43f0-9be4-ed30e9b35695
{
"reasonCode": "MD05"
}
```
## Create a Refund
To create a Refund for a previously initiated Payment, use the refunds endpoint. The ``paymentId`` of the original
Payment must be specified. In addition, the original amount must be specified, and it must be equal to the original
amount of the initial Payment, minus all previously made refunds to that initial Payment.
The ``Creditor-Notification-URI`` header in the request specifies the URI of a webhook, which will receive event
notifications about the particular created refund.
_Example API request:_
```http
POST /sandbox/creditor-api/v1/refunds HTTP/1.1
Content-Type: application/json
Creditor-Notification-URI: https://creditor.de/webhooks/refundevents
Authorization: Bearer cd759c15-8716-43f0-9be4-ed30e9b35695
{
"paymentId": "3d9bbfe2-1942-4036-b1e3-d49e65c26a29",
"instructedAmount": {
"amount": "300",
"currency": "EUR"
},
"originalAmount": {
"amount": "1000",
"currency": "EUR"
},
"metadata": {
"anyKey": "value"
}
}
```
An internal ID of the Refund is generated and returned in the response.
Initial status is also returned.
## Receive Refund Status
When creating a Refund, the client specifies a ``Creditor-Notification-URI`` header during
the refund creation request, the system will post event notifications to that specific URI. Essentially, events,
which change the state of the refund, are posted back to the client, to the specified URI.
In the chapter _"Create a Refund"_, the request example contained a
``Creditor-Notification-URI`` header. The following snippet provides an example of an event notification, which is
sent by the system to the client, when the Refund has been settled with the Creditor.
_Example refund settlement notification:_
```http
POST {client-notification-url} HTTP/1.1
Content-Type: application/json
{
"refundId": "45f171ac-ba35-4a7a-8b29-c6b8c53306f0",
"transactionStatus": "ACCC",
"event": {
"name": "SettledWithCreditor",
"timestamp": "2021-06-22T14:00:00Z"
},
"_links": {
"refund": {
"href": "/sandbox/creditor-api/v1/refunds/45f171ac-ba35-4a7a-8b29-c6b8c53306f0"
}
}
}
```
# Debtor Operations API
This chapter describes the typical Use Cases for a Debtor, with examples of API calls. It does not specify all
possible paths and outcomes, but demonstrates the look and feel of the API and the general capabilities of it.
1. **Confirm availability of Funds**
2. **Receive Payment Charge**
3. **Reject Payment**
4. **Create a Chargeback**
5. **Receive Chargeback Status**
6. **Receive a Refund**
These use cases are depicted together on the following diagram.
These activities are described in the next chapters.
## Confirm availability of Funds
When processing incoming Direct Debits, the payment engine requires early on the information about the availability
of funds on the debtor account. The client must host an endpoint, which will be called by the system for that
purpose, during pre-processing of incoming payments.
_Example Funds availability Callback:_
```http
POST {client-funds-avail-url} HTTP/1.1
Content-Type: application/json
{
"account": {
"iban": ""
},
"instructedAmount": {
"amount": "",
"currency": ""
}
}
```
The client shall respond with a 204 HTTP Status in case of a successful account and funds availability check.
## Receive Payment Charge
To receive incoming Direct Debits, the client must host a payment charges endpoint, which will be called by the
system. The client should reply with a 204 HTTP Status code to acknowledge that the payment charge is received.
_Example API request:_
```http
POST {client-payment-charges-url} HTTP/1.1
Content-Type: application/json
{
"paymentId": "6aa06e57-031d-4359-ae5d-0188cb7817c7",
"instructedAmount": {
"amount": "1000",
"currency": "EUR"
},
"debtorAccount": {
"iban": "DE89370400440532013000"
},
"debtorName": "",
"creditorAccount": {
"iban": "DE69423180036469843312"
},
"creditorName": "",
"creditorAgent": "",
"creditorAgentName": "",
"creditorId": "DE452399865083",
"endToEndIdentification": "123-ZXCV-890",
"requestedExecutionDate": "2021-06-01",
"remittanceInformationStructured": {
"reference": ""
},
"mandateInformation": {
"mandateId": "",
"recurringIndicator": true,
"amount": "",
"currency": ""
}
}
```
Subsequently, the client can reject the payment, by issuing a separate payment rejection call.
## Reject Payment
To reject a payment, the following request can be used.
The reason code of rejection should be specified, e.g. "MD01" - "No Mandate".
_Example API request:_
```http
POST /sandbox/debtor-api/v1/payments/6aa06e57-031d-4359-ae5d-0188cb7817c7/actions/reject HTTP/1.1
Content-Type: application/json
Authorization: Bearer 2898601e-dfa9-4cfe-84e9-e70e1eacbfef
{
"reasonCode": "MD01"
}
```
## Create a Chargeback
To create a Chargeback, the following request can be used.
The reason code of rejection should be specified, e.g. "MD06" - "Refund Request By End Customer".
_Example API request:_
```http
POST /sandbox/debtor-api/v1/chargebacks HTTP/1.1
Content-Type: application/json
Authorization: Bearer 2898601e-dfa9-4cfe-84e9-e70e1eacbfef
{
"paymentId": "6aa06e57-031d-4359-ae5d-0188cb7817c7",
"reasonCode": "MD06"
}
```
## Receive Chargeback Status
Notifications about the client-initiated Chargeback status shall be posted to the ``Debtor-Notification-URI``,
which has been specified during the creation of the Chargeback.
_Example chargeback settlement notification:_
```http
POST {client-notification-url} HTTP/1.1
Content-Type: application/json
{
"refundId": "45f171ac-ba35-4a7a-8b29-c6b8c53306f0",
"transactionStatus": "ACCC",
"event": {
"name": "SettledWithCreditor",
"timestamp": "2021-06-22T14:00:00Z"
},
"_links": {
"chargeback": {
"href": "/sandbox/debtor-api/v1/chargebacks/45f171ac-ba35-4a7a-8b29-c6b8c53306f0"
}
}
}
```
## Receive a Refund
To receive creditor-initiated refunds, the client must host an endpoint, which the system will invoke. The Refund
references one or more original payments.
_Example API request:_
```http
POST {client-refunds-url} HTTP/1.1
Content-Type: application/json
{
"refundId": "6aa06e57-031d-4359-ae5d-0188cb7817c7",
"payments": [
{
"paymentId": "6aa06e57-031d-4359-ae5d-0188cb7817c7"
}
],
"instructedAmount": {
"amount": "1000",
"currency": "EUR"
},
"debtorAccount": {
"iban": "DE89370400440532013000"
},
"debtorName": "",
"creditorAccount": {
"iban": "DE69423180036469843312"
},
"creditorName": "",
"creditorAgent": "",
"creditorAgentName": "",
"creditorId": "DE452399865083",
"endToEndIdentification": "123-ZXCV-890",
"requestedExecutionDate": "2021-06-01",
"remittanceInformationStructured": {
"reference": ""
},
"mandateInformation": {
"mandateId": "",
"recurringIndicator": true,
"amount": "",
"currency": ""
}
}
```
version: 1.0.0
title: SEPA Direct Debits
x-publishing-date: 11.05.2020
host: api.tietoevry.com
tags: []
schemes:
- http
- https
paths: {}
definitions: {}