Cashflows Gateway API

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.
This is a server-to-server call from your server to ours. 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 How to create a payment job.

2.     Receive the payment job details in the response to the payment job.
The API returns specific payment and order information plus a link (action URL) to determine the next stage of the payment processing. For card payments, the next step is usually 3-D Secure checking. Therefore, this link is likely to be a link to a 3-D Secure page. For information, see How to receive a response to a payment request and redirect a shopper.

3.     If 3-D Secure is enabled, use the link to direct the shopper to our 3-D Secure page where they can enter their extra security details. For information, see How to receive a response to a payment request and redirect a shopper.

How to create a payment job

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

·       Payment amount

·       Currency

·       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 required and optional fields, 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 your 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 shopper and delivery details in your payment request enables us to display this information in Cashflows Go, for example in the transaction details and reports. This can make it easier for you to locate payments and help with reconciliation. The extra detail can also help our Customer Support team to find a payment it ever needs investigating.

Additional details required for financial institutions

To comply with financial regulations, a payment request from a financial institution needs to include some extra information about the person who is receiving the funds. You need to include the extra details in the recipientDetails object when you create a new payment job, a MOTO payment job a parent payment job, or a recurring payment job.

Note: For MCC 6012 payments, we advise that you check the card type as credit cards are not accepted.

How to receive a response to a payment request and redirect a shopper

The gateway receives the payment request and responds with:

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

·       A link that points to the action URL where you should direct the shopper.

Here is an example with the action URL, (in this case a 3-D Secure page) highlighted.

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

To receive the response:

1.     For a card payment, extract the link (action URL) and use it to take you to the integration environment 3-D Secure simulation page:

Our 3-D Secure simulator provides options for you to simulate different scenarios so that you can test, for example, whether a transaction passes or fails 3-D Secure checks. For more information, see Using our 3-D Secure simulator.