Embedded Checkout

Embedded Checkout blends your website and checkout pages, but crucially Cashflows still host the payment field. We call these Embedded Fields.

Embedded Fields are a set of iFrames connecting your website with the Cashflows Gateway. When your customers arrive at the final checkout page of your website, a series of secure payment fields are displayed. This gives the impression that your business is capturing their card data while we take care of the processing, including security aspects and many of the technical complexities.

Introduction

Embedded Checkout offers:

  • The potential to accept all major types of card payment including Visa, Mastercard and Amex.

  • Handling of zero value authorisations and verifications.

  • The latest version of 3D Secure services from Visa and Mastercard are built in.

  • A downloadable industry-standard JavaScript library for easy integration and instant updates.

  • Pages that use Embedded Checkout are responsive and compatible with mobile devices.

  • Full customisation to match the look and feel of any website.

This means you can expect:

Fewer abandoned payments - Embedded checkouts can be customised to look and feel the same as any business website, encouraging customer confidence and reducing the number of abandoned payments.

More Speed - The longer a transaction takes and the more steps a customer needs to complete, the higher the chance a customer gives up and abandons a payment. With Embedded Checkout, the customer journey is quick.

Complete Control - Complete control over the checkout and payment page user interface and user experience without any worries over handling or exposing card details.

PCI compliance - Customers can safely enter their card details and pay with confidence.

How it works

  1. Embed each payment field within the checkout page as an embedded frame, each payment field will be injected with a frame by Cashflows.

Important

We recommend the checkout and payment page is kept separate from your shopping basket page.

  1. The customer then enters their payment details directly on the checkout page.

  2. After each field is completed, the data is sent directly to the Cashflows Gateway API where it is held securely in memory.

  3. After all required fields are completed and the customer presses the pay or verify button, the Cashflows Gateway concatenates the supplied payment data into a payment job request.

  4. The Cashflows Gateway sends this request either for authorisation or to the issuer’s bank to request the extra security checks in the form of Storing Customer Authentication (SCA).

  5. A JavaScript method is called and can be used to either:

    1. Display a success or failure message or

    2. Redirect the customer back to a website or web page that you specify.

Note

Embedded Checkout can only take the initial payment; further actions to a payment need to be made through the User Interface or with API calls.

If you want to use Embedded Checkout for mail or phone (MOTO) payment payments you need to include the isMoto flag, see the Cashflows Gateway guide.

Prerequisites

Before you start make sure you have:

Integrating Embedded Checkout

Your backend server needs to send an API request to our online payment servers to initiate your intent to create a transaction. We then send you a PaymentJobReference and the token which are linked to each other. You need to create the payment fields and the payment form and then link these to the Cashflows JavaScript Library to create and complete the payment request using this token.

Important

We recommend the checkout and payment page is kept separate from your shopping basket page.

The key steps to integrate embedded checkout are:

  1. Create a Payment Intent.

  2. Add the backend script.

  3. Download the JS Library and create a Cashflows object.

  4. Create the payment fields and payment form.

  5. initialise the Cashflows object.

Note

If you want to accept Apple Pay or Google Pay you need to enable them first.

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

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"
    },
}

Creating a payment intent

You first need to create a payment intent using an API call to the payment-intents endpoint:

If you need more information on payment intent calls see the Cashflows Gateway guide.

In your call you need to provide your API credentials (apiKey and configurationId) obtained from Cashflows Portal, as well as these mandatory fields.

Field

Description

amountToCollect

The total value of the payment transaction.

currency

The transaction currency.

paymentMethodsToUse

The payment type for the transaction.

You can also include address parameters, see Address and shipping data.

Example request:

{
    "amountToCollect": "10.00",
    "currency": "GBP",
    "locale": "en_GB",
    "paymentMethodsToUse": ["Card"]
}

Example response:

{
    "data": {
        "paymentJobReference": "Examplepaymentjobreference",
        "token": "yourpaymentintenttoken",
        "paymentStatus": "Pending"
    }
}

Address and shipping data

To help the authentication and authorisation process and reduce the number of declined transactions or related issues, we recommend that you supply as much cardholder data as possible. You can see a full list of accepted parameters in the API references.

Here is an example JSON payload showing billing and shipping address data. You should add this data to the parameters you hash and send when creating the Payment Intent.

"BillingAddress": {
    "Title": "Mr.",
    "FirstName": "Virgil",
    "MiddleName": "Van",
    "LastName": "Dijk",
    "CountryIso3166Alpha2": 826,
    "AddressLine1": "Business Centre Road",
    "AddressLine2": "Unit 7",
    "ZipCode": "XX12 1XX",
    "City": "TestCity",
    "StateProvince": null,
    "PhoneNumber1": "+44 9999 123456"
},
    "ShippingAddress": {
    "Title": "Mr.",
    "FirstName": "John",
    "MiddleName": null,
    "LastName": "Doe",
    "CountryIso3166Alpha2": 826,
    "AddressLine1": "Addressline1",
    "AddressLine2": "Addressline2",
    "ZipCode": "XX21 5XX",
    "City": "Cambridge",
    "StateProvince": null,
    "PhoneNumber1": "+44 9999 000000"
}

Adding the backend script

You need to include the backend script that creates and handles the Payment Intent within the header at the top of your checkout page. Here is an example to show how to create a HTML page using PHP:

<?php
include 'create_payment_intent_cashflows.php';
?>

<!DOCTYPE html>
<html>
...

Downloading the JavaScript library and creating a Cashflows object

To load the JavaScript library that creates the Cashflows object to your payment page you need to:

  1. Download the relevant JavaScript (JS) library from GitHub.

  2. Add the JS library to your Checkout Page where your payment fields will be rendered:

<script src = "JS library link path"></script>

Creating the payment fields and payment form

Next you need to create a form with the payment fields and payment button. You can use any names for these fields, but we suggest:

  • card-number

  • card-name

  • card-expiration

  • card-cvc

Example

<div class = "form-group">
    <label class = "form label" for "card-number"> Card Number </label>
    <input id = "card-number" type = "tel" class = "form control required"/>
</div>

You can use the div class and input IDs to style the payment fields within the payment form using styles from a cascading style sheet (CSS).

Initialising the Cashflows object

The last step is to initialise the Cashflows object at the bottom of the checkout page with the token acquired when creating the payment intent. This instructs the library to use the payment fields you created.

var cashflows = new Cashflows('yourpaymentintenttoken', true);
var inits = [
cashflows.initCard('#card-number', '#card-name', '#card- expiration', '#card-cvc', '#pay-with-card'),
];

The second argument in the cashflows variable is the isIntegration flag, if set to true your page will use the test environment.

Note

If you want to accept Apple Pay or Google Pay you need to initialise them separately with cashflows.initApplePay(`#apple-pay`) and cashflows.initGooglePay(`#google-pay`).

Example with both Apple Pay and Google Pay

<script>
window.onload = function() {

var cashflows = new Cashflows('yourpaymentintenttoken', true);
var inits = [
    cashflows.initCard('#card-number', '#card-name', '#card- expiration', '#card-cvc', '#pay-with-card'),
    cashflows.initApplePay('#apple-pay'), cashflows.initGooglePay('#google-pay')
];

Promise.all(inits)

.then(() => {
cashflows.checkout()

.then(() => {
var el = document.getElementById('card'); el.style.display = "none";
el = document.getElementById('alert-success'); el.style.display = "block";
})

.catch(e => {
var el = document.getElementById('card'); el.style.display = "none";
el = document.getElementById('alert-error'); el.style.display = "block"; el.querySelector('#message').innerHTML = e;
});
})

.catch(e => {
var el = document.getElementById('card'); el.style.display = "none";
el = document.getElementById('alert-error'); el.style.display = "block"; el.querySelector('#message').innerHTML = e;
});

}
</script>

If you’re adding Apple Pay you’ll also need to add in supporting CSS:

@supports (-webkit-appearance: -apple-pay-button) {
    .apple-pay-button {
        -webkit-appearance: -apple-pay-button;
        margin: 10px 10px 0 10px;
        -apple-pay-button-style: black;
        -apple-pay-button-type: plain;
        height: 40px;
        cursor: pointer;
    }
}

Testing and going live

To enable you to test your embedded checkout before going live, we have an integration environment where you can simulate different payment scenarios:

If you are testing card payments, you need to use a valid card number.

For more information about testing your integration and preparing to go live, see the Cashflows Gateway integration guide.

Enabling Apple Pay

To use Apple Pay with Embedded Checkout you need to have verified your Apple Pay Domain with Apple and enabled Apple Pay within Cashflows.

Verifying your Apple Pay Domain

To verify your Apple Pay Domain your need to host a domain verification file on your domain.

  1. Contact implementations@cashflows.com requesting Apple Pay verification files.

  2. Host the received files in the .well-known folder of your domain: https://[DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-association.

  3. Login to Cashflows Portal, then navigate to Configuration.

  4. Select Payment Methods, then select Card.

  5. Enable Allow Apple Pay in the configuration section:

  1. Select ApplePay Domains.

  2. Select Add Domain, enter your domain and select Save, this will automatically request Apple to check your domain.

Once Apple has approved your domain (usually after an hour), you will be able to take payments with Apple Pay through Embedded Checkout.

Adding an Apple Pay button

If you’re adding Apple Pay you’ll also need to add in supporting CSS:

@supports (-webkit-appearance: -apple-pay-button) {
    .apple-pay-button {
        -webkit-appearance: -apple-pay-button;
        margin: 10px 10px 0 10px;
        -apple-pay-button-style: black;
        -apple-pay-button-type: plain;
        height: 40px;
        cursor: pointer;
    }
}

Enabling Google Pay

Cashflows handles most of the work for Google Pay behind the scenes, to enable Google Pay in Embedded Checkout you need to:

  1. Login to Cashflows Portal, then navigate to Configuration.

  2. Select Payment Methods, then select Card.

  3. Enable Allow Google Pay in the configuration section:

  1. Register your Domain through the Google Business (https://pay.google.com/business/console/).

  2. Complete the Business Profile section.

  3. Complete the Google Pay API section.

  4. Select Add website and enter your website URL (domain that the Google Pay payment method will load on).

  5. Set the Google Pay API integration type to Gateway.

  6. Upload the required screenshots for Google to review: items on your website and the embedded checkout integration in showing the Google Pay payment method.

Note

Google Pay will only show for mobile devices.

  1. Save & Submit for Approval and wait for confirmation of your Merchant ID.

Once you have completed this you need to download the latest version of our library: https://github.com/Cashflows/cashflows-clientlib-js/releases.

You will need to make a change in the library to include your Merchant ID: self.initGooglePay = (targetEl, buttonOptions, {Your Google Merchant ID}).

Help on using the library can be found here https://github.com/Cashflows/cashflows-clientlib-js#basic-usage.

You are now setup for Google Pay on Embedded Checkout.

Enabling PayPal

To process PayPal payments, you first need to email support@cashflows.com to have PayPal enabled on your account. You also need a PayPal business account linked to your Cashflows account.

To link your PayPal business account to your Cashflows account:

  1. Sign in to Cashflows Portal.

Important

You must be signed in as an Owner to make configuration changes within the Cashflows portal.

  1. Log in and select Configuration.

  2. Select Payment Methods.

  3. Select PayPal.

  4. Select Connect PayPal account, follow the instructions if you don’t have a PayPal business account.

Important

Be sure to activate your account by confirming the email address used to create your PayPal account.

  1. Sign in to PayPal with your PayPal username and password.

When you return to Cashflows Portal, you will see the merchant ID that PayPal has assigned:

../_images/paypal_connect.PNG

  1. Select Save.

The changes take effect immediately but you also need to pass PayPal in the paymentMethodsToUse field:

"paymentMethodsToUse":
    [
        "Card",
        "PayPal"
    ],

To preview how PayPal appears on your payment page, you can either:

  • Use the Virtual Terminal to generate a payment link and open it in your browser, see the Virtual Terminal section for more information.

Or

  • Use Cashflows Portal and go to Configuration, then Hosted Checkouts, and click on any existing templates.

    ../_images/paypal_payment_page.PNG

Important

Your account needs to be enabled for sending Payment Links.