Embedded Checkout Quick Start

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.

Setup

This section will cover actions you need to do, or information you need to collect, before integrating with Cashflows.

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

Before integrating you’ll need:

• The correct user permissions

• To gather your API credentials

• To generate your signature

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

You need different credentials for the integration and production environments, to create an integration account for testing purposes contact implementations@cashflows.com.

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:

1. Sign into Cashflows Portal and select Configuration from the menu.

2. 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:

1. Select Generate a new API key to generate a new key.

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

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

Load the JavaScript library

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

The Cashflows Client Library for JavaScript can be installed with NPM. To install, simply add it to your package.json file:

{
    "dependencies": {
        "cashflows-clientlib-js": "^1.0.0"
    }
}

And run npm to update your dependencies with npm install.

Alternatively you can download the library directly:

1. Download the JavaScript library.

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

<script src = "[JavaScript library location]"></script>

Create a payment intent

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

• Integration environment: https://gateway-int.cashflows.com/api/gateway/payment-intents/

• Production environment: https://gateway.cashflows.com/api/gateway/payment-intents/

In your call you need to provide your API credentials (see above), 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 optional address parameters, see Address and shipping data in the full Embedded Checkout guide for more information.

Example request:

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

Example response:

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

Payment fields and initialisation

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>

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.

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:

1. Extract the paymentJobReference and paymentReference from the notification webhook.

2. 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 integration before going live, we have an integration environment where you can simulate different payment scenarios.

To test, send payments to https://secure-int.cashflows.com/gateway/.

Important

You need different credentials for the integration and production environments, to create an integration account for testing purposes contact implementations@cashflows.com.

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

Example: Simulating a Payment Request

{
  "type": "Payment",
  "paymentMethodsToUse": ["creditcard"],
  "parameters": {
    "cardNumber": "4111111111111111",
    "cardCvc": "123",
    "cardExpiryMonth": "06",
    "cardExpiryYear": "25",
    "cardHolderName": "Jane Doe"
  },
  "order": {
    "orderNumber": "TestPayment1"
  },
  "currency": "USD",
  "amountToCollect": "50.00"
}

Test cards

If you are testing card payments, you need to use a valid card number. Here are some test card numbers that you can use:

Click to show test cards

Test cards

cardNumber value	Card Type	CVC	Expiry date
4510400400099005	Visa	123	Any future date within 10 years
4510500400099002	Visa	123	Any future date within 10 years
4510800400099006	Visa	123	Any future date within 10 years
4000000000000002	Visa	123	Any future date within 10 years
5400100400099001	Mastercard	123	Any future date within 10 years
5400200400099009	Mastercard	123	Any future date within 10 years
5400300400099007	Mastercard	123	Any future date within 10 years
340000000000009	American Express	1234	Any future date within 10 years

Cardholder name

You can use specific values as the cardHolderName to trigger specific results for the test transaction:

cardHolderName value	Response
Luke Skywalker	Success response
Han Solo	Challenge response
Leia Skywalker	Decoupled challenge
Lando Calrissian	Not authenticated
Darth Maul	Not authenticated (with proof of authentication)
Darth Vader	Failed for technical reasons
Ben Kenobi	Rejected by issuer
Left blank	Failed response

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 successfully passing all 3D Secure checks and proceeds to the authorisation status.

• Authentication failed - simulates a customer incorrectly completing 3D Secure checks and proceeds to the declined status.

• Authentication unavailable - simulates a card issuer’s system being unavailable, depends on how the gateway is configured in Cashflows Portal.

• Authentication attempted - simulates the scenario where the 3D Secure system is available, but the card has not been enrolled for 3D Secure. The payment proceeds to the authorisation status.

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 implementations@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.

To make the switch, 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.