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.

FieldTypeDescriptionExample
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_transactionBooleanWhether the transaction was a recurring operation or nottrue,false
original_messageObjectInformation about your transaction request.Original Message Object
workflow_stateObjectState information about the workflow.Workflow State Object
event“String”Event name of the notification. See Event table for full list"transaction_accepted"
state“String”State of the transaction. See States Object."PENDING"
compound_state“String”Compound State of the transaction. See States Object."PENDING.PROCESSING_TRANSACTION_A"
card_referenceObjectinformation of the card that was usedCard reference object
payment_provider_responsesArrayInformation about payments or credits made.Payment Provider Response Object
payment_amountObjectOriginal requested payment amountPayment Amount Object
identityObjectInformation about the identity.Identity Object
response_code“String”Response code of the transaction. See States Object."IS0101"
response_code_description“String”Response code description."Transaction in progress"
test_transactionBooleanDenotes use of Test Cardfalse

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_type": "ID",
          "identifier": "unique_CRM_code",
          "secret": "COMPANY.SECRET",
          "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)