Payments – Hosted Payment Page (HPP) - Online Payments

Sending us payment details

So that we can process an online payment, your website needs to send an API payment request to our online payment servers to initiate the transaction.

You send us the payment transaction details in an API message. The message needs to submit a payment request to create a payment job with the details of the transaction. For a card payment, the request needs to include the card details. For a card that is enrolled for 3-D Secure version 2.2, the cardholder name is also required.

For all types of payment, we then send you a link to direct the shopper to our gateway’s 3-D Secure page. This page is where the shopper securely enters their 3-D Secure details. We carry out some 3-D Secure checks and depending on the result of the checks we either decline the transaction or accept if for payment processing.

The payment request needs to be in the form of a HTTPS POST to either our integration or production environment:

Tip: We recommend that you use UTF-8 for encoding before you submit.

If you need an integration account, please email techsupport@cashflows.com.

You must encrypt the message with the API key that you collected from Cashflows Go. For information, see Collect your access credentials.

You must use the same hashing technique that we do so that we can match our hash with yours. The hash assures message consistency and protects the payment request from being tampered with during transfer to our Cashflows gateway (a man-in-the-middle attack).

Your message needs to have the following headers:

ConfigurationId: xxxxx

Hash:ExampleExampleExampleExampleExampleExampleExampleExampleExample ExampleExampleExampleExampleExampleExample

The process for submitting a payment request involves the following steps. These steps are described in the sections that follow:

1.     Create a payment job.
A payment job is a server-to-server call from your server to ours. It contains the details that are required to initiate a payment request. After you have submitted the payment job, the Cashflows Gateway API returns a 201 response ‘Payment job created successfully’ (assuming that the request was successful). For information, see Create a payment job.

2.     Receive the payment job details in the response.
The API returns specific payment and order information and link to our Hosted Payment Page. For information, see Receive a response to a payment request and direct a shopper to the hosted payment page.

3.     Use the link to direct the shopper to our Hosted Payment Page where they can securely enter their card details and submit them for authorisation. For information, see Receive a response to a payment request and direct a shopper to the hosted payment page.

Note: If 3-D Secure is enabled, the Hosted Payment Page redirects the shopper to the 3-D Secure page on their bank’s website before submitting the payment.

How to create a payment job

To create a payment job, you must provide a payment job request that contains at least the mandatory parameters. To help you track payments, we recommend that you provide more than the mandatory details in the payment job. As a minimum, consider including:

·       Payment amount

·       Currency

·       Locale

·       Order reference (the reference that you generate)

·       Customer name

·       Customer email

Tip: As a starting point to establish and test connectivity, it’s good enough to provide only the mandatory information. You can then add details as required to build out the payment job request. To make it easier for you to identify a payment, we recommend that you include as much information as possible. Our API includes many more details including billing/shipping details, order line details and more. For a full list of mandatory and optional parameters, please contact our Technical Support team

To create a payment job:

1.     In the request header, provide your configuration ID and a hash.

Your configuration ID identifies your application to the gateway and is available in Cashflows Go. For information, see Collect you access credentials.

2.     Concatenate the message body to the API key to give one long string.

For example, to use an example API key like this:

845c51f6-1cd5-4338-a586-df752e65d690

To submit to the Cashflows API the following fields and values:

amountToCollect": "10.00", "currency": "GBP", "locale": "en_GB"

You would concatenate with the API key to give:

845c51f6-1cd5-4338-a586-df752e65d690{"amountToCollect": "10.00", "currency": "GBP", "locale": "en_GB" }

3.     Hash the concatenated string to give, for example:

3CDF192F6AC67E3A491EF2B60EA9A03C6B408056CE19C3BBC307EB06A4CE1F4081B8D021B1E9760E7CC18EED479EDBAFF926DADC2953B5F8B25717B8D5CB7609

Important: Every field and value that you send, and every parenthesis, must be included in the hash.

The resulting headers must match the format of this example:

ConfigurationId:201226100000131072

Hash:3CDF192F6AC67E3A491EF2B60EA9A03C6B408056CE19C3BBC307EB06A4CE1F4081B8D021B1E9760E7CC18EED479EDBAFF926DADC2953B5F8B25717B8D5CB7609

Tip: Including optional cardholder and delivery details in your payment request enables us to display this information in the gateway portal transaction search and reports. This can make it easier for you to locate payments and assist with reconciliation. The extra detail can also help our customer support team to find a payment it ever needs investigating.

Receive a response to a payment request and direct a shopper to the hosted payment page

The API receives the payment request and responds with:

·       A response code (to confirm success or otherwise) and

·       A link that points to the Hosted Payment Page where you should direct the shopper.

Here is an example with the link (action URL) highlighted.

If the request is successful, you’ll receive a 201 response. For a list of other response codes, see Response codes.

To receive the response:

1.     Extract the link (action URL) and use it to take you to the integration environment simulation page:

Tip: You can simulate a successful or a failed payment or use the test cards in the simulated live environment. For more information about testing and to find some the test card details that you can use, see Testing.