Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Introduction

This is aim of this guide is to show you how to integrate your website with the Blink gateway so that you can accept payments straight from your website. If you require a more advanced integration, please contact our Integrations Team.

Table of Contents
minLevel1
maxLevel2
exclude"Benefits" "Disadvantages"
stylecircle


Prerequisites

  • Merchant Gateway ID e.g. 233508

  • Secret Key e.g. <T4NW>)dic

  • Basic understanding of PHP and web development.


Integration Types

Hosted

The request is made using the URL: https://gateway2.blinkpayment.co.uk/hosted/modal, with the merchant credentials (MID and encrypted signature key), amount, reference and customer details.

When initiated, the hosted integration will redirect the customer from the merchant site to the Blink , where the customer fills in their card details and pays.

Once the customer has completed the payment, they can be redirected back to the merchant site. The response fields can be sent to the merchant site.

Benefits

  • Easy set up

  • Secure (Payment journey is handled completely by Blink)

Disadvantages

  • Redirects - Customer has to leave merchant site ( the gateway can be opened in an iframe, overlaying the merchant site, which mitigates this issue).

  • Takes longer for customer to go through payment journey.

  • Customisation is difficult and limited.


Direct

Note

The IP address of the merchant site must be whitelisted by Blink.

The merchant site must have a valid SSL (for 3DS transactions).

The request is made using the URL: https://gateway2.blinkpayment.co.uk/direct. unlike the hosted integration, all the required fields (amount, name, card number…) can be sent in one form, making the payment journey quicker and easier.

When initiated, the transaction request details are sent to the gateway from the site.

Once the payment is complete, the response is sent immediately to the merchant site.

Benefits

  • Customer stays on the merchant site for the whole payment life cycle.

  • Fully customisable.

Disadvantages

  • More vulnerable to security issues/ attacks (using hosted fields can mitigate this issue).

  • Troubleshooting can be more difficult.

  • Set up is more complicated as it requires IP whitelisting and implementing 3DS checking code.


Request

Required Fields

Field Name

Description

1

Merchant ID

Your Merchant Gateway ID

(Can be found on Take a Payment and Request a Payment)

2

signature

Unique key related to your merchant ID.

Please contact our support team to find out your signature key.

3

action

The Action requested. Typically, SALE

4

amount

Transaction Amount

5

type

1 - E-commerce (ECOM) - standard online payments.

2 - Mail Order Telephone Order (MOTO) - the merchant inputs the customer’s card details.

9 - Continuous Authority (CA) - for recurring and rerunning transactions.

6

countryCode

Merchant’s Location (for UK 826)

7

currencyCode

Transaction currency code (for UK 826)

8

cardNumber

The primary account number (PAN). Digits and spaces only - Direct Integration Only

9

cardExpiryMonth

The card’s expiry month from 1 to 12. - Direct Integration Only

10

cardExpiryYear

The card’s expiry year from 00 to 99. - Direct Integration Only

11

cardCVV

Payment card’s security number. The 3 or 4 digit number printed on the signature strip. - Direct Integration Only

Recommended (Optional) Fields

Field Name

Description

1

transactionUnique

You can supply a unique identifier for this transaction. This is an added security feature to combat transaction spoofing.

2

customerName

Name of Customer

3

customerEmail

Email Address of customer

4

customerAddress

Address of customer - may be required depending on AVS checks

5

customerPostCode

Post code of customer - may be required depending on AVS checks

6

orderRef

Free format text field to store order details, reference numbers, etc. for the Merchant’s records. Essentially, an additional identifier.

7

redirectURL

URL to which the hosted form will redirect the Customer’s browser after the transaction has been completed. (Only relevant to Hosted integration)

Advanced Fields

Field Name

Description

1

orderDate

Recorded date of the transaction

2

xref

Refers to a pervious transaction, this is used to rerun or refund previous transactions.

3

captureDelay

Delay the actual money transfer by an amount of days.

4

merchantPwd

Additional password to increase authentication security.


Response

Field Name

Always Returned?

Description

respnseCode

Yes

A numeric code providing the specific outcome. Common values are:

0 - Successful / authorised transaction.

1 - Card referred – Refer to card issuer.

2 - Card referred – Special condition.

4 - Card declined – Keep card.

5 - Card declined

responseStatus

Yes

A numeric code providing the outcome category. Possible values are:

0 – Authorisation Approved / No reason to decline

1 – Authorisation Declined.

2 – Authorisation Error / Transaction malformed.

responseMessage

Yes

Message received from the Acquiring bank, or any error message.

transactionID

Yes

A unique ID assigned by the Gateway.

acquirerResponseXXXX

Depends on the acquirer

Additional Response sent by acquirer

xref

Yes

Used to rerun or refund transactions at a later point.

state

Yes

Transaction state

timestamp

Yes

The time when the transaction was last modified

cardNumberMask

Yes

The first 4 digits and last 4 digits of the customer’s PAN card number. The rest of the digits are encrypted.

transactionUnique

If sent in request

Any value supplied in the initial request.

orderRef

If sent in request

Any value supplied in the initial request.

authorisationCode

If transaction was successful

Authorisation code (Auth Code) received from Acquirer.

amountReceived

If transaction was successful

Amount the Acquirer authorised. This should always be the full amount in the request.

cardTypeCode

Yes

Code identifying the type of card used.

cardType

Yes

Description of the type of card used.

cardSchemeCode

Yes

Code identifying the Card Scheme used.

cardScheme

Yes

Description of the Card Scheme used.

cardIssuer

Yes

Card Issues name

cardIssuerCountry

Yes

Card issuing country’s name

cardIssuerCountryCode

Yes

Card issuing country’s ISO-3166 2-letter code

amountRefunded

If it is a refund

Total amount of original SALE that has so far been refunded. Returned when action is REFUND_SALE


Test Accounts

If you would like to test an integration, please be in touch with our integrations team, who will send you Blink test account credentials. The merchant will be able to see the test transactions on their Blink account.

Test Card Details

Card Type

Card Number

CVV

Expiry Date

Address

Visa Credit

4929 4212 3460 0821

356

12/22

Flat 6

Primrose Rise

347 Lavender Road

Northampton

NN17 8YG

4543 0599 9999 9982

110

12/22

76 Roseby Avenue

Manchester

M63X 7TH

4543 0599 9999 9990

689

12/22

23 Rogerham

Mansions

4578 Ermine Street

Borehamwood

WD54 8TH

Visa Debit

4539 7910 0173 0106

289

12/22

Unit 5

Pickwick Walk

120 Uxbridge Road

Hatch End

Middlesex

HA6 7HJ

5301 2500 7000 0191

419

12/22

Mews 57

Ladybird Drive

Denmark 65890

Mastercard Credit

5301 2500 7000 0191

419

12/22

25 The Larches

Narborough

Leicester

LE10 2RT

5413 3390 0000 1000

304

12/22

Pear Tree Cottage

The Green

Milton Keynes

MK11 7UY

5434 8499 9999 9951

470

12/22

34a Rubbery Close

Cloisters Run

Rugby

CV21 8JT

5434 84999 999 9993

557

12/22

4-7 The Hay Market

Grantham

NG32 4HG

Mastercard Debit

5573 4712 3456 7898

159

12/22

Merevale Avenue

Leicester

LE10 2BU

UK Maestro

6759 0150 5012 3445 002

309

12/22

The Parkway

5258 Larches Approach

Hull

North Humberside

HU10 5OP

6759 0168 0000 0120 097

701

12/22

The Manor

Wolvey Road

Middlesex

TW7 9FF

American Express

3742 4545 5400 001

4887

12/22

The Hunts Way

Southampton

SO18 1GW

Electron

4917 4800 0000 0008

009

12/22

5-6 Ross Avenue

Birmingham

B67 8UJ

JCB

3540 5999 9999 1047

209

12/22

2 Middle Wallop

Merideth-in-the-Wolds

Lincolnshire

LN2 8HG

Test Transactions Limits

Range (£)

Authorisation Response

Settlement Outcome

0.00-0.99

66311 (Invalid Test Amount)

N/A

1.00 -24.99

(0) AUTH CODE: XXXXXX

ACCEPTED

25.00-49.99

(0) AUTH CODE: XXXXXX

REJECTED

50.00-74.99

(1) CARD REFERRED
(0) AUTH CODE: XXXXXX

ACCEPTED

75.00-99.99

(1) CARD REFERRED
(0) AUTH CODE: XXXXXX

REJECTED

100.00-149.99

(5) CARD DECLINED

N/A

150.00-199.99

(4) CARD DECLINED – KEEP CARD

N/A

200.00-249.99

(65) CARD DECLINED - SCA REQUIRED
(0) AUTH CODE: XXXXX

ACCEPTED

250.00-299.99

(65) CARD DECLINED - SCA REQUIRED (0) AUTH CODE: XXXXX

N/A

300 and greater

66311 (Invalid Test Amount)

N/A

Sample Codes

Hosted Integration

Code Block
breakoutModewide
languagephp
<?PHP


//Merchant ID 
 $merchantID = '233508'

 // Merchant Signature key,
 $key = '<T4NW>)dic';

 // Gateway URL
 $url = 'https://gateway2.blinkpayment.co.uk/hosted/modal';


 if (!isset($_POST['responseCode'])) {
 // Send request to gateway

 // Request
 $req = array(
 'merchantID' => $merchantID,
 'action' => 'SALE',
 'type' => 1,
 'countryCode' => 826,
 'currencyCode' => 826,
 'amount' => 1001,
 'orderRef' => 'Test purchase',
 'transactionUnique' => uniqid(),
 'redirectURL' => ($_SERVER['HTTPS'] == 'on' ? 'https' : 'http') . '://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'],
 );

 // Create the signature using the function called below.
 $req['signature'] = createSignature($req, $key);

 echo '<form action="' . htmlentities($url) . '" method="post">' . PHP_EOL;

 foreach ($req as $field => $value) {
 echo ' <input type="hidden" name="' . $field . '" value="' . htmlentities($value) . '">' . PHP_EOL;
 }

 echo ' <input type="submit" value="Pay Now">' . PHP_EOL;
 echo '</form>' . PHP_EOL;

 // Check the return signature
 if (!$signature || $signature !== createSignature($res, $key)) {
 // You should exit gracefully
 die('Sorry, the signature check failed');
 }

 // Check the response code
 if ($res['responseCode'] === "0") {
 echo "<p>Thank you for your payment.</p>";
 } else {
 echo "<p>Failed to take payment: " . htmlentities($res['responseMessage']) . "</p>";
 }

 }

 // Function to create a message signature
 function createSignature(array $data, $key) {
 // Sort by field name
 ksort($data);

 // Create the URL encoded signature string
 $ret = http_build_query($data, '', '&');

 // Normalise all line endings (CRNL|NLCR|NL|CR) to just NL (%0A)
 $ret = str_replace(array('%0D%0A', '%0A%0D', '%0D'), '%0A', $ret);

 // Hash the signature string and the key together
 return hash('SHA512', $ret . $key);
 }

 ?>

Direct Integration (with 3DS)

Code Block
breakoutModewide
languagephp
<?PHP
// Merchant ID
$merchantID = '233508';
 // Signature key entered on MMS. The demo account is fixed to this value,
 $key = '<T4NW>)dic';

 // Gateway URL
 $url = 'https://gateway2.blinkpayment.co.uk/direct/';

 
 // Setup PHP session as use it to store data between 3DS steps
 if (isset($_GET['sid'])) {
 session_id($_GET['sid']);
 }

 session_start();

 // Compose current page URL (removing any sid and acs parameters)
 $pageURL = ((isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] == 'on') ? 'https://' : 'http://')  . $_SERVER['SERVER_NAME'] . ($_SERVER['SERVER_PORT'] != '80' ? ':' . $_SERVER['SERVER_PORT'] : '')  . preg_replace('/(sid=[^&]+&?)|(acs=1&?)/', '', $_SERVER['REQUEST_URI']);
 // Add back the correct sid parameter (used as session cookie may not be passed when the page is redirected from an IFRAME)

 $pageURL .= (strpos($pageURL, '?') === false ? '?' : '&') . 'sid=' . URLencode(session_id());
 

 // If ACS response into the IFRAME then redirect back to parent window
 if (!empty($_GET['acs'])) {
 echo silentPost($pageURL, array('threeDSResponse' => $_POST), '_parent');
 exit();
 }

 if (!isset($_POST['threeDSResponse'])) {
 // Initial request

 // Gather browser info - can be done at any time prior to the checkout
 if (!isset($_POST['browserInfo'])) {
 echo collectBrowserInfo();
 exit();
 }

 // Direct Request
 $req = array(
 'merchantID' => $merchantID,
 'action' => 'SALE',
 'type' => 1,
 'currencyCode' => 826,
 'countryCode' => 826,
 'amount' => 901,
 'cardNumber' => '4543059999999990',
 'cardExpiryMonth' => 12,
 'cardExpiryYear' => 22,
 'cardCVV' => '689',
 'customerName' => 'Test Customer',
 'customerEmail' => 'test@testcustomer.com',
 'customerAddress' => '16 Test Street',
 'customerPostCode' => 'Tef 5ST',
 'orderRef' => '3DS tesrt purchase',

 // The following fields are mandatory for 3DS v2
 'remoteAddress' => $_SERVER['REMOTE_ADDR'],
 'threeDSRedirectURL' => $pageURL . '&acs=1',

 // The following field allows options to be passed for 3DS v2
 // and the values here are for demonstration purposes only
 'threeDSOptions' => array(
 'paymentAccountAge' => '20190601',
 'paymentAccountAgeIndicator' => '05',
 ),
 );

 // Add the browser info as it is mandatory for 3DS v2
 $req += $_POST['browserInfo'];

 } else {
 // 3DS continuation request
 $req = array(
 'threeDSRef' => $_SESSION['threeDSRef'],
 'threeDSResponse' => $_POST['threeDSResponse'],
 );

 }

 // Create the signature using the function called below.
 $req['signature'] = createSignature($req, $key);

 // Initiate and set cURL options to post to the gateway
 $ch = cURL_init($url);
 cURL_setopt($ch, CURLOPT_POST, true);
 cURL_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($req));
 cURL_setopt($ch, CURLOPT_HEADER, false);
 cURL_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
 cURL_setopt($ch, CURLOPT_RETURNTRANSFER, true);

 // Send the request and parse the response
 if (($res = cURL_exec($ch)) === false) {
 // You should exit gracefully
 die('Sorry, the request could not be sent: ' . cURL_error($ch));
 }

 parse_str($res, $res);

// Close the connection to the gateway
cURL_close($ch);

// Extract the return signature as this isn't hashed
$signature = null;
if (isset($res['signature'])) {
 $signature = $res['signature'];
 unset($res['signature']);
}

// Check the return signature
if (!$signature || $signature !== createSignature($res, $key)) {
 // You should exit gracefully
 die('Sorry, the signature check failed');
}

// Check the response code
if ((int)$res['responseCode'] === 65802) {
 // Send request to the ACS server displaying response in an IFRAME

 // Render an IFRAME to show the ACS challenge (hidden for fingerprint method)
 $style = (isset($res['threeDSRequest']['threeDSMethodData']) ? 'display: none;' : '');
 echo "<iframe name=\"threeds_acs\" style=\"height:420px; width:420px; {$style}\"></iframe>\n";

 // Silently POST the 3DS request to the ACS in the IFRAME
 echo silentPost($res['threeDSURL'], $res['threeDSRequest'], 'threeds_acs');

 // Remember the threeDSRef as need it when the ACS responds
 $_SESSION['threeDSRef'] = $res['threeDSRef'];

} else if ((int)$res['responseCode'] === 0) {
 echo "<p>Thank you for your payment.</p>";
} else {
    echo $res['responseCode'];
    
 echo "<p>Failed to take payment: :( " . htmlentities($res['responseMessage']) . "</p>";
}

// Function to create a message signature
function createSignature(array $data, $key) {
 // Sort by field name
 ksort($data);

 // Create the URL encoded signature string
 $ret = http_build_query($data, '', '&');

 // Normalise all line endings (CRNL|NLCR|NL|CR) to just NL (%0A)
 $ret = str_replace(array('%0D%0A', '%0A%0D', '%0D'), '%0A', $ret);

 // Hash the signature string and the key together
 return hash('SHA512', $ret . $key);
}

// Return HTML to render a hidden form used to collect some browser details
function collectBrowserInfo(array $options = null) {

 $form_attrs = 'id="collectBrowserInfo" method="post" action="?"';

 if (isset($options['formAttrs'])) {
 $form_attrs .= $options['formAttrs'];
 }

 $device_data = array(
 'deviceChannel' => 'browser',
 'deviceIdentity' => (isset($_SERVER['HTTP_USER_AGENT']) ? htmlentities($_SERVER['HTTP_USER_AGENT']) : null),
 'deviceTimeZone' => '0',
 'deviceCapabilities' => '',
 'deviceScreenResolution' => '1x1x1',
 'deviceAcceptContent' => (isset($_SERVER['HTTP_ACCEPT']) ? htmlentities($_SERVER['HTTP_ACCEPT']): null),
 'deviceAcceptEncoding' => (isset($_SERVER['HTTP_ACCEPT_ENCODING']) ? htmlentities($_SERVER['HTTP_ACCEPT_ENCODING']) : null),
 'deviceAcceptLanguage' => (isset($_SERVER['HTTP_ACCEPT_LANGUAGE']) ? htmlentities($_SERVER['HTTP_ACCEPT_LANGUAGE']) : null),
 'deviceAcceptCharset' => (isset($_SERVER['HTTP_ACCEPT_CHARSET']) ? htmlentities($_SERVER['HTTP_ACCEPT_CHARSET']) : null),
 );

 $form_fields = fieldToHtml('browserInfo', $device_data);

 if (isset($options['formData'])) {
 foreach ((array)$options['formData'] as $name => $value) {
 $form_fields .= fieldToHtml($name, $value);
 }
 }

 $ret = <<<EOS
 <form {$form_attrs}>
 {$form_fields}
 </form>
 <script>
 var screen_width = (window && window.screen ? window.screen.width : '0');
 var screen_height = (window && window.screen ? window.screen.height : '0');
 var screen_depth = (window && window.screen ? window.screen.colorDepth : '0');
 var identity = (window && window.navigator ? window.navigator.userAgent : '');
 var language = (window && window.navigator ? (window.navigator.language ? window.navigator.language : window.navigator.browserLanguage) : '');
 var timezone = (new Date()).getTimezoneOffset();
 var java = (window && window.navigator ? navigator.javaEnabled() : false);
 var fields = document.forms.collectBrowserInfo.elements;
 fields['browserInfo[deviceIdentity]'].value = identity;
 fields['browserInfo[deviceTimeZone]'].value = timezone;
 fields['browserInfo[deviceCapabilities]'].value = 'javascript' + (java ? ',java' : '');
 fields['browserInfo[deviceAcceptLanguage]'].value = language;
 fields['browserInfo[deviceScreenResolution]'].value = screen_width + 'x' + screen_height + 'x' + screen_depth;
 window.setTimeout('document.forms.collectBrowserInfo.submit()', 0);
 </script>
EOS;

 return $ret;
}

// Render HTML to silently POST data to URL in target brower window
function silentPost($url = '?', array $post = null, $target = '_self') {

 $url = htmlentities($url);
 $target = htmlentities($target);
 $fields = '';

 if ($post) {
 foreach ($post as $name => $value) {
 $fields .= fieldToHtml($name, $value);
 }
 }

 $ret = "
 <form id=\"silentPost\" action=\"{$url}\" method=\"post\" target=\"{$target}\">
 {$fields}
 <noscript><input type=\"submit\" value=\"Continue\"></noscript>
 </form>
 <script>
 window.setTimeout('document.forms.silentPost.submit()', 0);
 </script>
 ";

 return $ret;
}

// Return a value as hidden HTML FORM fields
function fieldToHtml($name, $value) {
 $ret = '';
 if (is_array($value)) {
 foreach ($value as $n => $v) {
 $ret .= fieldToHtml($name . '[' . $n . ']', $v);
 }
 } else {
 // Convert all applicable characters or none printable characters to HTML entities
if(!$value) $value = " ";
 $value = preg_replace_callback('/[\x00-\x1f]/', function($matches) { return '&#' . ord($matches[0]) .';'; }, htmlentities($value, ENT_COMPAT, 'UTF-8', true));

 $ret = "<input type=\"hidden\" name=\"{$name}\" value=\"{$value}\" />\n";
 }

 return $ret;
}


?>

Ecommerce Modules

Blink offers ready to use plugins for WooCommerce and Magento websites. They use the hosted integration and are fully connected to the reporting and tracking features on both platforms, i.e. a successful payment will generate an order for the merchant to fill.

WooCommerce Magento