Notifications

1 1. Where to find the notifications
2 2. Receive Notification Request
3 3. Additional Notification Information
4 4. 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. 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.

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