Picture

Getting started - Online Payments

So that you can make the most of using our Cashflows Gateway and we can process payments in a way that gives shoppers a seamless experience, there are a few things that you need to tell us. This section explains how you can provide some of the details that we need via Cashflows Go. This section also explains how to collect the details that you need to be able to use our API.1.1 Authentication

  • Processing payments, including eCommerce, mail or telephone (MOTO) payments, and recurring payments 

  • Automating day-to-day tasks such as processing refunds and cancellations.  

  • Securely storing card details for a shopper’s online account or when they when they return to your website for future purchases 

  • Retrieving the full range of available payment methods that our gateway offers, for example CardPayPal and so on. This includes the logos and icons to display. If we add a payment method to the gateway, you can automatically offer it on a website checkout page without any extra development effort. 

Our Gateway API provides a structured and consistent way for you to send requests to our payment gateway. It includes calls for creating payment jobs, refunds and other payment-related operations. The Gateway API handles extensive validation and conversion for each request. It provides added security with built-in authentication and authorisation checks. 

Our API is REST-based. It accepts calls in JavaScript Object Notation (JSON). You can use different programming languages to create the JSON. Our API uses standard HTTP response codes and familiar verbs including: 

·       GET 
To retrieve a resource. 

·       POST 
To create new resources and sub-resources. 

·       PUT 
To update existing resources. 

·       PATCH 
To update existing resources. 

·       DELETE 
To delete existing resources.

What you need

You need access to Cashflows Go. Cashflows Go 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 your website with our gateway using the Gateway API

·       Tell us where to send the status updates after we have finished our payment processing.

When you first sign up with us, we send you a welcome email that includes the details that you need to sign into Cashflows Go. If you don’t know how to sign in, visit How to sign in to Cashflows Go on our website.

If you need an integration account for testing purposes, send an email request to 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, send an email to support@cashflows.com.

Collect your access credentials

Before you can use our API, you need to collect your API access credentials from Cashflows Go. This is where you can find:

·       Configuration ID
This is the unique identifier of the business account (also referred to as the merchant account). You need to include this in API messages so that we can recognise the business and match transactions to it.

·       Current API key
This is the key to use for encrypting API messages that you send us.

·       New API key
This is where you can always generate a new API key, for example if a previous key becomes compromised.

1.     Sign into Cashflows Go. If you don’t know how to sign in, visit How to sign in to Cashflows Go on our website.

2.     From the Cashflows Go menu, select Configuration.

Picture

3.     Select the API Data page.

Picture

The API Data page displays your API configuration details:

Picture

4.     Include the Configuration ID in any messages that you send to our API.

5.     Use the Current API key to encrypt the API messages that you send us.

Signing API calls 

All messages that we send are signed with a SHA512 hash. 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 gateway (a man-in-the-middle attack). 

To calculate the hash, append the message body to the API password, for example: <password><message body>. If the message body is empty, you only need to hash the password. 

The calculated hash is then converted to a hex-string and sent in the header with Hash: xxxxxx. It’s possible for the gateway to have two passwords at one time. When you change a password, you need to first create a new second password. When all systems have migrated to the new password, you can remove the first password. This way you can change a password without any downtime. 

As well as the hash, you must supply the configuration ID in the HTML header of each call to the gateway. The configuration ID enables the gateway to identify your application and recognise the configuration settings for your business. The header must be in the format: 

ConfigurationId: xxxxx. 
Hash:ExampleExampleExampleExampleExampleExampleExampleExampleExample ExampleExampleExampleExampleExampleExample 

 

Where should we redirect shoppers after payment processing?

After we finish processing their payments, shoppers are redirected back to your website.

Note: For MOTO payments, there is no redirection since there is no shopper to redirect. We process MOTO payments immediately.

We direct shoppers to a webpage according to the status of their payment (successful or failed). Alternatively, you can choose to display your own webpages. You just need to set the addresses (return URLs) of the pages that you want us to display instead. This section explains how to set the default return URLs in Cashflows Go.

Sometimes you might not want to use our default pages or your own. For example, if your business has more than one website for selling different things, you can override the default page. The shopper then returns to your website via a webpage that relates to their purchase rather than the default page. For information, see How to override a default return address (URL).

Note: For recurring payments, you don’t need to set up any return URLs.

You can specify a different page for each of the following scenarios:

·       Success: A shopper completes a successful transaction.
You can display a Thank You page and explain what happens next, when they can expect their delivery and so on.

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

·       Failed: A shopper fails to complete the payment process, for example because we (or their bank) did not approve it (the payment was declined).
You can display a page to explain what might have happened and give the shopper the opportunity to try again with a different payment method.

·       Cancelled: A shopper cancels their transaction
If the shopper cancels the transaction, you can display a confirmation page to tell them what happened and/or provide any additional transaction information such as order ID.

Where should we send payment status updates?

When we have processed a payment and the status changes, for example from Pending to Paid, we need to communicate this to your website. We use webhooks for this. A webhook is a way for one application to provide data to other applications as it happens (in real-time). This means that you receive data immediately. You don’t need to check for changes in payment status. Instead, we can notify you, as long as you tell us where to send the notification webhooks.

To tell us where to send notification webhooks:

1.     Sign into Cashflows Go. If you don’t know how to sign in, visit How to sign in to Cashflows Go on our website.

2.     From the Cashflows Go menu, select Configuration.

Picture

3.     Select the API Data page.

Picture

4.     Select Edit API Data.

5.     In the Notification section, add the Notification URL. This is the address where you would like us to send the notifications (webhooks). Here is an example.

Picture

6.     In the Notification section, add the Notification email address. This is the email address where you would like us to send emails if we need to tell you about any notifications (webhooks) that we couldn’t deliver or if anything needs to be configured differently. These emails are for whoever maintains the website. These are not customer-facing emails. Therefore, this should be a business email address, for example the email address of the business owner or person responsible for managing the website.

Picture

Transaction currencies

Our Cashflows Gateway supports a range of currencies in addition to Pound Sterling - GBP. For the full list of supported currencies, visit our website.

Note: We need to configure your business account to use other currencies. Please contact our Technical Support team or your account manager.

Sending us requests 

Requests need to be in the form of a HTTPS POST to either our integration or production environment: 

How do you want your Hosted Payment Page to look?

You can use the default Hosted Payment Page as it is or you can customise how it looks so that it matches the other pages of your website. You can find all of the customisation options in Cashflows Go.

To find out how to sign in, visit How to sign in to Cashflows Go on our website.

For information about what you can customise and how to do it, see How to customise a Hosted Payment Page.

How to send us the details of a payment

So that we can process an online payment via the Hosted Payment Page, 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.

We then send you the address of the Hosted Payment Page to display to the shopper. This page is where the shopper securely enters their card details or selects an alternative payment method such as PayPal. We can process the payment as soon as the details are submitted to us.

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