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”

Receive Notification Request

The code provided 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, iSignthis will attempt to retry with additional POST(s).

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

Field Type Description Example
id “String” Unique response identification code. "885e3506-eb13-4d2c-bc24-

e336aaf94037"
secret “String” The transaction secret code. "083daa84-77b6-4817-a4f3-

5771779c1c82"
mode “String” The transaction mode detected by iSignthis. "registration"
recurring_transaction Boolean Whether the transaction was a recurring operation or not true,false
original_message Object Information about your transaction request. Original Message Object
workflow_state Object State information about the workflow. Workflow State Object
event “String” Event name of the notification. See Transaction Events for full list "transaction_accepted"
state “String” State of the transaction. See Transaction States. "PENDING"
compound_state “String” Compound State of the transaction. See Transaction States. "PENDING.PROCESSING_TRANSACTION_A"
card_reference Object information of the card that was used Card reference object
payment_provider_responses Array Information about payments or credits made. Payment Provider Response Object
payment_amount Object Original requested payment amount Payment Amount Object
identity Object Information about the identity. Identity Object
response_code “String” Response code of the transaction. See Transaction States. "IS0101"
response_code_description “String” Response code description. "Transaction in progress"
test_transaction Boolean Denotes use of Test Card false

 

Sample JSON  State Response

{
    "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
}

Additional information regarding notifications

We currently do not have a notification which alerts the merchant if a card is enrolled or not in 3DS.There are settings which decide what action to take if a card is enrolled or not.

Discuss with Merchant support for these workflow settings. This notification is upcoming in future releases.

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 while in transit.

Examples of creating base64 hashes using HMAC SHA256 in different programming languages (external link)