Integrate Image Checking Notification

What is the Image Checking Push Notification?

The Image Checking Push Notification is a near real-time notification about an image checking decision once it has been made. Providing a notification of an image checking decision results in a better customer experience for the end-user by setting expectations and prompting them to try again if their image is rejected. The Push Notification can be configured to point to a client’s API endpoint using different means of authentication which can be agreed upon within integration phase.

Client Deliverables

The client is required to setup an API endpoint to allow the Thales platform to send a notification to about an images’ current status. This would need to include a valid SSL Website Certificate and only allow HTTPS connection to ensure of encryption of data in transit using TLS1.2 and above.

An agreed authentication method will be a requirement during the project kick off phase to ensure all parties are inline.

Request

The request will be made up of a Header and Request body.

Header (Example Curl)

curl --request POST \
--header 'Accept: application/json' \
--header 'Potential Auth Control Option' \
--header 'Content-Type: application/json' \
--header 'x-correlation-id: ' \
--data ''

Body (application/json)

{
    "ImageId": “<Unique Image Id associated with a specific design submission>”,
    "Orientation": "<Horizontal or Vertical>",
    "ImageType": "<Gallery or Custom>",
    "ImageState": "<Pending,  Accepted or Rejected",
    "RejectionCode": "00",
    "SubmissionTimeStamp": "yyyyMMddHHmmss",
    "ImageCheckingTimeStamp": "yyyyMMddHHmmss",
    "DataCapture": {}
}

Note:

• RejectionCode will default to “00” for Accepted Gallery and Custom designs. This will be replaced with an Image Checking code if the image has been rejected. Image Checking codes can be configured and viewed within the AAM/SMC Administration Dashboard.
• DataCapture are optional values if they have been setup within the Product which can store and send back additional information to help map sessions and ImageIDs.
• ImageCheckingTimeStamp will be empty depending on the Image Status. Only Custom Images will receive this timestamp when within the Accepted or Rejected state.

Example DataCapture:

    "DataCapture": {
        "TokenId": "12345678901234567890", // This could be a value from the client to identify the end user more easily.
        "Optional1": "Value1" // There could be more than one DataCapture Key and Value
    }

Response

Thales would require a response from the API endpoint to know if the Push Notification was successful or not. This would allow the Push Notification to periodically Push again if the API endpoint was down or if there was an internal server error for example.

Status Code

AllAboutMe Push Notification would require at minimum a 200 Response Status code if a body is not going to be returned.

Body

{
   "CardImageId": "Value",
   "Success": "True or False"
} 

Note: The body could be optional if required by the client but must be agreed within the project requirements phase.

Authentication Options

Secret within Header

Simplest form of Authentication would be to use a Secret shared between Thales and the client to identify the incoming request is valid.

Example

--header 'Accept: application/json' \
--header 'Secret: xxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--header 'x-correlation-id: ' \

IP Address restrictions

Thales can also supply an external IP address of the request originator so that the client could potentially lock down the API endpoint to only except Push Notification from this requestor.

mTLS using Public/Private Certificate

The Push Notification also has the ability to support mTLS using certificates to help negotiate a secure channel between Thales and the client.

Thales can create a Public/Private key pair for which the public key is shared with the client and installed within their API endpoint.

Thales would be required during the request handshake to offer up the private key to match the client certificate.

Examples

Gallery - Auto Accept Notification

{
    "ImageId": "9tf5udq41",
    "Orientation": "Horizontal",
    "ImageType": "Gallery",
    "ImageState": "Accepted",
    "RejectionCode": "00",
    "SubmissionTimeStamp": "yyyyMMddHHmmss",
    "ImageCheckingTimeStamp": "",
    "DataCapture": {
        "TokenId": "12345678901234567890",
        "Optional1": "Value1"
    }
}

Note: RejectionCode is default “00” for Accepted Images and the ImageCheckingTimeStamp is empty “”.

Custom Image – Pending Status after submission

{
    "ImageId": "9tf5udq41",
    "Orientation": "Vertical",
    "ImageType": "Custom",
    "ImageState": "Pending",
    "RejectionCode": "",
    "SubmissionTimeStamp": "yyyyMMddHHmmss",
    "ImageCheckingTimeStamp": "",
    "DataCapture": {
        "TokenId": "12345678901234567890",
        "Optional1": "Value1"
    }
}

Note: RejectionCode is empty “” for Pending Images and the ImageCheckingTimeStamp is empty “”.

Custom Image – Rejected Status Notification

{
    "ImageId": "9tf5udq41",
    "Orientation": "Vertical",
    "ImageType": "Custom",
    "ImageState": "Rejected",
    "RejectionCode": "01",
    "SubmissionTimeStamp": "yyyyMMddHHmmss",
    "ImageCheckingTimeStamp": "yyyyMMddHHmmss",
    "DataCapture": {
        "TokenId": "12345678901234567890",
        "Optional1": "Value1"
    }
}

Custom Image – Accepted Notification

{
    "ImageId": "9tf5udq41",
    "Orientation": "Vertical",
    "ImageType": "Custom",
    "ImageState": "Accepted",
    "RejectionCode": "00",
    "SubmissionTimeStamp": "yyyyMMddHHmmss",
    "ImageCheckingTimeStamp": "yyyyMMddHHmmss",
    "DataCapture": {
        "TokenId": "12345678901234567890",
        "Optional1": "Value1"
    }
}

Note: RejectionCode is default “00” for Accepted Images