Notification

When a session is completed, an HTTP notification (Webhook) is sent to the merchant.

To receive notifications, you must configure a notification URL in your application. Each time a session is completed, an HTTP request will be made to that endpoint with useful information about the session status.

Notification structure MerchantNotificationRequest

This is the structure of the object you will receive in the notification:

{
  "status": {
    "status": "APPROVED",
    "reason": "00",
    "message": "Transaction approved",
    "date": "2019-01-01T12:00:00-05:00"
  },
  "requestId": 1234,
  "reference": "TEST_123424",
  "signature": "sha256:a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s"
}

Notification Reception

For proper integration and to ensure your system knows the correct session status, you must:

Make your notification endpoint available

Configure the endpoint on your server that will receive the notification.

This endpoint must be accessible by Placetopay services and must accept HTTPS communication with TLS 1.2 or 1.3.

Identify the payment session

In the received notification, you will find the following fields that will help you identify the payment session:

• requestId: Unique identifier of the session in Webcheckout.
• reference: Transaction reference.

Use the requestId and reference to find the payment in your system, it must match a session you previously created.

Validate message signature

Because the notification comes from an external system to your servers, it's important to validate that the message is authentic and comes from a reliable source. For this purpose, a signature included in the message is used, which was generated using the secretKey that only the involved systems know. To learn more about your secretKey, consult the Authentication documentation.

To start your validation, you must have the secretKey associated with your merchant available.

Identify the algorithm: To identify the algorithm used in the signature, consider the following:

• If the signature field starts with the sha256: prefix, then the signature was generated using SHA-256.
• If the signature field has no prefix, then the signature was generated using SHA-1. We recommend updating your integration to use SHA-256. Contact support if you need help with this process.

Extract the plain signature: Once the algorithm is identified, identify the signature field.

• If the sha256: prefix is present, you must remove it and this will give you the plain signature you need to compare, we'll call this receivedSignature.
• If there is no prefix, then the plain signature is equal to the value of the signature field, this will be your receivedSignature.

Generate your own signature: Once the algorithm is identified, you must generate your own signature using the following formula:

• For SHA-256: SHA-256(requestId + status.status + status.date + secretKey)
• For SHA-1: SHA-1(requestId + status.status + status.date + secretKey)

With this you will obtain the signature generated by your system, we'll call this generatedSignature.

Compare signatures: Finally, compare the signature you generated (generatedSignature) with the signature you received in the message (receivedSignature). If both signatures are equal, then the notification is authentic and you can proceed to update the session status in your system.

Update Information: If all you need is the final session status, then you can update the status in your system and that would be all.

Additionally, if you want to get more information about the session and related transactions, you should query the session and get all its details.

For Recurring Payments

Recurring payments occur after the initial session is completed, and generate notifications similar to those of a normal session, with some exceptions:

• The requestId field is NOT present. Since this payment is generated automatically and is not associated with a session created by the merchant. It is an independent transaction.
• The internalReference field is present. This field contains the unique identifier of the recurring payment on our platform.
• The new recurring object is present. This field contains additional information about the payment recurrence.
  • The recurring.tries field indicates the number of times the charge will be made.
  • The recurring.enabled field indicates whether recurring billing is enabled or disabled.

Improve your integration

Handling duplicate notifications

Although duplicate notifications are very rare, they can occasionally occur. As a merchant, it's important to handle these events appropriately to ensure the integrity of your transaction processing. Here are some guidelines:

• Verify session status: Compare the current session status with the notification status. If the statuses match, you may already have the updated version of the session.
• Store processed notifications: For more advanced integrations, store notifications that have been processed and compare any new notification by its signature to ensure it hasn't been handled previously.

Notification retries

It's important to note that the notification webhook is not retried. The notification is executed only once, regardless of whether there is no response, the response is an error, or the connection or response time times out. Only one call is made per notification. As an integrator, make sure your system is prepared to handle the notification on the first attempt.

Notification responses

The response for the webhook must be a 2xx HTTP success status. The response should be given as soon as possible. If the business logic is too complex or slow, we recommend handling the notification in an asynchronous job. This ensures that the webhook call is acknowledged quickly and detailed processing can be done in the background without delaying the response.

Receiving notifications on an HTTPS server

The notification URL must be secure and must use HTTPS on the internet. Make sure your server supports TLS 1.2 or 1.3 to maintain a high level of security in notifications.

Signature verification

The message signature is sent in the signature property and must be verified to ensure the integrity and authenticity of the notification. Use the following formula to verify the signature: SHA-256(requestId + status.status + status.date + secretKey). Make sure to replace secretKey with your actual secret key. This verification step is crucial to ensure that the notification has not been tampered with.

SHA-1 to SHA-256 Migration Process

If you are currently using SHA-1 for signature generation in your notifications, it is highly recommended that you migrate to SHA-256 to improve the security of your integration. Go to our Notification Migration to SHA-256 guide for detailed instructions on how to perform this transition effectively.