Notification

When a transaction is processed, an HTTP notification (Webhook) is sent to the merchant.

To receive notifications, you must send the notificationURL field with a notification URL. Each time a transaction is processed, an HTTP request will be made to that endpoint with useful information about the transaction status.

{
  "status": {
    "status": "APPROVED",
    "reason": "00",
    "message": "Aprobada",
    "date": "2024-07-11T15:22:37-05:00"
  },
  "internalReference": 1,
  "reference": "5834381",
  "signature": "9c0f8ff164d0af4a795f71ee127d8926f56d05fb"
}

Notification Reception

To make use of this notification, in your application you must:

Identify the transaction: With internalReference and reference, you must search for the payment in your system. This should match a transaction you previously created.

Validate message signature: You can validate that the notification is an authentic message from Placetopay by generating and comparing the signature.

The signature is generated with the following formula: SHA-1(internalReference + status.status + secretKey)

If the generated signature is equal to the signature received in the message, then the notification is authentic.

Update Information: If all you need is the final status of the transaction, then you can update the status in your system.

If you need additional information, you must query the transaction using the internalReference.

Signature validation

To ensure the authenticity of the notification, the session webhook includes a signature in the X-Signature header. You can validate this signature using an SHA-1 hash generated with the values of the session ID, session status, and the transaction key (tranKey) of your site.

const crypto = require('crypto');

const sessionId = notificationBody.session.id;
const sessionStatus = notificationBody.session.status;
const tranKey = 'YOUR_SITE_TRANKEY';

const signatureString = `${sessionId}${sessionStatus}${tranKey}`;

// Generate the signature locally
const generatedSignature = crypto
  .createHash('sha1')
  .update(signatureString)
  .digest('hex');

// Signature received in the notification
const receivedSignature = headers['X-Signature'];

// Validate the signature
if (generatedSignature === receivedSignature) {
  console.log("The notification is authentic.");
} else {
  console.log("Invalid signature: the notification is not authentic.");
}