Token update notifications

Use this service to get notified whenever something on the Network Token or it's underlying PAN changes. It pushes an HTTP message to a webhook of your choice and updates the card data mapped to the alias value stored in your token vault.

More specifically, a Token status request will be sent whereas the following parameters will be updated as soon as the respective card network triggers a change.

{
    "alias": "7LHXscqwAAEAAAGLgKAf-F9X1QGrAHsa",
    "fingerprint": "F-f5AcNienVUz735BKis71pD",
    "type": "CARD",
    "masked": "489537xxxxxx6386",
    "dateCreated": "2023-07-30T12:47:39Z",
    "card": {
        "panRemoved": false,
        "expiryMonth": "05",
        "expiryYear": "25",
        "cardInfo": {
            "brand": "VISA",
            "type": "debit",
            "usage": "consumer",
            "country": "US",
            "issuer": "U.S. REGION",
            "accountType": "PAN"
        },
        "networkToken": {
            "expiryMonth": "05",
            "expiryYear": "25",
            "status": "ACTIVE",
            "paymentAccountReference": "V0010013020217426481676671969"
        },
        "last4": "6386"
    }
}

📘

Please contact us if you are missing a parameter.

Activation

To enable Network Token update notifications and to configure your webhook please login to your account. Navigate to the Network Tokenization section tab within the Settings menu on your project and add the endpoint url.

Additional security - webhook signing

To protect our webhooks from being tampered, add an additional security layer by signing our webhooks. To access your HMAC key sign, login to our dashboard and navigate to the API Keys tab in the Developers menu within the project section. PCI Proxy will use this key to calculate a signature and add two parameters within the HTTP request header request-signature: A unique timestamp t and the expected signature s0.

To calculate the expected signature, concatenate the timestamp as a string with the webhook payload. Convert the resulting string to bytes and finally create a signature with your HMAC key using SHA256. Finally, compare your calculation to the expected signature s0. If your calculated signature equals s0, the webhook payload is valid and was not modified.

// hex bytes of the key
byte[] key = Hex.decodeHex(key);

// Create sign with timestamp and payload
String algorithm = "HmacSha256";
SecretKeySpec macKey = new SecretKeySpec(key, algorithm);
Mac mac = Mac.getInstance(algorithm);
mac.init(macKey);
mac.update(String.valueOf(timestamp).getBytes());
byte[] result = mac.doFinal(payload.getBytes());
String sign = Hex.encodeHexString(result);

# hey bytes of the key
key_hex_bytes = bytes.fromhex(key)

# Create sign with timestamp and payload
sign = hmac.new(key_hex_bytes, bytes(str(timestamp) + payload, 'utf-8'), hashlib.sha256)

# Create sign with timestamp and payload
echo hash_hmac('sha256', $timestamp . $payload, hex2bin($key));

To verify if you calculated the signature in the right way, the example below can be used. When testing locally, beware of pretty formatting the webhook payload, as it will result in a different signature than expected.

Given the key:
861bbfc01e089259091927d6ad7f71c8b46b7ee13499574e83c633b74cdc29e3b7e262e41318c8425c520f146986675fdd58a4531a01c99f06da378fdab0414a

Given the payload:
HELLO

Given the timestamp:
1605697463367

Then the signature is:
t=1605697463367,s0=82ef9a8178dcb4df0b71540fa06d7da826ecb26e1977e230bdc8c9d6f9f1af84

Retries

Retries are done max. 10 times with an exponential backoff until we receive an HTTP 2xx status code.