Remote Authentication Quick Start

This page will cover the basics of integrating with Cashflows using our Remote Authentication. To see more in-depth documentation see the general Remote Authentication guide. For advanced integrations or more technical solutions, see our API References.

Other integration options

There’s a Cashflows Gateway guide if you want a more generalised connection to Cashflows. We also have a plug-in for WooCommerce. If you’re a partner, we also have a Cashflows for Partners page dedicated to using Cashflows as a partner.

If you’d rather not handle payments directly, you can use the Hosted Payment Page (HPP). With Hosted Payment Pages you set up the hosted page via the Cashflows Portal, configure your branding, then link it to your application.

Setup

This section will cover actions you need to do, or information you need to collect, before integrating with Cashflows. If you have not yet set up a Cashflows account, contact us now.

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 use Remote Authentication 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:

  • To confirm your payment servers’ IP addresses by emailing implementations@cashflows.com

  • Your auth_id - your Merchant ID (MID)

  • Your auth_pass - your API Password

Your auth_id and auth_pass are provided when we create your account, if you have not received these, email implementations@cashflows.com.

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

Payment requests

To perform a Remote Authentication transaction, you need to:

  1. Send an authentication request with the necessary cardholder and payment details

  2. Process the response

Creating a authentication request

To create an authentication request you need to submit a UTF-8 encoded HTTPS POST request to:

Note

Before you can send payment requests you need to send our Implementations team the IP addresses of your payment servers so that we can configure your profile.

Payment request fields

To submit a payment request you need to send a request with the mandatory parameters. There are also additional, optional parameters you can include, see the API Reference for more information.

The parameters are:

Parameter

Description

Mandatory/Optional

auth_id

Your Profile Id

Mandatory

auth_pass

Authentication password

Mandatory

card_num

Customer’s card number (Must be numeric only with no separators)

Mandatory


(if no card_token)

card_token

Customer’s card token (Max of 50 characters)

Mandatory


(if no card_num)

card_cvv

Card security code

Mandatory

card_expiry

Card expiry date, format is MMYY

Mandatory

tran_ref

Your transaction reference (e.g. cart ID)

Mandatory

trans_desc

Your transaction description (Max of 99 characters)

Optional

tran_amount

Transaction amount to 2 decimal places, e.g. 24.99

Mandatory

tran_currency

Transaction currency (3-character code)

Mandatory

tran_testmode

Transaction test mode = 0

Mandatory

tran_type

Transaction type = sale

Mandatory

tran_recurrence

Used to override default MID settings:

  • sing - single transaction with no recurrence

  • subs - transaction in recurring subscription

  • inst - transaction in recurring instalment

  • unsc - unscheduled transaction, no fixed frequency or amount

  • card - cardholder initiated transaction with a stored card

Optional

tran_class

Transaction class = ecom, moto, or cont

Mandatory

retry_number

Indication of the number of retries attempts, 0 = initial attempt

Optional

descriptor

Soft descriptor added to your company name on the cardholder’s statement (Max of 12 characters)

Optional

return_token

If true the card_token will be included in the response only when we have processed a successful transaction

Optional

SCA_exemption_indicator

Indication of why the transaction may be exempt from SCA, possible values:

  • lowvalue = Applicable to transactions where amount is less than €30 or currency equivalent

  • lowrisk = transactions can be exempt from SCA provided they are low risk and below target fraud thresholds

Optional

cust_name

Customer’s name

Optional

cust_address

Customer’s address (Multiple lines can be separated using the new line break character (ASCII code 10))

Optional

cust_postcode

Customer’s post/zip/area code

Optional

cust_country

Customer’s country (ISO3166 2-character code)

Optional

cust_ip

Customer’s IP address (IPV4 Format only)

Optional

cust_email

Customer’s email address

Optional

cust_tel

Customer’s telephone number

Optional

Important

Although optional, not submitting the additional cardholder information may negatively impact both your transactions and anti-fraud measures.

Processing the response

Once the authentication request is sent, we will return a response containing details of the transaction, including whether the authorization was successful or not. You’ll need to handle this response in your backend system, logging the transaction status and storing any relevant details for future reference.

The response consists of:

  • Authorisation status code

  • Transaction ID

  • CVV/AVS result

  • Authorisation code

  • Authorisation message

  • Acquirer Reference Number (ARN)

Example response

{
  "status": "approved",
  "transactionId": "TX1234567890",
  "authCode": "654321",
  "amount": {
    "value": "100.00",
    "currency": "GBP"
  },
  "responseCode": "00",
  "responseDescription": "Approved"
}

CVV/AVS check values

CVV checks are enabled by default, however AVS needs to be opted into. If you wish to use AVS, email support@cashflows.com or contact your relationship manager. If AVS is not enabled a response of 00 will be sent.

The CVV/AVS result is a 3-digit value, each digit representing a different check. The first value is the CVV check, the second is the address and the third is the postcode. The possible values for each digit are as follows:

Value

Meaning

0

Not Checked

1

Check was not available

2

Full match

3

Partial match

4

Not matched

5

Error

A partial match is only possible for the address or postcode data, not for CVV check. Not all acquirers or issuers support all checks, in which case the results will be either 0 or 1.

Example Response

CVV

Address

Postcode

232

Full match

Partial match

Full match

400

Not matched

Not checked

Not checked

Testing your integration

You can test your Remote Auth integration by setting your POST request to the Integration environment (https://secure-int.cashflows.com/gateway/remote_auth) and using test cards details.

Note

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

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 - Credit

123

Any future date within 10 years

4510500400099002

Visa - Credit

123

Any future date within 10 years

4510800400099006

Visa - Credit

123

Any future date within 10 years

4000000000000002

Visa - Credit

123

Any future date within 10 years

8400182600000009

Visa - Credit

123

Any future date within 10 years

8400682600000008

Visa - Debit

123

Any future date within 10 years

8400682600011005

Visa - Debit

123

Any future date within 10 years

5400200400099009

Mastercard - Credit

123

Any future date within 10 years

5400300400099007

Mastercard - Credit

123

Any future date within 10 years

8500582600000009

Mastercard - Credit

123

Any future date within 10 years

5400100400099001

Mastercard - Debit

123

Any future date within 10 years

8500182600000008

Mastercard - Debit

123

Any future date within 10 years

340000000000009

American Express - Credit

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

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:

  • auth_id

  • auth_pass

  • 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/gateway/remote_auth to https://gateway.cashflows.com/gateway/remote_auth for the production environment.

Additional resources

For additional information, see the:

Contact and Support

If you need additional support please contact one of the below teams. Phone lines are open Monday to Friday between 09:00 and 17:00 UTC.

Application and account setup

For information relating to your application or technical implementation, please use the contact details below:

Account support

To assist you in your day-to-day running of your account, please use the contact details below: