Getting started with the Cashflows Gateway API

What is the Cashflows Gateway API?

To enable you to connect your payment processing system with the Cashflows Gateway, we offer our Gateway API. By using our Gateway API, you can integrate with all of the functionality that comes with our gateway for processing online payments. We take care of many of the technical complexities. This can save you time and money.

Key features

With our API you can send us requests for:

• Creating payments and taking mail or telephone (MOTO) payments,

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

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

• Retrieving the full range of available payment methods that our gateway offers. 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.

The benefits of using our Gateway API

Benefits include:

• More ways to pay
  Our gateway API enables acceptance of major card types, including Visa, Mastercard, and American Express. We’re continually working to add new payment types to our gateway. The wider the range of payment methods that you can offer, the more business your website is likely to attract. Shoppers can pay the way they want to. As we add more payment options to the gateway, they automatically become available to you via a single API call. No hard coding. No extra development effort needed.

• Accepting payments in other currencies
  Our gateway supports a range of currencies as well as Pound Sterling - GBP.

• Standards
  Our gateway API is REST-based and uses recognisable methods. This makes it easy to learn and use.

• Security
  Our gateway ensures extensive validation and conversion for each transaction request. It also offers, as standard, an extra security layer with built-in 3-D Secure authentication and authorisation checks. Our gateway includes 3-D Secure services (up to version 2.2) from Visa (Verified by Visa) and Mastercard (SecureCode).

• Modern integration
  Our Cashflows Gateway uses the latest integration practices to provide security and flexibility. You can use the same Gateway API to implement a payment page that we host for you. For information, see Adding a Cashflows hosted payment page to a website (PDF).

• Integration environment for testing
  We have an API integration environment that you can use for testing. This does not affect any live data or interact with any external finance networks, for example banks.

Industry standards

Our Gateway API conforms to the OpenAPI Specification (OAS – formerly Swagger).

Our Gateway API accepts requests in JSON that can be generated in a variety of popular languages including PHP, cURL, Java, or .NET.

Our Gateway API is based on the REST (Representational State Transfer) architectural style. It uses standard HTTP response codes, authentication, and verbs.

Standard verbs

• GET
  Used to retrieve a resource.

• POST
  Used to create new resources and sub-resources.

• PUT
  Used to update existing resources.

• PATCH
  Used to update existing resources.

• DELETE
  Used to delete existing resources.

Standard response codes

Our gateway uses the following standardised codes in the responses that you receive. These codes tell you if a request was successful or not. A code that starts with 2 indicates success. A code that starts with 4 indicates an issue.

What you need

So that you can use our Gateway API, you need to collect your access credentials, so that you can prove your identity to the gateway and it can recognise the calls that you submit as genuine. We use API keys for this and they are available for you to collect from Cashflows Go.

Cashflows Go is your online account with Cashflows. 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.

Collect your access credentials

Before you can integrate your website with our gateway using the Gateway API you need a:

• 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.

To collect your access credentials from Cashflows Go

Before you can use our API, you need to collect your access credentials from Cashflows Go.

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.

3.     Select the API Data page.

The API Data page displays your API configuration details:

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.

To generate a new API key

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.

3.     Select the API Data page.

4.     Select Generate a new API key for migration.

A new key is generated for you and displayed on the screen.

5.     Wherever your integration uses the API key, replace the old key with the new one.

6.      Select Update API Key to replace your old key with the new one.

7.     When you have successfully updated all references to your API key with the newly generated one, check the box to confirm.

8.     Select Update API Key. The old key is replaced with the new one.

What you need to tell us

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. For information about how to do this, refer to the Cashflows Go Guide.

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.

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.

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 

Sending us requests 

When you are ready to send us payment requests, you can send using HTTPS to either our integration or production environment.

Here’s an example request to create a new payment job. You can use it to send us a test request.

POST https://gateway-int.cashflows.com/api/gateway/payment-jobs

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