Hosted Payment Page Quick Start

Cashflows Hosted Payment Page (HPP) offers a secure, PCI-compliant way to integrate card payments into your site. It’s fully hosted by Cashflows, includes 3D Secure support, is mobile-optimised, and can be branded to match your site.

Hosted Payment Pages are a secure webpage incorporated into your website. Shoppers are direct to our Hosted Payment Page when they check out and pay. Cashflows takes care of the processing, including security aspects and many of the technical complexities. When the payment processing is finished, we redirect the shopper back to your website.

High-Level Flow

Shopper clicks Pay on your site.
Your server sends a payment-initiation JSON to Cashflows Gateway.
Cashflows displays HPP with your custom styling.
Shopper enters card details; 3D Secure may apply.
Gateway processes payment, then notifies your site of success/failure.
Shopper is redirected back to your return URL

Setup

Sensitive data and PCI-DSS

The storage of Sensitive Authentication Data (track data and/or CVV2) post-authorisation is prohibited by Visa and Mastercard, as well as Requirement 3 of the Payment Card Industry Data Security Standard (PCI-DSS).

If you handle card data you need to demonstrate your systems handle this data securely and that you take full responsibility for your PCI compliance. This includes, but is not limited to, providing your current Attestation of Compliance certificate and evidence of a recent clean vulnerability scan.

A list of approved Security Assessors can be found at: https://www.pcisecuritystandards.org/assessors_and_solutions/qualified_security_assessors.

Prerequisites

You need access to Cashflows Portal. Cashflows Portal is your online account with Cashflows. It gives you access to all your transaction data, payment tools and notifications. This is where you can:

Find the configuration details that you need to integrate our Hosted Payment Page into your website using our API.
Tell us the addresses of the webpages (return URLs) to use to redirect a shopper back to your website after we have processed their payment.
Customise the Hosted Payment Page, if you choose not to use the default page as we provide it.

When you first sign up with us, we send you a welcome email that includes the details that you need to sign into Cashflows Portal. If you don’t know how to sign in, see the Cashflows Portal guide.

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

Important

You need different credentials for the integration and production environments.

Before you can connect to our production environment for going live, you need:

A production account
Sign-in credentials

We provide these when your account has been approved. If you have not received these, email techsupport@cashflows.com.

Important

Gateway webhook notifications are sent from these two IP address: 54.74.58.255 and 52.215.48.101. Depending on your firewall settings, you may wish to whitelist them, as well as Ireland in your Geolocation settings.

User permissions

Before integrating you need to have access to Cashflows Portal. You’ll need the Owner or External Developer user role to access the required pages. If you don’t have access to any of the pages mentioned below, contact your administrator to check your user permissions. If you have not yet set up a Cashflows account, contact us now.

API credentials

To integrate with Cashflows you’ll first need to collect your API credentials:

Configuration ID - unique identifier for your account included in API messages
Current API key - the key for encrypting API messages sent to us

To retrieve your credentials:

Sign into Cashflows Portal and select Configuration from the menu.
Select the API Data tab, the API Data page displays your API configuration details:

If you need to generate a new API key this can be done from the API Data tab:

Select Generate a new API key to generate a new key.
Wherever your integration uses the API key, replace the old key with the new one.
When you have successfully updated all API key references, check the confirmation box and select Update API Key:

Generate your signature

As with all API calls you will need to send a request signature with any requests.

To ensure server to server messages have been issued by valid users, request messages must be signed. The hash field is a SHA2-512 hash calculated by concatenating your API key with a string of the request object. If you don’t have your API key please contact your Implementation Manager.

If the signature is incorrect, an error will be returned. Repeated failures will lock your account, if this happens, please contact your Implementation Manager.

SHA2-512 hash of your request. To generate your hash, concatenate the message body of your request to the API key to give one long string.

Warning

Whitespace and new lines in the request object are included in the hash calculation. We use CR-LF for line breaks, however Unix systems often use just LF, and this can affect calculations. If you can’t match signatures but have the correct password hash, remove unnecessary whitespace from your Request nodes.

After applying a SHA2-512 hash, the concatenated string would look like:

3CDF192F6AC67E3A491EF2B60EA9A03C6B408056CE19C3BBC307EB06A4CE1F4081B8D 021B1E9760E7CC18EED479EDBAFF926DADC2953B5F8B25717B8D5CB7609

Finally, add the generated key as the Hash value in your request:

{
    "ConfigurationId": "YOUR_CONFIGURATION_ID",
    "Hash": "YOUR_SIGNATURE_HASH",
    "Request": {
        "type": "Payment",
        "paymentMethodsToUse": ["creditcard"],
        "parameters": {
            "cardNumber":"4000000000000002",
            "cardCvc": "123",
            "cardExpiryMonth": "05",
            "cardExpiryYear": "23"
        },
        "order": {
            "orderNumber": "Payment ref D1"
        },
        "currency": "GBP",
        "amountToCollect": "10.00"
    },
}

Create a payment job

To create a payment job, you must make a request containing the mandatory parameters as well as your ConfigurationId and Hash discussed above.

To help you track payments, we recommend 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

When starting integration, it’s good enough to provide only the mandatory information to establish and test connectivity quickly. You can then add details as required to build out the payment job request.

Mandatory parameters

Parameter

Description

paymentAmount

Matches the account as reported by the issuer

currency

No match, participating BIN/ issuer

locale

string (query)

Determines the language that the Hosted Payment Page, and any related messages, is displayed in.

For example, to set the language to English, use the locale en-GB. Other options are:

el_GR (Greek)
en_US (US English)
nl_NL (Dutch)
es_ES (Spanish)

If your language is not available, please choose the most appropriate language for your shoppers.

Optional parameters

Parameter	Description
`orderReference`	The reference number that you generate to identify an order.
`customerName`	The name of the shopper.
`customerEmail`	The email address of the shopper.

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.

Example: Create a new payment job

PYTHON

import requests
import json

# Define the API endpoint
url = "https://gateway-inta.cashflows.com/api/gateway/payment-jobs"

# Define the payload (data to send with the request)
payload = json.dumps({
    "amountToCollect": "15.50",
    "currency": "GBP"
})

# Define the headers
headers = {
    'Hash': 'YOUR_SIGNATURE_HASH',
    'ConfigurationId': 'YOUR_CONFIGURATION_ID',
    'Content-Type': 'application/json'
}

# Send the POST request to the API
response = requests.post(url, headers=headers, data=payload)

# Print the response text (or handle it as needed)
if response.status_code == 200:
    print("Request was successful!")
    print("Response: ", response.json())  # Assuming the server returns JSON data
else:
    print(f"Request failed with status code {response.status_code}")
    print("Response Text: ", response.text)

JAVA

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpHeaders;
import java.util.HashMap;
import java.util.Map;

public class Main {
    public static void main(String[] args) throws Exception {
        String url = "https://gateway-inta.cashflows.com/api/gateway/payment-jobs";

        String payload = "{ \"amountToCollect\": \"15.50\", \"currency\": \"GBP\" }";

        // Setting the headers
        Map<String, String> headers = new HashMap<>();
        headers.put("Hash", "YOUR_SIGNATURE_HASH");
        headers.put("ConfigurationId", "YOUR_CONFIGURATION_ID");
        headers.put("Content-Type", "application/json");

        // Create HTTP client
        HttpClient client = HttpClient.newHttpClient();

        // Build the HTTP request
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Hash", headers.get("Hash"))
            .header("ConfigurationId", headers.get("ConfigurationId"))
            .header("Content-Type", headers.get("Content-Type"))
            .POST(HttpRequest.BodyPublishers.ofString(payload))
            .build();

        // Send the request and get the response
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

        // Print the response
        System.out.println(response.body());
    }
}

C#

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var url = "https://gateway-inta.cashflows.com/api/gateway/payment-jobs";
        var payload = "{\"amountToCollect\": \"15.50\", \"currency\": \"GBP\"}";

        var client = new HttpClient();

        // Setting the headers
        client.DefaultRequestHeaders.Add("Hash", "YOUR_SIGNATURE_HASH");
        client.DefaultRequestHeaders.Add("ConfigurationId", "YOUR_CONFIGURATION_ID");

        var content = new StringContent(payload, Encoding.UTF8, "application/json");

        // Sending the POST request
        var response = await client.PostAsync(url, content);

        // Reading and printing the response
        var responseContent = await response.Content.ReadAsStringAsync();
        Console.WriteLine(responseContent);
    }
}

NODEJSREPL

const axios = require('axios');

const url = 'https://gateway-inta.cashflows.com/api/gateway/payment-jobs';
const payload = {
amountToCollect: "15.50",
currency: "GBP"
};

const headers = {
'Hash': 'YOUR_SIGNATURE_HASH',
'ConfigurationId': 'YOUR_CONFIGURATION_ID',
'Content-Type': 'application/json'
};

axios.post(url, payload, { headers })
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error('Error:', error.response ? error.response.data : error.message);
});

PHP

<?php

$url = 'https://gateway-inta.cashflows.com/api/gateway/payment-jobs';
$data = array(
    'amountToCollect' => '15.50',
    'currency' => 'GBP'
);

// Convert data array to JSON
$jsonData = json_encode($data);

// Set headers
$headers = array(
    'Hash: YOUR_SIGNATURE_HASH',
    'ConfigurationId: YOUR_CONFIGURATION_ID',
    'Content-Type: application/json'
);

// Initialize cURL session
$ch = curl_init($url);

// Set cURL options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);

// Execute the request
$response = curl_exec($ch);

// Check for errors
if(curl_errno($ch)) {
    echo 'cURL Error: ' . curl_error($ch);
} else {
    echo $response; // Print the response
}

// Close the cURL session
curl_close($ch);

?>

RUBY

require 'net/http'
require 'json'
require 'uri'

# URL for the API endpoint
url = URI.parse('https://gateway-inta.cashflows.com/api/gateway/payment-jobs')

# Payload (data to be sent)
payload = {
amountToCollect: "15.50",
currency: "GBP"
}.to_json

# Headers
headers = {
'Hash' => 'YOUR_SIGNATURE_HASH',
'ConfigurationId' => 'YOUR_CONFIGURATION_ID',
'Content-Type' => 'application/json'
}

# Create a new HTTP request
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url.path, headers)
request.body = payload

# Send the request and get the response
begin
response = http.request(request)

# Print the response body
puts response.body
rescue StandardError => e
# Print error message if request fails
puts "Error: #{e.message}"
end

Response codes

After you have submitted a request to create a payment job, the Cashflows Gateway API responds with a code. Ideally the response is a success code but can be any of the following.

Response Indicator	Description
`201`	Payment job created successfully.
`400`	Request contains errors.
`401`	Invalid token.
`403`	Insufficient permissions.
`404`	Configuration not found.
`406`	Bad response

Redirect the shopper

When you create a payment job, you receive a response including a link (action URL) to the Hosted Payment Page. This link redirects shoppers so they enter their card details, or select an alternative payment method, on the payment page we host for you.

Extract the link and use it to take shopper Hosted Payment Page, or to the integration environment simulation page when testing.

Example request

{
    "amountToCollect": "10.00",
    "currency": "GBP",
    "locale": "en_GB",
    "order": {
        "orderNumber":"Your ref",
        "billingAddress" : {
            "firstName" : "Alex",
            "lastName" : "Smith"
        },
        "billingIdentity": {
            "emailAddress": "alex@test.com"
        }
    }
}

Example of the full response with the success response code included

{
    "data": {
        "reference": "210121017238589452",
        "createDateTimeUtc": "2021-01-14T10:32:50.506892Z",
        "type": "Payment",
        "traceReference": "210120117364553808",
        "configurationId": "200426117314086912",
        "domain": "cashflows.com",
        "locale": "en_GB",
        "timeZone": "Europe/London",
        "order": {
            "orderNumber": "Your ref",
            "createDateTimeUtc": "2021-01-14T10:32:50.506894Z",
            "billingAddress": {
                "firstName": "Alex",
                "lastName": "Smith"
            },
            "billingIdentity": {
                "emailAddress": "alex@test.com"
            },
            "orderLines": []
            },
            "orderHistory": [],
            "paymentMethodsToUse": [
                "Card"
            ],
            "currency": "GBP",
            "amountToCollect": "10.00",
            "expirationDateTimeUtc": "2021-07-14T10:32:50.5068906Z",
            "lastUpdateTimeUtc": "2021-01-14T10:32:50.5068934Z",
            "lastProcessedTimeUtc": "2021-01-14T10:32:50.5068927Z",
            "flags": {},
            "attributes": {},
            "paymentStatus": "Pending",
            "payments": [
                {
                    "reference": "210121117372807180",
                    "createDateTimeUtc": "2021-01-14T10:32:50.6776922Z",
                    "paymentMethods": [
                        "Card"
                    ],
                    "status": "Pending",
                    "amountToCollect": "10.00",
                    "steps": [
                        {
                            "reference": "210121217372942352",
                            "createDateTimeUtc": "2021-01-14T10:32:50.7307589Z",
                            "action": "DisplayHostedPage",
                            "paymentMethods": [
                                "Card"
                            ],
                            "status": "Pending",
                            "amountToCollect": "10.00"
                        }
                    ],
                    "flags": {},
                    "attributes": {
                        "returnUrlSuccess": "https://www.mywebshop.com/?paymentjobref=210121017238589452&paymentref=210121117372807180&ordernumber=Your+ref",
                        "returnUrlFailed": "https://www.mywebshop.com/?paymentjobref=210121017238589452&paymentref=210121117372807180&ordernumber=Your+ref",
                        "returnUrlCancelled": "https://www.mywebshop.com?paymentjobref=210121017238589452&paymentref=210121117372807180&ordernumber=Your+ref&status=cancelled"
                    },
                    "refunds": [],
                    "captures": []
                }
            ]
        },
    "links": {
        "data": {
            "url": "https://gateway-int.cashflows.com/api/gateway/payment-jobs/210121017238589452",
            "type": "application/json"
        },
        "action": {
            "url": "https://gateway-int.cashflows.com/payment?ref=4ab07d818100e4880130c8e35d25ea1be6b35b94bf1416b2fda63815e83d9fbe68f1a4769d1abc9cf0e57616aa70a8b327f0354f1611fd216383cdd28d5d5580",
            "type": "text/html"
        },
        "documentation": {
            "url": "https://gateway-int.cashflows.com/payment-gateway-api/documentation/index.html",
            "type": "text/html"
        }
    }
}

Processing a payment

When you attempt to process a payment, we send you a webhook notifying you about the payment status, for example when the payment changes from Pending to Paid. If you haven’t already done so, you need to tell us where to send these notification webhooks.

You can then use the paymentJobReference and paymentReference from the notification webhook to check the status of the order to update your systems.

Tip

We recommend updating orders only when you receive the payment status notification. A notification from the Cashflows Gateway assures you that a payment request has not been intercepted during transfer.

When we direct shoppers back to your website, we direct them back to the confirmation webpage corresponding to the status of their payment (successful, failed or cancelled). Using the addresses of the pages (return URLs) that you set up in Cashflows Portal by default.

You can use the default pages provided by Cashflows, or you can display your own. IF you want to display your own, you need to set the addresses (return URLs) of the pages in the Cashflows Portal.

If your business has more than one website for selling different things, you can override the default address and tell us to use a different one that you specify in the payment job request.

How to override a default return URL

If you want your shopper to be sent somewhere other than our default pages or yours, you can use an individual payment job request to tell us. The shopper then returns to your website via a webpage that relates to their purchase rather than the default page.

To override a default return URL include the return URL in the create payment job request:

{
    "amountToCollect": "10.00",
    "currency": "GBP",
    "locale": "en_GB",
    "order": {
        "orderNumber":"Your ref1",
        "billingAddress" : {
            "firstName" : "Alex",
            "lastName" : "Smith"
        },
        "billingIdentity": {
            "emailAddress": "alex@test.com"
        }
    },
    "parameters": {
        "returnUrlSuccess": "https://www.mywebshop.com?status=success",
        "returnUrlCancelled": "https://www.mywebshop.com?status=cancelled",
        "returnUrlFailed": "https://www.mywebshop.com?status=failed"
    }
}

Payment status updates

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 notify you about a payment status update we send you a webhook. The body of the notification webhook includes the paymentJobReference and paymentReference. For example:

{
    "notifyType": "PaymentStatusChange",
    "paymentJobReference": "ExamplePaymentJobReference",
    "paymentReference": "ExamplePaymentReference"
}

If you have any IP or Country Blocking this can stop the notifications going through leading to transactions not being updated correctly.

Please ensure that Ireland is a Whitelisted Country and these IPs are whitelisted:

Production: 54.74.58.255 and 52.215.48.101
Integration: 54.75.5.171 and 54.73.83.234

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

To receive the payment status:

Extract the paymentJobReference and paymentReference from the notification webhook.
Include them in a RetrievePaymentJob API call.

When the payment status has been confirmed, your business systems can be updated to match.

Tip

For security reasons, we recommend that you update an order only when you receive the notification webhook from us.

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"

Mandatory parameters

Parameter

Description

paymentJobReference

integer($int64)

(path)

The reference of the payment job to retrieve.

paymentReference

integer($int64)

(path)

The reference of the payment to retrieve.

Optional parameters

Parameter

Description

configurationId

string (header)

Your configuration ID.

hash

string (query)

A hexadecimal sha512 hash of your password.

locale

string (query)

Determines the language that the Hosted Payment Page, and any related messages, is displayed in.

For example, to set the language to English, use the locale en-GB. Other options

el_GR (Greek)
en_US (US English)
nl_NL (Dutch)
es_ES (Spanish)

If your language is not available, please choose the most appropriate language for your shoppers.

Response codes

Response Indicator	Description
`200`	Payment retrieved successfully.
`400`	Request contains errors.
`401`	Invalid token.
`403`	Insufficient permissions.
`404`	Configuration, payment job or payment not found.

Reply to a notification

After receiving the confirmed paymentJobReference and paymentReference, the notification process ends, and 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.

If the response does not contain the expected 200 response code and message body, or if there is no response, the gateway keeps sending the same notification webhook for up to a month.

To reply to a notification webhook, send the 200 response with the paymentJobReference and the paymentReference, for example:

Testing your integration

To enable you to test your Hosted Payment Page before going live, we have an integration environment where you can simulate different payment scenarios. We also provide some test cards that you can use.

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

Important

You need different credentials for the integration and production environments.

The Cashflows integration environment

To simulate a card payment choose a simulation option:

Successful Payment
Failed Payment
Simulate Live Environment

To test your integration to our payment page, you need to send some payment requests to the integration environment (https://secure-int.cashflows.com/gateway/standard) using a valid card number.

Here are some test card numbers that you can use you to test your integration:

`cardNumber` value	Card Type	CVC	Expiry date
`4510400400099005`	Visa - Credit	123	Any future date within 10 years
`4510500400099002`	Visa - Credit	123	Any future date within 10 years
`4510800400099006`	Visa - Credit	123	Any future date within 10 years
`4000000000000002`	Visa - Credit	123	Any future date within 10 years
`8400182600000009`	Visa - Credit	123	Any future date within 10 years
`8400682600000008`	Visa - Debit	123	Any future date within 10 years
`8400682600011005`	Visa - Debit	123	Any future date within 10 years
`5400200400099009`	Mastercard - Credit	123	Any future date within 10 years
`5400300400099007`	Mastercard - Credit	123	Any future date within 10 years
`8500582600000009`	Mastercard - Credit	123	Any future date within 10 years
`5400100400099001`	Mastercard - Debit	123	Any future date within 10 years
`8500182600000008`	Mastercard - Debit	123	Any future date within 10 years
`340000000000009`	American Express - Credit	1234	Any future date within 10 years

If you enter some test card details and select Pay with card …, you’ll see our 3D Secure simulation page.

Using our 3D Secure simulator

Our 3D Secure simulator provides options for you to simulate different scenarios so that you can test, for example, whether a transaction passes or fails 3D Secure checks.

Authentication successful

Simulates a payment that has successfully passed all 3D Secure checks and will proceed to the authorisation stage of payment processing.

Authentication failed

Simulates the scenario where a shopper does not correctly complete 3D Secure checks. The payment will be declined by the gateway, and will not proceed to the authorisation stage of payment processing.

Authentication unavailable

Simulates the scenario where a card issuer’s system is not available. The response depends on how the gateway is configured in Cashflows Portal under the setting called 3D Secure Required.

If disabled, the payment will proceed to the authorisation stage of payment processing.

If enabled, the payment will be declined by the gateway. It will not proceed to the authorisation stage of payment processing.

Note

You or the business owner can choose to reject a payment if 3D Secure is unavailable.

Authentication attempted

Simulates the scenario where the 3D Secure system is available, but the card has not been enrolled for 3D Secure. The payment will proceed to the authorisation stage of payment processing.

Customise Appearance

If you want to customise the appearance of your Hosted Payment Pages, we recommend reading the Customise Appearance section in the full Hosted Payment Pages guide.

Going live

Before you can connect to our production environment for going live, you need:

A production account
Sign-in credentials

We provide these when your account has been approved. If you have not received these, email techsupport@cashflows.com.

Important

You need different credentials for the production environment. You can’t use your integration account credentials.

When you are satisfied that your integration is complete and working you can start processing live transactions by switching from the integration environment to the production environment.

You need to change your:

Configuration ID.
API key.
The URLs that point to the environments where you send your API messages. This means that you need to change the integration (test) URL from https://gateway-int.cashflows.com to https://gateway.cashflows.com for the production environment.

Important

Gateway notifications are sent from these two IP address: 54.74.58.255 and 52.215.48.101. Depending on your firewall settings, you may wish to whitelist them, as well as Ireland in your Geolocation settings.