1. Introduction
SEPA Instant Instant Notification (SIIN) is basically additional information/notification(s) of SEPA inbound transactions.
2. Notifications
The following figure depicts the timeline of SIIN notifications for SDD:
Notes
After a mandate has been triggered, it either gets executed or executed rejected.
A mandate can get executed rejected during settlement.
Mandate cancellation may take place at any given point throughout the process.
Type | Description | Notification |
|---|---|---|
Mandate created | Mandate has been created. | {
"id": "BLBRE-202410-00000257",
"uid": "5efc2c74-4fd0-4895-af0b-3ad053f50d20",
"recurring_transaction": false,
"event": "mandate_created",
"original_sender_iban": "CY80904000010001918197001000",
"original_sender_name": "John Smith",
"original_sender_bank_country": "Cyprus",
"screen_entities": [],
"payment_provider_responses": [
{
"operation_successful": true,
"provider_name": "MT59ZZZ9kj9553335T",
"reference_code": "BLBRE-202410-00000257",
"provider_reference_code": "CY17002001280000001200527600",
"response_id": "Frequent",
"status_code": "2024-10-30T09:38:56.4857597Z",
"external_correlation_id": "",
"details": "Mandate01",
"manual_reconciliation": false
}
],
"payment_amount": {
"currency": "EUR",
"amount": 5000
},
"beneficiary_iban": "CY21002001950000357001234567",
"original_sender_address": "",
"transaction_detail": ""
}
|
Mandate rejected | Mandate has been rejected. | {
"id": "BLBRE-202410-00000257",
"uid": "5efc2c74-4fd0-4895-af0b-3ad053f50d21",
"recurring_transaction": false,
"event": "mandate_rejected",
"original_sender_iban": "",
"original_sender_name": "",
"original_sender_bank_country": "",
"beneficiary_iban": "",
"original_sender_address": "",
"transaction_detail": ""
"screen_entities": [],
"payment_provider_responses": [
{
"operation_successful": true,
"provider_name": "MT59ZZZ9kj9553335T",
"reference_code": "BLBRE-202410-00000257",
"provider_reference_code": "CY17002001280000001200527600",
"response_id": "",
"status_code": "2024-10-30T09:38:56.4857597Z",
"external_correlation_id": "",
"details": "Mandate01",
"manual_reconciliation": false
}
],
"payment_amount": {
"currency": "",
"amount": null
}
}
|
Mandate triggered | Mandate has been triggered. | {
"id": "BLBRE-202410-00000257",
"uid": "5efc2c74-4fd0-4895-af0b-3ad053f50d22",
"recurring_transaction": false,
"event": "mandate_triggered",
"original_sender_iban": "CY80904000010001918197001000",
"original_sender_name": "John Smith",
"original_sender_bank_country": "Cyprus",
"screen_entities": [],
"payment_provider_responses": [
{
"operation_successful": true,
"provider_name": "Merchant name",
"reference_code": "BLBRE-202410-00000257",
"provider_reference_code": "CY17002001280000001200527600",
"response_id": "Frequent",
"status_code": "2024-10-30T09:38:56.4857597Z",
"external_correlation_id": "",
"details": "Mandate01",
"manual_reconciliation": false
}
],
"payment_amount": {
"currency": "EUR",
"amount": 5000
},
"beneficiary_iban": "CY21002001950000357001234567",
"original_sender_address": "",
"transaction_detail": "Mandate01"
}
|
Mandate executed | Mandate has been executed. | {
"id": "BLBRE-202410-00000257"
"uid": "5efc2c74-4fd0-4895-af0b-3ad053f50d23",
"recurring_transaction": false,
"event": "mandate_executed",
"original_sender_iban": "CY80904000010001918197001000",
"original_sender_name": "John Smith",
"original_sender_bank_country": "Cyprus",
"beneficiary_iban": "CY21002001950000357001234567",
"original_sender_address": "",
"transaction_detail": "",
"screen_entities": [],
"payment_provider_responses": [
{
"operation_successful": false,
"provider_name": "Merchant name",
"reference_code": "BLBRE-202410-00000257",
"provider_reference_code": "CY17002001280000001200527600",
"response_id": "Frequent",
"status_code": "2023-11-14T13:12:07.5466826Z",
"external_correlation_id": "",
"details": "Mandate01-1",
"manual_reconciliation": false
}
],
"payment_amount": {
"currency": "EUR",
"amount": 5000
}
}
|
Mandate executed rejected | Mandate execution has been rejected. | {
"id": "BLBRE-202410-00000257",
"uid": "5efc2c74-4fd0-4895-af0b-3ad053f50d24",
"recurring_transaction": false,
"event": "mandate_execution_rejected",
"original_sender_iban": "CY80904000010001918197001000",
"original_sender_name": "John Smith",
"original_sender_bank_country": "Cyprus",
"beneficiary_iban": "CY21002001950000357001234567",
"original_sender_address": "",
"transaction_detail": "",
"screen_entities": [],
"payment_provider_responses": [
{
"operation_successful": false,
"provider_name": "Merchant name",
"reference_code": "BLBRE-202410-00000257",
"provider_reference_code": "CY17002001280000001200527600",
"response_id": "Frequent",
"status_code": "2023-11-14T13:12:07.5466826Z",
"external_correlation_id": "",
"details": "Mandate01-1",
"manual_reconciliation": false
}
],
"payment_amount": {
"currency": "EUR",
"amount": 5000
}
}
|
Mandate settled | Mandate has been settled. | {
"id": "BLBRE-202410-00000257",
"uid": "5efc2c74-4fd0-4895-af0b-3ad053f50d25",
"recurring_transaction": false,
"event": "mandate_settled",
"original_sender_iban": "CY80904000010001918197001000",
"original_sender_name": "John Smith",
"original_sender_bank_country": "Cyprus",
"original_sender_address": "",
"beneficiary_iban": "CY21002001950000357001234567",
"beneficiary_acno": "",
"transaction_detail": "",
"screen_entities": [],
"payment_provider_responses": [
{
"operation_successful": true,
"provider_name": "Merchant name",
"reference_code": "DCS0101056119",
"provider_reference_code": "CY17002001280000001200527600",
"response_id": "Frequent",
"status_code": "2024-10-24T08:27:16.1530000Z",
"external_correlation_id": "",
"details": "Mandate01-1",
"manual_reconciliation": false
}
],
"payment_amount": {
"currency": "EUR",
"amount": 5000
}
}
|
Mandate cancelled | Mandate has been cancelled. | {
"id": "BLBRE-202410-00000257",
"uid": "5efc2c74-4fd0-4895-af0b-3ad053f50d26",
"recurring_transaction": false,
"event": "mandate_cancelled",
"original_sender_iban": "",
"original_sender_name": "",
"original_sender_bank_country": "",
"screen_entities": [],
"payment_provider_responses": [
{
"operation_successful": true,
"provider_name": "MT59ZZZ9kj9553335T",
"reference_code": "BLBRE-202410-00000257",
"provider_reference_code": "CY17002001280000001200527600",
"response_id": "Frequent",
"status_code": "2024-10-30T09:38:56.4857597Z",
"external_correlation_id": "",
"details": "Mandate01",
"manual_reconciliation": false
}
],
"payment_amount": {
"currency": "",
"amount": null
},
"beneficiary_iban": "",
"original_sender_address": "",
"transaction_detail": ""
}
|
Type | Description | Notification |
|---|---|---|
Incoming refund | Debtor initiated refund & merchant’s account has been debited. | {
"id": "BLBRE-202410-00000257",
"uid": "5efc2c74-4fd0-4895-af0b-3ad053f50d27",
"recurring_transaction": false,
"event": "mandate_chargeback",
"original_sender_iban": "CY80904000010001918197001000",
"original_sender_name": "John Smith",
"original_sender_bank_country": "Cyprus",
"beneficiary_iban": "CY21002001950000357001234567",
"original_sender_address": "",
"transaction_detail": "Mandate01",
"screen_entities": [],
"payment_provider_responses": [
{
"operation_successful": false,
"provider_name": "Merchant name",
"reference_code": "RDD0111068107",
"provider_reference_code": "CY21002001950000357001234567",
"response_id": "John Smith",
"status_code": "2023-11-14T13:12:07.5466826Z",
"external_correlation_id": "",
"details": "Mandate01",
"manual_reconciliation": false
}
],
"payment_amount": {
"currency": "EUR",
"amount": 5000
}
}
|
Cancellation by creditor failed | Merchant attempted to cancel direct debit payment, but failed. This corresponds to a payment being cancelled, not a mandate. | {
"id": "BLBRE-202410-00000257",
"uid": "5efc2c74-4fd0-4895-af0b-3ad053f50d28",
"recurring_transaction": false,
"event": "mandate_payment_cancellation_failed",
"original_sender_iban": "CY80904000010001918197001000",
"original_sender_name": "John Smith",
"original_sender_bank_country": "Cyprus",
"beneficiary_iban": "CY21002001950000357001234567",
"original_sender_address": "",
"transaction_detail": "Mandate01",
"screen_entities": [],
"payment_provider_responses": [
{
"operation_successful": false,
"provider_name": "Merchant name",
"reference_code": "DCS0101056119",
"provider_reference_code": "CY21002001950000357001234567",
"response_id": "John Smith",
"status_code": "2023-11-14T13:12:07.5466826Z",
"external_correlation_id": "",
"details": "Mandate011",
"manual_reconciliation": false
}
],
"payment_amount": {
"currency": "EUR",
"amount": 5000
}
}
|
Cancellation by creditor successful | Merchant attempted to cancel direct debit payment, and was successful. This corresponds to a payment being cancelled, not a mandate. | {
"id": "BLBRE-202410-00000257",
"uid": "5efc2c74-4fd0-4895-af0b-3ad053f50d29",
"recurring_transaction": false,
"event": "mandate_payment_cancellation_successful",
"original_sender_iban": "CY80904000010001918197001000",
"original_sender_name": "John Smith",
"original_sender_bank_country": "Cyprus",
"beneficiary_iban": "CY21002001950000357001234567",
"original_sender_address": "",
"transaction_detail": "Mandate01",
"screen_entities": [],
"payment_provider_responses": [
{
"operation_successful": false,
"provider_name": "Merchant name",
"reference_code": "DCS0101056119",
"provider_reference_code": "CY21002001950000357001234567",
"response_id": "John Smith",
"status_code": "2023-11-14T13:12:07.5466826Z",
"external_correlation_id": "",
"details": "Mandate011",
"manual_reconciliation": false
}
],
"payment_amount": {
"currency": "EUR",
"amount": 5000
}
}
|
Reversal by creditor failed | Merchant attempted to reverse direct debit payment (send funds back to creditor), but failed. | {
"id": "BLBRE-202410-00000257",
"uid": "5efc2c74-4fd0-4895-af0b-3ad053f50d30",
"recurring_transaction": false,
"event": "mandate_reversal_failed",
"original_sender_iban": "CY80904000010001918197001000",
"original_sender_name": "John Smith",
"original_sender_bank_country": "Cyprus",
"beneficiary_iban": "CY21002001950000357001234567",
"original_sender_address": "",
"transaction_detail": "Mandate01",
"screen_entities": [],
"payment_provider_responses": [
{
"operation_successful": false,
"provider_name": "Merchant name",
"reference_code": "RDD0111068107",
"provider_reference_code": "CY21002001950000357001234567",
"response_id": "John Smith",
"status_code": "2023-11-14T13:12:07.5466826Z",
"external_correlation_id": "",
"details": "Mandate01",
"manual_reconciliation": false
}
],
"payment_amount": {
"currency": "EUR",
"amount": 5000
}
}
|
Reversal by creditor successful | Merchant attempted to reverse direct debit payment (send funds back to creditor), and was successful. | {
"id": "BLBRE-202410-00000257",
"uid": "5efc2c74-4fd0-4895-af0b-3ad053f50d31",
"recurring_transaction": false,
"event": "mandate_reversal_successful",
"original_sender_iban": "CY80904000010001918197001000",
"original_sender_name": "John Smith",
"original_sender_bank_country": "Cyprus",
"beneficiary_iban": "CY21002001950000357001234567",
"original_sender_address": "",
"transaction_detail": "Mandate01",
"screen_entities": [],
"payment_provider_responses": [
{
"operation_successful": false,
"provider_name": "Merchant name",
"reference_code": "RDD0111068107",
"provider_reference_code": "CY21002001950000357001234567",
"response_id": "John Smith",
"status_code": "2023-11-14T13:12:07.5466826Z",
"external_correlation_id": "",
"details": "Mandate01",
"manual_reconciliation": false
}
],
"payment_amount": {
"currency": "EUR",
"amount": 5000
}
}
|
Merchants should use a unique reference for each trigger so as to facilitate easier correlation.
3. Notification fields
Field | Description |
|---|---|
id | Identifier of the mandate. |
uid | Unique reference for the notification. This is auto-generated. |
recurring_transaction | This field is always set to false. |
event | Refers to the event that triggered this notification. Values: “mandate_created”, “mandate_rejected“, “mandate_triggered”, "mandate_executed", "mandate_execution_rejected", "mandate_settled", “mandate_cancelled”. |
original_sender_iban | IBAN of the sender. |
original_sender_name | Name of the sender. |
original_sender_bank_country | Country of the sender’s bank. |
screen_entities | This field is always empty. |
operation_successful | Ignore this field. |
provider_name | In mandate_created, this field is set to the SDD creditor ID. |
reference_code | In mandate_created, this field reflects the reference provided when the mandate was created. In mandate_chargeback, mandate_reversal_failed & mandate_reversal_successful, this field reflects the unique reference of the new transaction (not the original trigger). |
provider_reference_code | The IBAN of the merchant. |
response_id | The type of mandate. Values: Null, “Frequent”, “Recurring”, “Limited”, “OneOff“. |
status_code | Date & timestamp of the event. |
external_correlation_id | Ignore this field. |
details | In mandate_created, this field reflects the account identifier provided when the mandate was created. |
manual_reconciliation | Ignore this field. |
currency | Currently, the value is always “EUR”. This is not specified in mandate_rejected and mandate_cancelled. |
amount | The amount of money being sent. The value of this field is always in cents. In mandate_rejected and mandate_cancelled, this field is set to null. |
beneficiary_iban | IBAN of the merchant. This is not specified in mandate_rejected and mandate_cancelled. |
beneficiary_acno | Ignore this field. |
original_sender_address | The address of the sender, if it is known. |
transaction_detail | In mandate_created, this field is not specified. |
4. Retry Schedule
We are expecting to receive a HTTP status code of 2xx (100, 201 etc) in response to the notification. More info on HTTP status codes is provided here.
If we receive something else (or we are unable to connect to your server), then we consider the transmission of the notification to have failed.
In this case, we will be re-attempting the notification until either:
Your server responses with 2xx HTTP status code; or
Retries are exhausted for the notification.
It is recommended that you respond with non-2xx HTTP status codes only if you were unable to receive the message because we monitor failures.
Retries follow the following schedule:
5 seconds, 1 minute, 1 hour, 6 hours, 12 hours, 1 day, and, finally, after 1 more day.
Since it is possible for your system to receive the message successfully, but we may not get an 2xx HTTP status code (e.g., timeout), you should be prepared to receive notifications at least once. So, duplicate notifications may be received by your system. Your system must deduplicate messages using appropriate unique identifiers.
4.1 De-duplication
Your system must expect to receive duplicate notifications.
It is possible that your server receives a webhook, but due to connectivity loss or timeouts, ISX does not receive a 2xx response from you. In this case, ISX will retry the notification, despite your system having already processed it.
In order to de-duplicate, utilise the uid attribute in the notification body to determine whether the notification is unique. We suggest that you track these identifiers on your side and ignore messages that have repeated.
5. Final notifications
If you have received 'final' notifications, then any notifications after this should be ignored.
