Remote Authentication

Welcome to the Remote Authentication guide. This guide provides details on integrating into the Cashflows acquirer network. The Cashflows Remote Auth API is a mechanism that enables you to collect cardholder and transaction details within your gateway and to submit them directly to the Cashflows acquirer network for processing.

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.

Submit a payment request

To request a payment, you need to submit a HTTPS POST request with a description of the goods or services being purchased, the total cost, your Cashflows profile ID, the card details, and the cardholder’s details. The request must be UTF-8 encoded and submitted to:

Integration - https://secure-int.cashflows.com/gateway/remote_auth.
Production - https://secure.cashflows.com/gateway/remote_auth.

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.

Please contact techsupport@cashflows.com if you require an integration account.

Warning

Our payment services do not have fixed IP addresses and may change, so we recommend directing your requests to the DNS record of secure.cashflows.com.

Payment request parameters

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
`gateway_id_mc`	Sends your Merchant Partner Gateway ID (MPG ID) to Mastercard for identification (11 numeric characters) If you don’t know your MPG ID, contact support@cashflows.com	Mandatory on Mastercard transactions for Merchant Payment Gateways

Optional customer parameters:

Parameter	Description	Mandatory/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 above cardholder information may negatively impact both your transactions and anti-fraud measures.

If you’re using 3D Secure with Visa, Mastercard, or American Express, you must also include:

Parameters (3D Secure)

Description

acs_eci

The response from the 3DS server:

5 = VbyV - Full Authentication
6 = VbyV - Attempted Authentication
7 = VbyV - No Authentication
2 = MasterCard SecureCode - Full Authentication
1 = MasterCard SecureCode - Attempted Authentication
0 = MasterCard SecureCode - No Authentication
05 = American Express Safekey - Full Authentication
06 = American Express Safekey - Attempted Authentication
07 = American Express Safekey - No Authentication

acs_cavv

The Cardholder Authentication Verification Value from 3DS server, 28 Characters.

American Express Safekey – provide the American Express Verification Value (AEVV) – 20 characters long.

acs_dstransid

The universally unique transaction identifier assigned by the Directory Server (DS) to identify a single transaction, 36 characters. Required when acs_3dsversion = 2.1.0/2.2.0.

American Express Safekey – provide the American Express Safekey Transaction ID (XID) – 20 characters long.

If your MCC is 6012, 6051, or 7299 (financial institutions) you must also include:

Parameters (financial institutions)	Description
`primary_recipient_dob`	Customer’s Date of Birth. Format is YYYYMMDD (8 numeric characters)
`primary_recipient_surname`	Customer’s Surname or Last name (2-64-characters alpha characters, including -)
`primary_recipient_postcode`	Customer’s Postcode (2 to 16-characters alpha characters, including spaces)
`primary_recipient_account_number`	Customer’s Account Number (1 to 32 alpha numeric characters, including /-) For PAN Numbers: First 6 and Last 4

Example payments request

PYTHON

import requests

url = 'https://secure-int.cashflows.com/gateway/remote_auth/gateway/remote_auth'

data = {
    'auth_id': 'YOUR_AUTH_ID',
    'auth_pass': 'YOUR_AUTH_PASS',
    'card_num': '4510400400099005',
    'card_cvv': '123',
    'card_expiry': '1126',
    'cust_name': 'Mrs T Tester',
    'cust_address': 'testUserApi',
    'cust_postcode': 'TE456ST',
    'cust_country': 'GB',
    'cust_ip': '123.45.67.89',
    'cust_email': 'customer@example.com',
    'cust_tel': '01234567890',
    'tran_ref': 'testApi',
    'tran_amount': '200.00',
    'tran_currency': 'GBP',
    'tran_testmode': '0',
    'tran_type': 'sale',
    'tran_class': 'ecom',
    'acs_eci': '',
    'acs_cavv': '',
    'return_scheme_transaction_id' => '1',
    'submit': 'submit'
}

headers = {'Content-Type': 'application/x-www-form-urlencoded'}

response = requests.post(url, data=data, headers=headers)
print(response.text)

JAVA

import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.entity.*;
import java.util.*;

public class PaymentRequest {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClients.createDefault();
        HttpPost post = new HttpPost("https://secure-int.cashflows.com/gateway/remote_auth/gateway/remote_auth");

        List<NameValuePair> params = new ArrayList<>();
        params.add(new BasicNameValuePair("auth_id", "YOUR_AUTH_ID"));
        params.add(new BasicNameValuePair("auth_pass", "YOUR_AUTH_PASS"));
        params.add(new BasicNameValuePair("card_num", "4510400400099005"));
        params.add(new BasicNameValuePair("card_cvv", "123"));
        params.add(new BasicNameValuePair("card_expiry", "1126"));
        params.add(new BasicNameValuePair("cust_name", "Mrs T Tester"));
        params.add(new BasicNameValuePair("cust_address", "testUserApi"));
        params.add(new BasicNameValuePair("cust_postcode", "TE456ST"));
        params.add(new BasicNameValuePair("cust_country", "GB"));
        params.add(new BasicNameValuePair("cust_ip", "123.45.67.89"));
        params.add(new BasicNameValuePair("cust_email", "customer@example.com"));
        params.add(new BasicNameValuePair("cust_tel", "01234567890"));
        params.add(new BasicNameValuePair("tran_ref", "testApi"));
        params.add(new BasicNameValuePair("tran_amount", "200.00"));
        params.add(new BasicNameValuePair("tran_currency", "GBP"));
        params.add(new BasicNameValuePair("tran_testmode", "0"));
        params.add(new BasicNameValuePair("tran_type", "sale"));
        params.add(new BasicNameValuePair("tran_class", "ecom"));
        params.add(new BasicNameValuePair("acs_eci", ""));
        params.add(new BasicNameValuePair("acs_cavv", ""));
        params.add(new BasicNameValuePair("return_scheme_transaction_id", "1"));
        params.add(new BasicNameValuePair("submit", "submit"));

        post.setEntity(new UrlEncodedFormEntity(params));
        post.setHeader("Content-Type", "application/x-www-form-urlencoded");

        HttpResponse response = client.execute(post);
        System.out.println(EntityUtils.toString(response.getEntity()));
    }
}

C#

using System;
using System.Net.Http;
using System.Collections.Generic;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var client = new HttpClient();

        var values = new Dictionary<string, string>
        {
            { "auth_id", "YOUR_AUTH_ID" },
            { "auth_pass", "YOUR_AUTH_PASS" },
            { "card_num", "4510400400099005" },
            { "card_cvv", "123" },
            { "card_expiry", "1126" },
            { "cust_name", "Mrs T Tester" },
            { "cust_address", "testUserApi" },
            { "cust_postcode", "TE456ST" },
            { "cust_country", "GB" },
            { "cust_ip", "123.45.67.89" },
            { "cust_email", "customer@example.com" },
            { "cust_tel", "01234567890" },
            { "tran_ref", "testApi" },
            { "tran_amount", "200.00" },
            { "tran_currency", "GBP" },
            { "tran_testmode", "0" },
            { "tran_type", "sale" },
            { "tran_class", "ecom" },
            { "acs_eci", "" },
            { "acs_cavv", "" },
            { "return_scheme_transaction_id", "1" },
            { "submit", "submit" }
        };

        var content = new FormUrlEncodedContent(values);
        var response = await client.PostAsync("https://secure-int.cashflows.com/gateway/remote_auth/gateway/remote_auth", content);

        string responseString = await response.Content.ReadAsStringAsync();
        Console.WriteLine(responseString);
    }
}

NODEJSREPL

const axios = require('axios');
const qs = require('qs');

const data = qs.stringify({
auth_id: 'YOUR_AUTH_ID',
auth_pass: 'YOUR_AUTH_PASS',
card_num: '4510400400099005',
card_cvv: '123',
card_expiry: '1126',
cust_name: 'Mrs T Tester',
cust_address: 'testUserApi',
cust_postcode: 'TE456ST',
cust_country: 'GB',
cust_ip: '123.45.67.89',
cust_email: 'customer@example.com',
cust_tel: '01234567890',
tran_ref: 'testApi',
tran_amount: '200.00',
tran_currency: 'GBP',
tran_testmode: '0',
tran_type: 'sale',
tran_class: 'ecom',
acs_eci: '',
acs_cavv: '',
return_scheme_transaction_id: '1',
submit: 'submit'
});

axios.post('https://secure-int.cashflows.com/gateway/remote_auth/gateway/remote_auth', data, {
headers: {
    'Content-Type': 'application/x-www-form-urlencoded'
}
})
.then(response => {
console.log(response.data);
})
.catch(error => {
console.error('Error:', error.response ? error.response.data : error.message);
});

PHP

<?php
$data = http_build_query([
    'auth_id' => 'YOUR_AUTH_ID',
    'auth_pass' => 'YOUR_AUTH_PASS',
    'card_num' => '4510400400099005',
    'card_cvv' => '123',
    'card_expiry' => '1126',
    'cust_name' => 'Mrs T Tester',
    'cust_address' => 'testUserApi',
    'cust_postcode' => 'TE456ST',
    'cust_country' => 'GB',
    'cust_ip' => '123.45.67.89',
    'cust_email' => 'customer@example.com',
    'cust_tel' => '01234567890',
    'tran_ref' => 'testApi',
    'tran_amount' => '200.00',
    'tran_currency' => 'GBP',
    'tran_testmode' => '0',
    'tran_type' => 'sale',
    'tran_class' => 'ecom',
    'acs_eci' => '',
    'acs_cavv' => '',
    'return_scheme_transaction_id' => '1',
    'submit' => 'submit'
]);

$ch = curl_init('https://secure-int.cashflows.com/gateway/remote_auth/gateway/remote_auth');

curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

RUBY

require 'net/http'
require 'uri'

uri = URI.parse("https://secure-int.cashflows.com/gateway/remote_auth/gateway/remote_auth")

request = Net::HTTP::Post.new(uri)
request.set_form_data({
"auth_id" => "YOUR_AUTH_ID",
"auth_pass" => "YOUR_AUTH_PASS",
"card_num" => "4510400400099005",
"card_cvv" => "123",
"card_expiry" => "1126",
"cust_name" => "Mrs T Tester",
"cust_address" => "testUserApi",
"cust_postcode" => "TE456ST",
"cust_country" => "GB",
"cust_ip" => "123.45.67.89",
"cust_email" => "customer@example.com",
"cust_tel" => "01234567890",
"tran_ref" => "testApi",
"tran_amount" => "200.00",
"tran_currency" => "GBP",
"tran_testmode" => "0",
"tran_type" => "sale",
"tran_class" => "ecom",
"acs_eci" => "",
"acs_cavv" => "",
"return_scheme_transaction_id" => "1",
"submit" => "submit"
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end

puts response.body

Example payments response

A|01S0135FD47|200|AUTHOK|Authorised|MCC6830070529

Example payments request with 3DS

PYTHON

import requests

url = 'https://secure-int.cashflows.com/gateway/remote_auth/gateway/remote_auth'
payload = {
    'auth_id': 'YOUR_AUTH_ID',
    'auth_pass': 'YOUR_AUTH_PASS',
    'card_num': '4510400400099005',
    'card_cvv': '123',
    'card_expiry': '1126',
    'cust_name': 'Mrs T Tester',
    'cust_address': 'testUserApi',
    'cust_postcode': 'TE456ST',
    'cust_country': 'GB',
    'cust_ip': '123.45.67.89',
    'cust_email': 'customer@example.com',
    'cust_tel': '01234567890',
    'tran_ref': 'testApi',
    'tran_desc': 'Kerri Test',
    'tran_amount': '12.11',
    'tran_currency': 'GBP',
    'tran_testmode': '0',
    'tran_type': 'sale',
    'tran_class': 'ecom',
    'acs_eci': '5',
    'acs_cavv': 'AAABCAAhIXdRcEdRVyEhAAAAAAA=',
    'acs_xid': 'AgABBAACAAYABwAGAgQCAQgry0E=',
    'submit': 'submit'
}

response = requests.post(url, data=payload, headers={'Content-Type': 'application/x-www-form-urlencoded'})
print(response.text)

JAVA

import org.apache.http.client.methods.*;
import org.apache.http.impl.client.*;
import org.apache.http.entity.*;
import org.apache.http.message.*;
import java.util.*;

public class PaymentRequest {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClients.createDefault();
        HttpPost post = new HttpPost("https://secure-int.cashflows.com/gateway/remote_auth/gateway/remote_auth");

        List<NameValuePair> params = new ArrayList<>();
        params.add(new BasicNameValuePair("auth_id", "YOUR_AUTH_ID"));
        params.add(new BasicNameValuePair("auth_pass", "YOUR_AUTH_PASS"));
        params.add(new BasicNameValuePair("card_num", "4510400400099005"));
        params.add(new BasicNameValuePair("card_cvv", "123"));
        params.add(new BasicNameValuePair("card_expiry", "1126"));
        params.add(new BasicNameValuePair("cust_name", "Mrs T Tester"));
        params.add(new BasicNameValuePair("cust_address", "testUserApi"));
        params.add(new BasicNameValuePair("cust_postcode", "TE456ST"));
        params.add(new BasicNameValuePair("cust_country", "GB"));
        params.add(new BasicNameValuePair("cust_ip", "123.45.67.89"));
        params.add(new BasicNameValuePair("cust_email", "customer@example.com"));
        params.add(new BasicNameValuePair("cust_tel", "01234567890"));
        params.add(new BasicNameValuePair("tran_ref", "testApi"));
        params.add(new BasicNameValuePair("tran_desc", "Kerri Test"));
        params.add(new BasicNameValuePair("tran_amount", "12.11"));
        params.add(new BasicNameValuePair("tran_currency", "GBP"));
        params.add(new BasicNameValuePair("tran_testmode", "0"));
        params.add(new BasicNameValuePair("tran_type", "sale"));
        params.add(new BasicNameValuePair("tran_class", "ecom"));
        params.add(new BasicNameValuePair("acs_eci", "5"));
        params.add(new BasicNameValuePair("acs_cavv", "AAABCAAhIXdRcEdRVyEhAAAAAAA="));
        params.add(new BasicNameValuePair("acs_xid", "AgABBAACAAYABwAGAgQCAQgry0E="));
        params.add(new BasicNameValuePair("submit", "submit"));

        post.setEntity(new UrlEncodedFormEntity(params));
        post.setHeader("Content-Type", "application/x-www-form-urlencoded");

        HttpResponse response = client.execute(post);
        System.out.println(EntityUtils.toString(response.getEntity()));
    }
}

C#

using System;
using System.Net.Http;
using System.Collections.Generic;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var client = new HttpClient();

        var values = new Dictionary<string, string>
        {
            { "auth_id", "YOUR_AUTH_ID" },
            { "auth_pass", "YOUR_AUTH_PASS" },
            { "card_num", "4510400400099005" },
            { "card_cvv", "123" },
            { "card_expiry", "1126" },
            { "cust_name", "Mrs T Tester" },
            { "cust_address", "testUserApi" },
            { "cust_postcode", "TE456ST" },
            { "cust_country", "GB" },
            { "cust_ip", "123.45.67.89" },
            { "cust_email", "customer@example.com" },
            { "cust_tel", "01234567890" },
            { "tran_ref", "testApi" },
            { "tran_desc", "Kerri Test" },
            { "tran_amount", "12.11" },
            { "tran_currency", "GBP" },
            { "tran_testmode", "0" },
            { "tran_type", "sale" },
            { "tran_class", "ecom" },
            { "acs_eci", "5" },
            { "acs_cavv", "AAABCAAhIXdRcEdRVyEhAAAAAAA=" },
            { "acs_xid", "AgABBAACAAYABwAGAgQCAQgry0E=" },
            { "submit", "submit" }
        };

        var content = new FormUrlEncodedContent(values);
        var response = await client.PostAsync("https://secure-int.cashflows.com/gateway/remote_auth/gateway/remote_auth", content);

        string responseString = await response.Content.ReadAsStringAsync();
        Console.WriteLine(responseString);
    }
}

NODEJSREPL

const axios = require('axios');
const qs = require('qs');

const data = qs.stringify({
auth_id: 'YOUR_AUTH_ID',
auth_pass: 'YOUR_AUTH_PASS',
card_num: '4510400400099005',
card_cvv: '123',
card_expiry: '1126',
cust_name: 'Mrs T Tester',
cust_address: 'testUserApi',
cust_postcode: 'TE456ST',
cust_country: 'GB',
cust_ip: '123.45.67.89',
cust_email: 'customer@example.com',
cust_tel: '01234567890',
tran_ref: 'testApi',
tran_desc: 'Kerri Test',
tran_amount: '12.11',
tran_currency: 'GBP',
tran_testmode: '0',
tran_type: 'sale',
tran_class: 'ecom',
acs_eci: '5',
acs_cavv: 'AAABCAAhIXdRcEdRVyEhAAAAAAA=',
acs_xid: 'AgABBAACAAYABwAGAgQCAQgry0E=',
submit: 'submit'
});

axios.post('https://secure-int.cashflows.com/gateway/remote_auth/gateway/remote_auth', data, {
headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
})
.then(res => console.log(res.data))
.catch(err => console.error(err));
console.error('Error:', error.response ? error.response.data : error.message);
});

PHP

<?php
$data = http_build_query([
'auth_id' => 'YOUR_AUTH_ID',
'auth_pass' => 'YOUR_AUTH_PASS',
'card_num' => '4510400400099005',
'card_cvv' => '123',
'card_expiry' => '1126',
'cust_name' => 'Mrs T Tester',
'cust_address' => 'testUserApi',
'cust_postcode' => 'TE456ST',
'cust_country' => 'GB',
'cust_ip' => '123.45.67.89',
'cust_email' => 'customer@example.com',
'cust_tel' => '01234567890',
'tran_ref' => 'testApi',
'tran_desc' => 'Kerri Test',
'tran_amount' => '12.11',
'tran_currency' => 'GBP',
'tran_testmode' => '0',
'tran_type' => 'sale',
'tran_class' => 'ecom',
'acs_eci' => '5',
'acs_cavv' => 'AAABCAAhIXdRcEdRVyEhAAAAAAA=',
'acs_xid' => 'AgABBAACAAYABwAGAgQCAQgry0E=',
'submit' => 'submit'
]);

$ch = curl_init('https://secure-int.cashflows.com/gateway/remote_auth/gateway/remote_auth');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/x-www-form-urlencoded'
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

RUBY

require 'net/http'
require 'uri'

uri = URI.parse("https://secure-int.cashflows.com/gateway/remote_auth/gateway/remote_auth")

request = Net::HTTP::Post.new(uri)
request.set_form_data({
"auth_id" => "YOUR_AUTH_ID",
"auth_pass" => "YOUR_AUTH_PASS",
"card_num" => "4510400400099005",
"card_cvv" => "123",
"card_expiry" => "1126",
"cust_name" => "Mrs T Tester",
"cust_address" => "testUserApi",
"cust_postcode" => "TE456ST",
"cust_country" => "GB",
"cust_ip" => "123.45.67.89",
"cust_email" => "customer@example.com",
"cust_tel" => "01234567890",
"tran_ref" => "testApi",
"tran_desc" => "Kerri Test",
"tran_amount" => "12.11",
"tran_currency" => "GBP",
"tran_testmode" => "0",
"tran_type" => "sale",
"tran_class" => "ecom",
"acs_eci" => "5",
"acs_cavv" => "AAABCAAhIXdRcEdRVyEhAAAAAAA=",
"acs_xid" => "AgABBAACAAYABwAGAgQCAQgry0E=",
"submit" => "submit"
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end

puts response.body

Example payments with 3DS response

A|01S01356909|200|AUTHOK|Authorised

Submit an eWallet payment

We’ve increased our support for Cardholder Not Present transactions by introducing the eWallet type for transactions. New fields called ewallet and ewallet_type indicates to our system that an eWallet has been used.

With these fields, you can increase your understanding of which payment methods are being used within your business, to identify these transactions help your decisions. You can see this increased detail of payment types within your extracted reports and within the detail page of each transaction.

The supported digital are:

Apple Pay
Google Pay
Samsung Pay

To submit an eWallet payment you need to provide these parameters when submitting your payment:

Parameters	Description
`ewallet`	Indicates whether a Pay’s wallet was used: `true` `false`
`ewallet_type`	Indicates which Pay’s wallet was used, accepted values: (case_sensitive): `applepay` `googlepay` `samsungpay` `other`
`card_num`	Token (DPAN)
`card_expiry`	Token expiration date (MMYY)
`acs_cavv`	Cryptogram
`acs_eci`	Status

Void or refund a transaction

To void or refund a transaction you can either use the administration system or send a request to the Remote Auth API. To make the request through the API you need to submit a HTTPS POST with the desired transaction details. The request must be UTF-8 encoded and submitted to:

Integration - https://secure-int.cashflows.com/gateway/remote_auth.
Production - https://secure.cashflows.com/gateway/remote_auth.

Voiding a transaction stops it from being settled. If a transaction has already been settled, you’ll need to request a refund instead. To submit a void or refund request you need to send a request with the trans_type field set to either void or refund. You also need to provide the original transaction information, including the amount. To process a partial refund set the trans_amount to less than the original transaction amount.

Note

You cannot refund more than the original transaction value and are unable to complete a partial refund on the same day that the transaction was made.

Void and refund request parameters

Parameters	Description
`auth_id`	Your Profile Id
`auth_pass`	Authentication password
`tran_amount`	Transaction amount to 2 decimal places, e.g. 24.99
`tran_currency`	Transaction currency, 3-character code, e.g. GBP
`tran_testmode`	Transaction test mode. 0
`tran_type`	Transaction type = “refund” or “void”
`tran_class`	Transaction class = must match the original transaction class
`tran_orig_id`	Original transaction ID to be refunded or voided
`descriptor`	A soft descriptor that is added to your Company Name when displayed on the Cardholders statement (Max of 12 characters) (Optional)

Example void request

PYTHON

import requests

url = "https://secure-int.cashflows.com/gateway/remote_auth/gateway/remote_auth"
payload = {
    'auth_id': 'YOUR_AUTH_ID',
    'auth_pass': 'YOUR_AUTH_PASS',
    'tran_amount': '20.15',
    'tran_currency': 'GBP',
    'tran_testmode': '0',
    'tran_type': 'void',
    'tran_class': 'ecom',
    'tran_orig_id': '01S0135F74D',
    'retry_number': '0',
    'descriptor': 'Some descriptor'
}
headers = {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Cookie': 'AWSALB=...; AWSALBCORS=...'
}

response = requests.post(url, data=payload, headers=headers)
print(response.text)

JAVA

import org.apache.http.client.methods.HttpPost;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
import org.apache.http.message.BasicNameValuePair;

import java.util.*;

CloseableHttpClient client = HttpClients.createDefault();
HttpPost post = new HttpPost("https://secure-int.cashflows.com/gateway/remote_auth/gateway/remote_auth");

List<BasicNameValuePair> form = new ArrayList<>();
form.add(new BasicNameValuePair("auth_id", "YOUR_AUTH_ID"));
form.add(new BasicNameValuePair("auth_pass", "YOUR_AUTH_PASS"));
form.add(new BasicNameValuePair("tran_amount", "20.15"));
form.add(new BasicNameValuePair("tran_currency", "GBP"));
form.add(new BasicNameValuePair("tran_testmode", "0"));
form.add(new BasicNameValuePair("tran_type", "void"));
form.add(new BasicNameValuePair("tran_class", "ecom"));
form.add(new BasicNameValuePair("tran_orig_id", "01S0135F74D"));
form.add(new BasicNameValuePair("retry_number", "0"));
form.add(new BasicNameValuePair("descriptor", "Some descriptor"));

post.setEntity(new UrlEncodedFormEntity(form));
post.setHeader("Cookie", "AWSALB=...; AWSALBCORS=...");

var response = client.execute(post);
String responseBody = EntityUtils.toString(response.getEntity());
System.out.println(responseBody);
client.close();

C#

using System.Net.Http;
using System.Collections.Generic;

var client = new HttpClient();
var values = new Dictionary<string, string>
{
    { "auth_id", "YOUR_AUTH_ID" },
    { "auth_pass", "YOUR_AUTH_PASS" },
    { "tran_amount", "20.15" },
    { "tran_currency", "GBP" },
    { "tran_testmode", "0" },
    { "tran_type", "void" },
    { "tran_class", "ecom" },
    { "tran_orig_id", "01S0135F74D" },
    { "retry_number", "0" },
    { "descriptor", "Some descriptor" }
};

var content = new FormUrlEncodedContent(values);
client.DefaultRequestHeaders.Add("Cookie", "AWSALB=...; AWSALBCORS=...");
var response = await client.PostAsync("https://secure-int.cashflows.com/gateway/remote_auth/gateway/remote_auth", content);
string result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

NODEJSREPL

const axios = require('axios');
const qs = require('qs');

let data = qs.stringify({
'auth_id': 'YOUR_AUTH_ID',
'auth_pass': 'YOUR_AUTH_PASS',
'tran_amount': '20.15',
'tran_currency': 'GBP',
'tran_testmode': '0',
'tran_type': 'void',
'tran_class': 'ecom',
'tran_orig_id': '01S0135F74D',
'retry_number': '0',
'descriptor': 'Some descriptor'
});

axios.post('https://secure-int.cashflows.com/gateway/remote_auth/gateway/remote_auth', data, {
headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Cookie': 'AWSALB=...; AWSALBCORS=...'
},
maxBodyLength: Infinity
})
.then(res => console.log(res.data))
.catch(err => console.error(err));

PHP

<?php
$curl = curl_init();

$data = http_build_query([
    'auth_id' => 'YOUR_AUTH_ID',
    'auth_pass' => 'YOUR_AUTH_PASS',
    'tran_amount' => '20.15',
    'tran_currency' => 'GBP',
    'tran_testmode' => '0',
    'tran_type' => 'void',
    'tran_class' => 'ecom',
    'tran_orig_id' => '01S0135F74D',
    'retry_number' => '0',
    'descriptor' => 'Some descriptor'
]);

curl_setopt_array($curl, [
    CURLOPT_URL => "https://secure-int.cashflows.com/gateway/remote_auth/gateway/remote_auth",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $data,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/x-www-form-urlencoded",
        "Cookie: AWSALB=...; AWSALBCORS=..."
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;
?>

RUBY

require 'net/http'
require 'uri'

uri = URI.parse("https://secure-int.cashflows.com/gateway/remote_auth/gateway/remote_auth")
request = Net::HTTP::Post.new(uri)
request["Content-Type"] = "application/x-www-form-urlencoded"
request["Cookie"] = "AWSALB=...; AWSALBCORS=..."
request.set_form_data(
"auth_id" => "YOUR_AUTH_ID",
"auth_pass" => "YOUR_AUTH_PASS",
"tran_amount" => "20.15",
"tran_currency" => "GBP",
"tran_testmode" => "0",
"tran_type" => "void",
"tran_class" => "ecom",
"tran_orig_id" => "01S0135F74D",
"retry_number" => "0",
"descriptor" => "Some descriptor"
)

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end

puts response.body

Example void response

A|01V0135F755|000|-|Authorised

Example refund request

PYTHON

import requests

url = "https://secure-int.cashflows.com/gateway/remote_auth"
payload = {
    'auth_id': 'YOUR_AUTH_ID',
    'auth_pass': 'YOUR_AUTH_PASS',
    'tran_amount': '11.11',
    'tran_currency': 'GBP',
    'tran_testmode': '0',
    'tran_type': 'refund',
    'tran_class': 'ecom',
    'tran_orig_id': '01S0135F71A',
    'retry_number': '0',
    'descriptor': 'Some descriptor'
}
headers = {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Cookie': 'AWSALB=...; AWSALBCORS=...'
}

response = requests.post(url, data=payload, headers=headers)
print(response.text)

JAVA

import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.util.EntityUtils;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.message.BasicNameValuePair;

import java.util.*;

CloseableHttpClient client = HttpClients.createDefault();
HttpPost post = new HttpPost("https://secure-int.cashflows.com/gateway/remote_auth");

List<BasicNameValuePair> form = new ArrayList<>();
form.add(new BasicNameValuePair("auth_id", "YOUR_AUTH_ID"));
form.add(new BasicNameValuePair("auth_pass", "YOUR_AUTH_PASS"));
form.add(new BasicNameValuePair("tran_amount", "11.11"));
form.add(new BasicNameValuePair("tran_currency", "GBP"));
form.add(new BasicNameValuePair("tran_testmode", "0"));
form.add(new BasicNameValuePair("tran_type", "refund"));
form.add(new BasicNameValuePair("tran_class", "ecom"));
form.add(new BasicNameValuePair("tran_orig_id", "01S0135F71A"));
form.add(new BasicNameValuePair("retry_number", "0"));
form.add(new BasicNameValuePair("descriptor", "Some descriptor"));

post.setEntity(new UrlEncodedFormEntity(form));
post.setHeader("Cookie", "AWSALB=...; AWSALBCORS=...");

var response = client.execute(post);
String responseBody = EntityUtils.toString(response.getEntity());
System.out.println(responseBody);
client.close();

C#

using System.Net.Http;
using System.Collections.Generic;

var client = new HttpClient();
var form = new Dictionary<string, string>
{
    { "auth_id", "YOUR_AUTH_ID" },
    { "auth_pass", "YOUR_AUTH_PASS" },
    { "tran_amount", "11.11" },
    { "tran_currency", "GBP" },
    { "tran_testmode", "0" },
    { "tran_type", "refund" },
    { "tran_class", "ecom" },
    { "tran_orig_id", "01S0135F71A" },
    { "retry_number", "0" },
    { "descriptor", "Some descriptor" }
};

var content = new FormUrlEncodedContent(form);
client.DefaultRequestHeaders.Add("Cookie", "AWSALB=...; AWSALBCORS=...");
var response = await client.PostAsync("https://secure-int.cashflows.com/gateway/remote_auth", content);
string result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

NODEJSREPL

const axios = require('axios');
const FormData = require('form-data');

let data = new FormData();
data.append('auth_id', 'YOUR_AUTH_ID');
data.append('auth_pass', 'YOUR_AUTH_PASS');
data.append('tran_amount', '11.11');
data.append('tran_currency', 'GBP');
data.append('tran_testmode', '0');
data.append('tran_type', 'refund');
data.append('tran_class', 'ecom');
data.append('tran_orig_id', '01S0135F71A');
data.append('retry_number', '0');
data.append('descriptor', 'Some descriptor');

axios.post('https://secure-int.cashflows.com/gateway/remote_auth', data, {
headers: {
    ...data.getHeaders(),
    'Content-Type': 'application/x-www-form-urlencoded',
    'Cookie': 'AWSALB=...; AWSALBCORS=...'
},
maxBodyLength: Infinity
})
.then(res => console.log(res.data))
.catch(err => console.error(err));

PHP

<?php
$curl = curl_init();

$data = http_build_query([
    'auth_id' => 'YOUR_AUTH_ID',
    'auth_pass' => 'YOUR_AUTH_PASS',
    'tran_amount' => '11.11',
    'tran_currency' => 'GBP',
    'tran_testmode' => '0',
    'tran_type' => 'refund',
    'tran_class' => 'ecom',
    'tran_orig_id' => '01S0135F71A',
    'retry_number' => '0',
    'descriptor' => 'Some descriptor'
]);

curl_setopt_array($curl, [
    CURLOPT_URL => "https://secure-int.cashflows.com/gateway/remote_auth",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $data,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/x-www-form-urlencoded",
        "Cookie: AWSALB=...; AWSALBCORS=..."
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;
?>

RUBY

require 'net/http'
require 'uri'

uri = URI.parse("https://secure-int.cashflows.com/gateway/remote_auth")
request = Net::HTTP::Post.new(uri)
request["Content-Type"] = "application/x-www-form-urlencoded"
request["Cookie"] = "AWSALB=...; AWSALBCORS=..."
request.set_form_data(
"auth_id" => "YOUR_AUTH_ID",
"auth_pass" => "YOUR_AUTH_PASS",
"tran_amount" => "11.11",
"tran_currency" => "GBP",
"tran_testmode" => "0",
"tran_type" => "refund",
"tran_class" => "ecom",
"tran_orig_id" => "01S0135F71A",
"retry_number" => "0",
"descriptor" => "Some descriptor"
)

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end

puts response.body

Example request response

A|01R0135F71B|000|-|Authorised

Credit transfers

If you have Credit Transfers enabled, you can use the Remote Auth API to make a credit transfer request. To request a credit transfer, submit a HTTPS POST with the amount that you wish to credit. The request must be UTF-8 encoded and submitted to:

Integration - https://secure-int.cashflows.com/gateway/remote_auth.
Production - https://secure.cashflows.com/gateway/remote_auth.

Credit transactions are only supported for these MCCs:

5262 – Marketplaces
6010 - Financial Institutions – Manual Cash Disbursements
6011 - Financial Institutions – Automated Cash Disbursements
6012 - Financial Institutions – Merchandise, Services, and Debt Repayment
6300 - Insurance Sales, Underwriting, and Premiums
6399 - Insurance, Not Elsewhere Classified
7994 - Game of skill
7995 - Gambling
8999 - Professional Services (Not Elsewhere Classified)

Contact your account manager to confirm if Credit Transfers have been enabled on your account.

To protect credit transfers whilst being transferred you must include a cryptographic hash digital signature.

The digital signature or ‘message digest’ must be created by your own server-side scripting using the SHA256 algorithm method and contain the following values:

tran_type:tran_amount:tran_currency:tran_orig_id:tran_ref:security_hash

For Visa card Credit Transfers, where tran_orig_id is not supplied in the request, this parameter must be omitted from the hash string:

tran_type:tran_amount:tran_currency:tran_ref:security_hash

Each section of data is separated using a ‘:’ (colon) character, and data must be organised in the exact sequence shown.

The ‘message digest’ can then be included in your credit transfer request using the security_hash parameter.

We compare the ‘message digest’ against our own ‘message digest’ created from the supplied credit. As only you and the Cashflows know the security_hash element of the ‘message digest’, the credit transfer will only be processed if the two ‘message digest’ match.

Warning

At no time should the pre-set security_hash be included in any FORM or web page that is held on your server.

Credit transfer request parameters

To submit a credit transfer 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 mandatory parameters are:

Parameters	Description
`auth_id`	Your Profile Id
`auth_pass`	Authentication password
`tran_amount`	Credit Transfer amount to 2 decimal places, e.g. 24.99 (The currency symbol must not be included)
`tran_currency`	Transaction currency, 3-character code, e.g. GBP
`tran_ref`	Your transaction reference (e.g. cart ID)
`tran_testmode`	Transaction test mode. 0
`tran_type`	Transaction type = credit
`tran_class`	Transaction class = cred
`tran_orig_id`	Mandatory for Mastercard. Optional for Visa (where card_num or card_token is provided) Original transaction id to which the credit will be applied to.
`card_num`	Visa only: Customer’s card number (Must be numeric only with no separators) (Conditional, not required if `tran_orig_id` or `card_token` is provided)
`card_token`	Visa only: Customer’s card token (Max of 50 characters) (Conditional, not required if `card_num` or `tran_orig_id` is provided)
`security_hash`	A security Hash value used to ensure that no-one has tampered with the credit transfer request

Example credit transfer request

Example of the POST string sent in the Credit Transfer request to the Remote Auth API for administration:

auth_id=1234&auth_pass=Password&tran_amount=9.99&tran_currency=GBP&tran_testmode=0&tran_type=credit&tran_class=cred&tran_orig_id=01S0001234&security_hash=e5446ea59340d867af9fed6ba92f267e17d0119c7d972d7d84c0ab31ee4b1708

Release a transaction

Before the funds of a transaction are requested from the bank it is possible on the date of the transaction to place them On Hold for up to 7 days.

To release transactions that have been placed on hold you need to send a MIME multipart POST request to the Remote Auth API. The request must be UTF-8 encoded and submitted to:

Integration - https://secure-int.cashflows.com/gateway/remote_auth.
Production - https://secure.cashflows.com/gateway/remote_auth.

Warning

If the transaction is not released within the 7 days, it will expire and will need to be authorised again.

The POST request contains two parts, the first includes instructions to the system for your batch request, and the second includes the attachment with transaction references that you want releasing from hold.

These are the parameters used in the first part of a batch release request to the Remote Auth API:

Parameters	Description
`profile_id`	Your Profile Id
`profile_pass`	Authentication password
`batch_op`	Type of Batch operation. For a batch release request the value must be `onhold-release-submit`
`attached_type`	Defines the format of the attachment. This must be set to `onhold_v0`

The second part of the POST header contains the batch file containing all the transaction references that you wish to release. The batch file must be in either a .csv or .txt format as specified in the request’s Content-Disposition filename.

Example batch release request

Example of the POST header sent in the batch release request to the Remote Auth API for administration:

Content-Type: application/x-www-form-urlencoded profile_id=73&profile_pass=password1234&attached_type=onhold_v0&batch_op=onhold-release-submit

The last part of the POST contains the details of the attachment that includes the transaction reference that you wish to release:

Content-Type: text/csv
Content-Disposition: attachment; filename="releaseRefs.csv" 01S00001724 01S00001725 01S00001726

Batch release response

After you have sent a batch release request, the response will contain one of following results:

Parameters	Description
`invalid_request`	Error – Request cannot be parsed correctly
`invalid_credentials`	Error – Cannot verify the profile id or authentication password
`request_toobig`	Error – The batch request is larger than 64k for the Content-Length
`invalid_filename`	Error – The attachment filename is not valid
`internal_failure`	Error – There has been an internal error, please try again
`release_report`	Success – The batch request has been successfully uploaded and a batch Id has been created.

Example batch release request responses

Example of an invalid request response:

Content-Type: application/x-www-form-urlencoded result=invalid_request

Example of a response for a successful batch release request:

Content-Type: application/x-www-form-urlencoded result=release_report&batch_id=26&batch_status=pending

When a batch release request has been successfully uploaded the response will display a batch id number enabling you to query the status of the batch after the initial request.

Batch release query request

After uploading your batch release file, the system takes around 5 minutes to complete the release of the transactions, depending on file size. You can periodically poll the service using a batch release POST query request to query the status of a request.

To submit a batch release query request, POST parameters to the Remote Auth API:

Parameters	Description
`profile_id`	Your Profil Id
`profile_pass`	Authentication password
`batch_id`	The Id of the batch that you wish to query
`batch_op`	Type of Batch operation. For a batch release query request the value must be `onhold-release-query`

Example batch release query request

Example of the POST header sent in the batch release query request to the Remote Auth API:

POST /admin/remote_batch HTTP/1.0
Content-Type: multipart/x-vcg-remote-api; boundary=_partBoundary_ Content-Length: 172

--_partBoundary_
Content-Type: application/x-www-form-urlencoded profile_id=73&profile_pass=password1234&batch_id=26&batch_op=onhold-release-query
--_partBoundary_--

Batch release query response

After you have sent a batch release query, the response will contain one of following results:

Query results	Description
`invalid_request`	Error – Request cannot be parsed correctly
`invalid_credentials`	Error – Cannot verify the profile id or authentication password
`internal_failure`	Error – There has been an internal error, please try again
`release_notfound`	Error – Cannot find the requested batch Id
`release_report`	Success – The batch query request has been successfully submitted and a batch has been found

If the query was successfully submitted (i.e., result=release_report) the response will return a batch_id and batch_status of either pending, processing or complete. If the status of the batch is ‘complete’, the following additional information and an attachment providing status of each of the transactions will be included in the multipart response:

Batch complete parameters	Description
`item_count`	Total number of items in the batch release
`item_succ`	Number of transactions that have been successfully released
`item_fail`	Number of transactions that have failed and not been released
`attachment_type`	Defines the format of the attachment

In the attachment part of the multipart response each transaction will contain one of the following results:

Transaction results	Description
`batchrel_notonhold`	The transaction was not on hold at the time of the request as the transaction has been previously released and may have been already settled
`batchrel_invalref`	The transaction could not be found as it has an invalid reference
`batchrel_expired`	The transaction has expired and therefore has not been sent of authorisation
`batchrel_error`	There was an internal error, please resubmit this transaction release request
`batchrel_ok`	The transaction has been successfully released for authorisation

Example of the multipart response you receive for a successful batch release query request. The first part of the response shows the details of the successfully query:

--remote_batch-4C4106B0
Content-Type: application/x-www-form-urlencoded result=release_report&batch_id=26&batch_status=complete&item_count=4&item_succ=4&item_fail=0&attached_type=onhold_v0

The final part of the multipart response shows the results of each of the transactions that were requested to be released:

--remote_batch-4C4106B0
    Content-Type: text/csv 01S00001724,batchrel_expired 01S00001725,batchrel_ok 01S00001726,batchrel_ok
    --remote_batch-4C4106B0-

Account Verification ID

To submit a recurring payment, you need to first get an initial account verification of a customer’s card details (including the CVV), or use an existing ecom or moto sale. The request is then checked, and if successful, authorised. The card details are then securely held in our PCI approved systems and a request response sent to you with an Account Verification ID.

Account verification request parameters

To submit an account verification 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 mandatory parameters are:

Parameter	Description
`auth_id`	Must be set to the Profile ID
`auth_pass`	Authentication password
`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)
`tran_ref`	Your transaction reference (e.g. cart ID)
`tran_desc`	Your transaction description (Optional)
`tran_amount`	Transaction amount to 2 decimal places, e.g. 24.99 (The currency symbol must not be included)
`tran_currency`	Transaction currency, 3-character code
`tran_testmode`	Transaction test mode. 0
`tran_type`	Transaction type = sale
`tran_class`	Transaction class = cont
`tran_orig_id`	Verification ID or Sales ID (e.g. 05P00001724 or 06S00001724)
`retry_number`	Indication of the number of retries attempts, 0 = initial attempt
`return_acq_ref`	If not Null the Acquirer Reference Number (ARN) will be included in the response only when we have processed a live payment
`descriptor`	A soft descriptor that is added to your Company Name when displayed on the Cardholders statement. (Max of 12 characters) (Optional)
`tran_recurrence`	To be 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 with a stored card card = Cardholder initiated transaction with a stored (Optional)
`SCA_exemption_indicator`	Indication of why the transaction may be exempt from SCA, possible values: Recurring = Applicable to transactions where recurrence type = ‘subs’ or ‘inst’ MerchantInitiated = Applicable to merchant-initiated transactions where recurrence type = ‘sing’ or ‘unsc’ (Optional)

If you’re using 3D Secure with Visa, Mastercard, or American Express, you must also include:

Parameters (3D Secure)

Description

acs_eci

The response from the 3DS server:

5 = VbyV - Full Authentication
6 = VbyV - Attempted Authentication
7 = VbyV - No Authentication
2 = MasterCard SecureCode - Full Authentication
1 = MasterCard SecureCode - Attempted Authentication
0 = MasterCard SecureCode - No Authentication
05 = American Express Safekey - Full Authentication
06 = American Express Safekey - Attempted Authentication
07 = American Express Safekey - No Authentication

acs_cavv

The Cardholder Authentication Verification Value from 3DS server, 28 Characters.

American Express Safekey – provide the American Express Verification Value (AEVV) – 20 characters long.

acs_dstransid

The universally unique transaction identifier assigned by the Directory Server (DS) to identify a single transaction, 36 characters. Required when acs_3dsversion = 2.1.0/2.2.0.

American Express Safekey – provide the American Express Safekey Transaction ID (XID) – 20 characters long.

If your MCC is 6012, 6051, or 7299 (financial institutions) you must also include:

Parameters (financial institutions)	Description
`primary_recipient_dob`	Customer’s Date of Birth. Format is YYYYMMDD (8 numeric characters)
`primary_recipient_surname`	Customer’s Surname or Last name (2-64-characters alpha characters, including -)
`primary_recipient_postcode`	Customer’s Postcode (2 to 16-characters alpha characters, including spaces)
`primary_recipient_account_number`	Customer’s Account Number (1 to 32 alpha numeric characters, including /-) For PAN Numbers: First 6 and Last 4 (Never include full PAN in primary_recipient_account_number field.)

Example account verification request (with card number)

Example of the POST string sent in the account verification request to the API for authorisation:

auth_id=1234&auth_pass=Password&card_num=4000000000000002&card_cvv=123&card_expiry=0121&cust_name=Testing&cust_address=My%20house%0AMy%20street%0AMy%20Town&cust_postcode=CB22%205LD&cust_country=GB&cust_ip=123.45.67.89&cust_email=test@test.com&tran_ref=abc123&tran_currency=GBP&tran_testmode=0&tran_type=verify&tran_class=ecom

Example account verification request (with card token)

Example of the POST string sent in the account verification request to the API for authorisation:

auth_id=1234&auth_pass=Password&card_token=1000000000030419&card_cvv=123&card_expiry=0121&cust_name=Testing&cust_address=My%20house%0AMy%20street%0AMy%20Town&cust_postcode=CB22%205LD&cust_country=GB&cust_ip=123.45.67.89&cust_email=test@test.com&tran_ref=abc123&tran_currency=GBP&tran_testmode=0&tran_type=verify&tran_class=ecom

Note

An Account Verification request checks if the account is valid, it will not perform a check for available funds on the account and is not an authorisation of a sale.

Example account verification response

Example of the account verification response sent to you after submitting an account verification request:

Example response	Meaning
A\|05P00001724\|232\|031971\|Authorised	Authorised: A Account Verification Id: 05P00001724 CVV/AVS:232 Authorisation code: 031971

This includes the Account Verification ID denoted with a 05P prefix and the CVV/AVS check response. A continuous authorised payment request can only be performed where the CVV comparison check has been returned as a MATCH (i.e. the first check value must be a 2), irrespective of the authorisation status of the Account Verification.

Recurring/continuous payments

You can submit a recurring payment using an approach called continuous authority. When sending a continuous (recurring) payment request you must include an Account Verification ID to enable us to use the initially stored card details.

Setting up a recurring/continuous payment

When sending a continuous (recurring) payment request you must always include the Account Verification ID to enable us to use the initially stored card details to send the payment for authorisation.

Recurring/continuous payment request parameters

To send a recurring payment request you must exclude the card_num (or card_token), card_expiry, and card_cvv parameters, and include the tran_orig_id which has the value of initial verification or sale Id. The following table lists the continuous payment request parameters that must be passed to the API. There are also additional, optional parameters you can include, see the API Reference for more information.

The mandatory parameters are:

Parameter	Description
`auth_id`	Must be set to the Profile ID
`auth_pass`	Authentication password
`tran_ref`	Your transaction reference (e.g. cart ID)
`tran_amount`	Transaction amount to 2 decimal places, e.g. 24.99 (The currency symbol must not be included)
`tran_currency`	Transaction currency, 3-character code
`tran_testmode`	Transaction test mode. 0
`tran_type`	Transaction type = sale
`tran_class`	Transaction class = cont
`tran_orig_id`	Verification ID or Sales ID (e.g. 05P00001724 or 06S00001724)
`scheme_transaction_id`	ID provided by Acquirers and if the original transaction was processed via another Acquirer, they will need to obtain the id from them Note – Mandatory if tran_orig_id is not provided, if using an Acquirer other than Cashflows you can obtain the ID from them
`retry_number`	Indication of the number of retries attempts, 0 = initial attempt (For more information see Retry Handing)
`return_acq_ref`	If not Null the Acquirer Reference Number (ARN) will be included in the response only when we have processed a live payment.
`SCA_exemption_indicator`	Indication of why the transaction may be exempt from SCA, possible values: Recurring = Applicable to transactions where recurrence type = ‘subs’ or ‘inst’ MerchantInitiated = Applicable to merchant-initiated transactions where recurrence type = ‘sing’ or ‘unsc’ (Optional)

If your MCC is 6012, 6051, or 7299 (financial institutions) you must also include:

Parameters (financial institutions)	Description
`primary_recipient_dob`	Customer’s Date of Birth. Format is YYYYMMDD (8 numeric characters)
`primary_recipient_surname`	Customer’s Surname or Last name (2-64-characters alpha characters, including -)
`primary_recipient_postcode`	Customer’s Postcode (2 to 16-characters alpha characters, including spaces)
`primary_recipient_account_number`	Customer’s Account Number (1 to 32 alpha numeric characters, including /-) For PAN Numbers: First 6 and Last 4 (Never include full PAN in primary_recipient_account_number field.)

Example continuous payment request

Example of the POST string sent in the continuous payment request to the Remote Auth API for authorisation:

auth_id=1234&auth_pass=Password&cust_name=Testing&cust_address=My%20house%0AMy%20street%0AMy%20Town&cust_postcode=CB22%205LD&cust_country=GB&cust_ip=123.45.67.89&cust_email=test@test.com&tran_ref=abc123&tran_amount=9.99&tran_currency=GBP&tran_testmode=0&tran_type=sale&tran_class=cont&tran_orig_id=05P00001724

Authorisation response code

The response consists of:

Authorisation status code
Transaction ID
CVV/AVS result
Authorisation code
Authorisation message
Acquirer Reference Number (ARN)

These fields are separated using the vertical bar character. An authorisation status of A indicates that the transaction was authorised, anything else indicates that it was not.

Example Response	Meaning
A\|01S00001724\|232\|031971\|Authorised\|74698692333601146452212\|1000000000030419	Authorised: A Transaction Id: 01S00001724 CVV/AVS:232 Authorisation code: 031971 Authorisation Request Response: 74698… Card token: 1000000000030419
D\|01S00001723\|400\|D102\|Not Authorised\|74698692333601146452212	Not authorised: D Transaction Id: 01S00001723 CVV/AVS:400 Authorisation Request Response: 74698…
V\|99E5D84B40F\|000\|V226\|Invalid request	Invalid request: V Transaction Id: 99E5D84B40F CVV/AVS:000
B\|01S00632BE2\|000\|D090\|Not authorised	Blocked: D Transaction Id: 01S00632BE2 CVV/AVS:000

CVV/AVS check values

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

Retry handling

If there are any network, timing, or connection issues our system will return a response code informing you of the issue.

If you receive any of the following response codes, you should retry your authorisation request as the retry will return a different response to the original request:

S201: API to gateway connect fail
S203: API layer timeout
V249: Duplicate transaction still processing

If the system was unable to send the request of authorisation you will be returned the following response codes:

S001 or S101: Connection failure

In this case you can resubmit authorisation request without risk of double authorisation.

If the system cannot determine whether an attempted authorisation was successful or not, the system will return the following response codes:

S003 or S103: Response Timeout
S002 or S102: Invalid response

For the full list of response codes, see API Reference.

Sending a retry request

To submit a retry request, enter a value greater than zero into the retry_number parameter and resubmit the authorisation request.

Note

For this functionality to work correctly, all transactions must have a unique tran_ref and must be submitted within 5 minutes of the initial authorisation request.

When our system receives a retry request, you will be presented with one of these results:

If the retry request is a duplicate request of a finished transaction, then the original transaction response is returned.
If original transaction is still being processed, you will receive the V249 response code.
If our system has no record of a previous duplicate transaction request, then the transaction is processed, and the results returned.

Card on file / CV2less payments

A card-on-file transaction helps provide seamless online or in-app transactions in a cardholder-initiated transaction without the need of a CVV check.

Initial transaction requirements

Parameter	Requirement
`tran_recurrence`	`card`
`tran_type`	`sale` or `verify`
`tran_class`	`ecom`
`card_num`	Mandatory if no `card_token`
`card_token`	Mandatory if no `card_num`
`card_cvv`	Mandatory
`card_expiry`	Mandatory
`using_stored_credentials`	`false`
`return_token`	`true`
`acs_3dsversion`	Mandatory
`acs_eci`	Mandatory
`acs_cavv`	Mandatory
`acs_dstransid`	Mandatory

Subsequent transaction requirements

Parameter	Requirement
`tran_recurrence`	`card`
`tran_type`	`sale`
`tran_class`	`ecom`
`card_num`	Mandatory if no `card_token`
`card_token`	Mandatory if no `card_num`
`card_expiry`	Mandatory
`using_stored_credentials`	`true`
`acs_3dsversion`	Mandatory
`acs_eci`	Mandatory
`acs_cavv`	Mandatory
`acs_dstransid`	Mandatory

Network Tokens

Network Tokens increase security of transactions by replacing sensitive payment information with dynamically generated tokens to mitigate the risk of data breaches and fraud. The tokens are used to substitute a cardholder’s Primary Account Number (PAN) with a unique identifier. This process also simplifies payment management as well as increasing security as tokens can be updated without changing the underlying payment information.

To use Network Tokens you need to ensure you send the below parameters as part of your Remote Authentication request. For more information about Remote Authentication see the Remote Authentication Guide or API Reference.

For Cardholder Initiated Transactions:

Parameter	Description	Mandatory/Optional
`network_token`	Boolean – True – If transaction uses Network Tokens	Mandatory
`card_num`	String – Customer’s virtual card number	Mandatory
`card_tavv`	Hex – Token authentication verification value	Mandatory
`card_cvv`	Int – Card security code	Optional
`card_payment_account_reference`	String or Int – EMVCo standard value used to link tokenised and PAN-based transactions without PAN as the linkage mechanism	Optional

For Merchant Initiated Transactions:

Parameter	Description	Mandatory/Optional
`network_token`	Boolean – True if transaction uses Network Tokens	Mandatory
`card_num`	String – customer’s virtual card number	Mandatory
`card_tavv`	Hex – token authentication verification value	Mandatory
`card_payment_account_reference`	String or Int – EMVCo standard value used to link tokenised and PAN-based transactions without PAN as the linkage mechanism	Optional

Test 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:

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

Warning

Test card numbers will only work in the Integration environment, if used in Production environment an error will be returned.