Notifications

1 1. Where to find the notifications
2 2. Receive Notification Request
- 2.1 Data Types
- 2.2 Sample Notification
3 3. Retry Schedule
- 3.1 3.1 De-duplication
4 4. Additional Notification Information
5 5. Verify Notification Checksum (optional)

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. Receive Notification Request

The code provided (below right) is a sample of a notification, after a transaction.

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

If your endpoint does not return a 2XX HTTP status code, ISX will attempt to retry with additional POST(s).

The notification will be attempted in the following intervals, until a response is received: 5 seconds, 1 minute, 1 hour, 6 hours, 12 hours, 1 day, and finally one more day.

A merchant can receive web hooks in any order. ISX does not allow for FIFO (First In First Out). If the merchant API is down on the first notification, ISX is not able to hold up the system for the rest of the notifications. A merchant needs to implement final states. If a merchant receives a final state (e.g., transaction_accepted), then the merchant can ignore all the other notifications.

Data Types

Field	Type	Description

Field	Type	Description
id	String	Unique response identification code.
secret	String	The transaction secret code.
mode	String	The transaction mode detected by ISX.
recurring_transaction	Boolean	Whether the transaction was a recurring operation or not.
original_message	Object	Information about your transaction request.
workflow_state	Object	State information about the workflow.
event	String	Event name of the notification. Refer to Transaction Events & States for full list.
state	String	State of the transaction. Refer to Transaction Events & States.
compound_state	String	Compound State of the transaction. Refer to Transaction Events & States.
card_reference	Object	Information of the card that was used.
payment_provider_responses	Array	Information about payments or credits made.
payment_amount	Object	Original requested payment amount.
identity	Object	Information about the identity.
response_code	String	Response code of the transaction. Refer to Transaction Events & States.
response_code_description	String	Response code description.
test_transaction	Boolean	Denotes use of Test Card.

Sample Notification

{
	"id":"885e3506-eb13-4d2c-bc24-e336aaf94037",
	"secret":"083daa84-77b6-4817-a4f3-5771779c1c82",
	"mode":"registration",
	"recurring_transaction":false,
	"original_message":{
		"merchant_id":"widgets-pty-ltd",
		"transaction_id":"6efa5fac-89de-4e75-a2f9-4d34333e7cf1",
		"reference":"256b4622-ea1d-4af0-8326-a276a0627810",
		"account":{
			"identifier":"Test_ID",
			"ext":{
				
			}
		}
	},
	"workflow_state":{
		"capture":"SUCCESS",
		"charge":"SUCCESS",
		"credit":"NA",
		"3ds":"SUCCESS",
		"piv":"SUCCESS",
		"sca":"SUCCESS",
		"docs":"NA",
		"kyc":"NA"
	},
	"event":"transaction_accepted",
	"state":"SUCCESS",
	"compound_state":"SUCCESS.COMPLETE",
	"card_reference":{
		"masked_pan":"411111....1111",
		"card_brand":"VISA",
		"expiry_date":"1222",
		"recurring_id":"f7fb955_15fc0a831d7__7fa7"
	},
	"payment_provider_responses":[
		{
			"operation_type":"authorization-and-capture",
			"operation_successful":true,
			"provider_type":"credit_card",
			"provider_name":"ISXPay",
			"request_currency":"EUR",
			"reference_code":"349351111111111111",
			"provider_reference_code":"1111111111",
			"response_id":"11111111111",
			"status_code":"OK000",
			"status_description":"Success"
		}
	],
	"payment_amount":{
		"currency":"EUR",
		"amount":3100
	},
	"identity":{
		"id":"_b103fc0_158a2f3a950__7e12",
		"download_url":"https://gateway.isignthis.com/v1/identity/_b103fc0_158a2f3a950__7e12",
		"ledger_lifetime_amount":"63828",
		"ledger_lifetime_currency":"EUR",
		"credit_ledger_lifetime_amount":"14625",
		"credit_ledger_lifetime_currency":"EUR",
		"kyc_state":"NONE",
		"created_at":"2016-11-26T23:34:51.301Z"
	},
	"response_code":"00",
	"response_code_description":"Approved and completed successfully",
	"test_transaction":false
}

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.

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

4. Additional Notification Information

Currently, we do not have a notification which alerts the merchant if a card is enrolled in 3DS or not.

There are settings which decide what action to take if a card is enrolled or not.

Discuss with the ISX relationship management team for these workflow settings.

This notification is upcoming in future releases.

5. Verify Notification Checksum (optional)

Every notification will include the X-ISX-Checksum header. This header will hold the hash-based message authentication code (HMAC) value of the notification body.

The notification body is hashed using the SHA256 HMAC algorithm, using a unique key generated for this purpose. It is provided to you with the name of Notification Token.

To generate the hash you should be using the RAW BODY of the response with the Key that was provided to you.

The resulting hash is base64-encoded.

The header can be used to verify that the notification message has not been tampered with, while in transit.