Notification

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

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

Receipt of Notification

To take advantage of this notification, in your application you must:

Identify the session: With the requestId and reference look for the payment in your system, it must match a session that you have previously created.

Validate message signature: You can validate that it is a trusted message from Placetopay by generating and comparing the signature.

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

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

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

Also, if you want to get more information about the session and the related transactions, you should refer to the session and get all the details of it..

Additional fields

Recurring Payment:

Session information: In the internalReference field you can identify the transaction reference from our platform.

Payment recurrence information: The tries field indicates the number of times the payment will be made and the enabled field indicates whether this payment is enabled or disabled.

Examples of answers

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

{
  "status": {
    "status": "APPROVED",
    "reason": "00",
    "message": "Approved transaction",
    "date": "2019-01-01T12:00:00-05:00"
  },
  "internalReference": 1598634446,
  "reference": "564555",
  "signature": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s",
  "recurring": {
     "tries": 2,
     "enabled": 0
  }
}

Improve your integration

Handling Duplicated Events

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

• Verify Session Status: Compare the current status of the session against the state of the notification. If the states match, you might 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 their signature to ensure it hasn't already been handled.

Webhook Retries

It's important to note that the notification webhook is not retried. The notification is only executed once, regardless of whether there is no response, the response is an error, or the connection or response times out. There is only one call made for each notification. As a merchant, ensure that your system is prepared to handle the notification on the first attempt.

Webhook Responses

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

Receiving Webhooks on an HTTPS Server

The notification URL must be secure and must use HTTPS over the internet. Ensure that your server supports TLS 1.2 or 1.3 to maintain a high level of security for the notifications.

Verifying the Signature

The signature of the message 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-1(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.