Migration of notification algorithm from SHA-1 to SHA-256

This guide will help you migrate your Checkout notification integration from the SHA-1 algorithm (deprecated) to the SHA-256 algorithm (recommended and secure).

Why migrate?

SHA-1 has been marked as deprecated due to security vulnerabilities discovered in recent years. SHA-256 is the current industry standard and provides a significantly higher level of security to protect the integrity of notifications.

Differences between SHA-1 and SHA-256

SHA-1 Signature Structure (Deprecated)

{
  "status": { /* ... */ },
  "requestId": 1234,
  "reference": "TEST_123424",
  "signature": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s"
}

• The signature has NO prefix
• Length: 40 hexadecimal characters
• Formula: SHA-1(requestId + status.status + status.date + secretKey)

SHA-256 Signature Structure (Recommended)

{
  "status": { /* ... */ },
  "requestId": 1234,
  "reference": "TEST_123424",
  "signature": "sha256:a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"
}

• The signature HAS the sha256: prefix
• Length: 64 hexadecimal characters (excluding the prefix)
• Formula: SHA-256(requestId + status.status + status.date + secretKey)

Migration Process

Phase 1: Preparation (Dual Support)

During this phase, your system must support BOTH algorithms simultaneously. This allows you to make a seamless transition.

Update validation code

Modify your code to detect the algorithm used. Below we show some examples of what you can implement, but the exact implementation will depend on the programming language you use and your code structure. This implementation is merely a reference and should not be used as-is in production without first adapting it to your specific context.

function validateSignature($notification, $secretKey) {
    $signature = $notification['signature'];
    $requestId = $notification['requestId'];
    $status = $notification['status']['status'];
    $date = $notification['status']['date'];
    
    // Identify the algorithm
    if (strpos($signature, 'sha256:') === 0) {
        // SHA-256
        $receivedSignature = substr($signature, 7); // Remove prefix
        $generatedSignature = hash('sha256', $requestId . $status . $date . $secretKey);
    } else {
        // SHA-1 (legacy)
        $receivedSignature = $signature;
        $generatedSignature = sha1($requestId . $status . $date . $secretKey);
    }
    
    return hash_equals($generatedSignature, $receivedSignature);
}

Update validation code if you are using lightbox

If you are using Lightbox to integrate Placetopay, make sure to update the code that handles notifications to support both algorithms. Check the Lightbox section for more details on how to handle notifications in this context.

Test in testing environment

1. Deploy the updated code to your development/staging environment
2. Request Placetopay support to enable SHA-256 in your test account
3. Perform test transactions and verify that notifications are validated correctly
4. Confirm that both SHA-1 and SHA-256 work correctly

Monitor and log (Optional)

If you want to closely monitor the migration process, implement logging to track which algorithm is being used. For example, in PHP you could add:

if (strpos($signature, 'sha256:') === 0) {
    error_log("Notification received with SHA-256 for requestId: {$requestId}");
} else {
    error_log("Notification received with SHA-1 (legacy) for requestId: {$requestId}");
}

Phase 2: SHA-256 Activation

Once your code is updated and tested:

1. Deploy your changes to production
2. Contact Placetopay support to request SHA-256 activation in your production account
3. The Placetopay team will activate SHA-256 for your account
4. From that moment, all new notifications will include the sha256: prefix in the signature
5. Your code will automatically detect the new format and validate using SHA-256

Phase 3: Post-migration Verification

After activation:

1. Monitor logs: Verify that all new notifications use SHA-256
2. Review metrics: Ensure there's no increase in rejected notifications
3. Validate alerts: Confirm your monitoring system doesn't report anomalies

Phase 4: Cleanup (Optional)

Once you confirm SHA-256 is working correctly for at least 30 days, you can:

1. Remove legacy SHA-1 support code
2. Simplify your validation logic to use only SHA-256
3. Update your internal documentation

Migration Checklist

Use this list to ensure a successful migration:

• Code updated to support both algorithms (SHA-1 and SHA-256)
• Tests performed in development/staging environment
• Logging implemented to track algorithm usage
• Coordination with Placetopay support for activation
• SHA-256 activated in test account
• Successful validation of notifications in tests
• SHA-256 activated in production account
• Active monitoring post-migration (first 7 days)
• Verification of metrics and logs (30 days)
• (Optional) Legacy SHA-1 code removed

Frequently Asked Questions

Support

If you need help during the migration process:

• Support email: [email protected]
• Technical documentation: Notifications
• Authentication documentation: Authentication