SIIN

1 1. Introduction
2 2. SIIN Notifications
- 2.1 2.1. Where to find the notifications
- 2.2 2.2. Receive Notification Request
3 3. Retry Schedule
4 4. Prerequisite
5 5. Final notifications

1. Introduction

SEPA Instant Instant Notification (SIIN) is basically additional information/notification(s) of SEPA inbound transactions.

2. SIIN Notifications

2.1. Where to find the notifications

All the required information in the transaction, is sent to the notification URL provided.

A sample of the objects is given below.

To receive notifications on the configured URL, your URL must end with /v1/notification.

Example: “https://test.com/v1/notification”

2.2. Receive Notification Request

The code provided in the sample notifications, is typical of what you will see after a transaction.

In the response, you will be able to find all the required information regarding the transaction.

There are two sample notifications below, one in EUR and another in GBP.

Data Types

Field	Description	Example(s)

Field	Description	Example(s)
id	Unique transaction. This will be the same across all webhook attempts to merchant.	898a610b-432e-41ef-9d47-024b07062520
uid	Same as the ID. Value is always the same.	898a610b-432e-41ef-9d47-024b07062520
recurring_transaction	Always false.	false
event	Always payment_success.	payment_success
original_sender_iban	Original IBAN of the original sender. For non-EUR: this may contain an account number instead of IBAN e.g., GBP payments.	DE5550010517367539681480013595
original_sender_name	Account name of the original sender.	Paul Anderson
original_sender_bank_country	Country (name) of the sender’s (originating) bank.	Germany
original_sender_address	Full address of the original sender (if available).	Street, City, Germany
beneficiary_iban	Beneficiary IBAN (where funds land). For incoming SIIN, this is the merchant's account. Useful for clients who receive SIIN for multiple IBANs. For Cyprus accounts this will always be a CY IBAN.	CY66904000010004100014401000
beneficiary_acno	The isx.money account number of the beneficiary.	1014876501000
transaction_detail	Reference provided by sender/bank for the transaction.	Reference or message specified by the sender
screen_entities	Always an empty list.	[]
payment_provider_resposes	Always a single entry array.
operation_successful	Always false.	false
provider_name	Merchant ID of the beneficiary configured in the system.	test_merchant
reference_code	Transaction reference ID under which inbound transfer is credited to beneficiary’s account.	CT001-0988455
provider_reference_code	The IBAN of the beneficiary. For Cyprus, the same as beneficiary_iban.	CY66904000010004100014401000
respose_id	Same as the original_sender_name	Paul Anderson
status_code	Date & time of the payment.	2021-04-16T09:50:20.2391789Z
external_correlation_id	This reference can be provided to ISX by a merchant. The data can then be returned in the notifications.	4b292023-8b0b-4e75-98b4-5f07273ef06e
details	Same as transaction_detail. These are payment details received from a sender – sender to beneficiary payment details.	Reference or message specified by the sender
manual_reconcilliation	Always false.	false
payment_amount	Amount data.
currency	Transaction currency.	EUR, GBP, USD
amount	Amount in the smallest currency unit (e.g., cents if using EUR).	2500

Sample EUR Notification

{
	"id":"898a610b-432e-41ef-9d47-024b07062520",
	"uid":"898a610b-432e-41ef-9d47-024b07062520",
	"recurring_transaction":false,
	"event":"payment_success", //this is always the same
	"original_sender_iban":"CY76904000010003112651201000",
	"original_sender_name":"Test User",
	"original_sender_bank_country":"Cyprus",
	"screen_entities":[
		
	],
	"payment_provider_responses":[
		{
			"operation_successful":false,
			"provider_name":"Test Merchant",
			"reference_code":"CT001-0988455", //“id” is the unique ID of the SIIN transaction, the “CT” in the “reference_code” is our own internal reference number
			"provider_reference_code":"CY66904000010004100014401000", //this is the IBAN of the beneficiary’s account
			"response_id":"Thompson", //this carries the same information as the ”original_sender_name” field
			"status_code":"2021-04-16T09:50:20.2391789Z", //this is the date and time of the incoming transaction
			"external_correlation_id":"4b292023-8b0b-4e75-98b4-5f07273ef06e",
			"details":"Transaction_details",
			"manual_reconciliation":false
		}
	],
	"payment_amount":{
		"currency":"EUR",
		"amount":25000
	}
}

Sample notification for all other currencies, except EUR

{
	"id":"3decd26e-8b29-450b-82ce-0908b0db2169",
	"uid":"3decd26e-8b29-450b-82ce-0908b0db2169",
	"recurring_transaction":false,
	"event":"payment_success", //this is always the same
	"original_sender_iban":"80013595",
	"original_sender_name":"Viera Mylonas",
	"beneficiary_iban":"12345678",
	"beneficiary_acno":"1014876501000",
	"original_sender_address":", , , ",
	"transaction_detail":"Citizen test 1",
	"screen_entities":[
		
	],
	"payment_provider_responses":[
		{
			"operation_successful":false,
			"provider_name":"Citizen",
			"reference_code":"CTUK1-0001391", //“id” is the unique ID of the SIIN transaction, the “CT” in the “reference_code” is our own internal reference number
			"provider_reference_code":"1014876501000", //this is the 8-digit account of the beneficiary’s account
			"response_id":"Viera Mylonas", //this carries the same information as the ”original_sender_name” field
			"status_code":"2023-01-27T16:46:11.041366Z", //this is the date and time of the incoming transaction
			"external_correlation_id":"",
			"details":"Citizen test 1",
			"manual_reconciliation":false
		}
	],
	"payment_amount":{
		"currency":"GBP",
		"amount":2200
	}
}

3. 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. Prerequisite

It is mandatory for the notification URL provided to be HTTP protocol that uses the SSL/TLS protocol for encryption and authentication (HTTPS).

5. Final notifications

If you have received 'final' notifications, then any notifications after this should be ignored.