Payments – Hosted Payment Page (HPP) - Online Payments

Handling payment status updates

To notify you about a payment status update, for example when the payment changes from Pending to Paid, we send you back a webhook. The body of the notification webhook includes the paymentJobReference and paymentReference. Here is an example.

When you receive a webhook, you need to extract these details and include them in a RetrievePaymentJob API call to get the payment status.

When  the payment status has been confirmed, your business systems can be updated to match. For example, if the payment status is Paid, you can store this in your database and proceed with your shipping process.

Tip: For security reasons, we recommend that you update an order only when you receive the notification webhook from us. A notification from our Cashflows Gateway assures you that a payment request has not been intercepted during transfer.

Receive a notification webhook

We recommend that when you receive a notification webhook from us, you use it to confirm the status of the payment before you update an order.

To receive the payment status :

1.     Extract the paymentJobReference and paymentReference from the notification webhook.

1.     Include them in a RetrievePaymentJob API call.

Reply to a notification webhook

When the Cashflows Gateway receives the confirmed paymentJobReference and paymentReference, the notification process ends. It starts again when another payment status change occurs. It’s good practice to acknowledge a notification webhook so that we know that you have received it and it has not been intercepted.

Also, if the response does not contain the expected 200 response code and the message body, or if there is no response at all, the gateway keeps trying to send the same notification webhook for as long as a month. Initially, the retries are every minute and then every day and then every week. Therefore, if you don’t acknowledge a notification webhook, the repeated attempts to send it create unnecessary gateway traffic.

To reply to a notification webhook:

1.     Send the 200 response with the paymentJobReference and the paymentReference, for example:

{

    paymentJobReference: "200421017498767380",

    paymentReference: "200421100461508616"

}

Handling retry attempts

If a payment fails, our Cashflows Gateway offers the shopper an opportunity to try again, for example with a different payment card. The gateway keeps trying until either the payment is successful or the number of retries is exceeded. Here’s an example from our integration environment.

The shopper can select the Retry button and enter different card details. If they try too many times, the shopper sees a page to tell them that they have exceeded the number of attempts. Here’s an example from our integration environment.