Cashflows Gateway API
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.
How to 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:
Extract the paymentJobReference and paymentReference from the notification webhook.
Match these details with the corresponding references that you stored when you created the payment job.
Include them in a RetrievePaymentJob API call.
Example RetrievePaymentJob
GET https://gateway-int.cashflows.com/api/gateway/payment-jobs/{paymentJobReference}/payments/{paymentReference}
Example response with the payment status and amount
"status": "Paid",
"amountToCollect": "10.00"
How to 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.
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:
Send the 200 response with the paymentJobReference and the paymentReference, for example:
{
paymentJobReference: "200421017498767380",
paymentReference: "200421100461508616"
}