Contents

Protect Plus (API)

 

Warning
The following content assumes you have obtained the necessary PCI certification to process and submit sensitive cardholder data in the request to our Webservices API.

If you are unsure, please contact our Support Team for assistance.

Info
If you are already processing e-commerce payments using our JavaScript Library, your existing solution can be updated to also submit Protect Plus requests with minimal changes to the mark-up. Click here to learn more.

 

Protect Plus is a sophisticated counter-fraud service that provides your site with an extra layer of security against fraudulent transactions. It makes use of the industry’s largest negative database to perform a comprehensive suite of fraud assessments, including identity checks against the UK electoral roll and BT databases.

 

Process overview

Status good
Sign up for Protect Plus
Before you can get started, you will need to contact our Sales Team and enable Protect Plus on your account.

 

What checks are performed?

We analyse the customer’s billing, delivery and payment details using a rule-based system to detect suspicious patterns in user activity. Our system will assist you in deciding on whether or not to process a customer’s transaction based on the perceived level of risk. Checks performed include:

 

 

Warning
Protect Plus does not guarantee against fraud
You should consider all data regarding a transaction before accepting the payment.

 

What happens after the checks are performed?

The Protect Plus system will analyse transaction details and issue one of the following fraudcontrolshieldstatuscode values:

“ACCEPT” The details are not deemed suspicious.
“CHALLENGE” Further investigation is recommended.
“DENY” The details are suspicious and a transaction should not be performed.
“NOSCORE” Transaction was declined by the acquirer before checks were performed.

 

Order of requests

Protect Plus checks are performed when a RISKDEC request is submitted to our system. There are two methods in which you can configure your system to process RISKDEC requests using our Webservices API:

 

RISKDEC then AUTH request

Process overview

  1. When the customer clicks “Pay” on your checkout, your system submits a RISKDEC request to Trust Payments using the Webservices API (we provide an example of how to structure this request below).
  2. Trust Payments checks the payment details, generates a fraudcontrolshieldstatuscode and returns this information to your system in a RISKDEC response.
  3. Your system will need to check the shield status code and determine whether or not to proceed with the payment.
  4. If you opt to process the payment, you can process a payment using our JavaScript as described herewith one important difference.
    The JWT in the payload must be updated to include field parenttransactionreference, including the unique transactionreference returned in the RISKDEC response.
    This is used to inherit data from the initial request.
  5. Trust Payments contacts the acquiring bank to process the payment.
  6. Trust Payments returns the response JWT to your system. You will need to interpret the response.

 

Info
By default, when you opt to perform the RISKDEC before the AUTH, we automatically suspend authorised transactions when the fraudcontrolshieldstatuscode is “CHALLENGE” or “DENY”. This will allow you to investigate further and make a more informed choice on whether or not to authorise a suspicious transaction. This behaviour can be changed. Please contact the Support Team for further information.

 

RISKDEC request example

Here is an example of a RISKDEC request, the details of which can be inherited in future payments processed using our JavaScript Library:


#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

riskdec= {
    "sitereference": "test_site12345",
    "requesttypedescriptions": ["RISKDEC"],
    "accounttypedescription": "ECOM",
    "currencyiso3a": "GBP",
    "baseamount": "1011",
    "orderreference": "My_Order_123",
    "pan": "4111111111111111",
    "expirydate": "12/2020",
    "securitycode": "123"
}

strequest = securetrading.Request()
strequest.update(riskdec)
stresponse = st.process(strequest) #stresponse contains the transaction response
<?php

if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
  throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);

$configData = array(
'username' => '[email protected]',
'password' => 'Password1^',
);

$requestData = array(
  'sitereference' => 'test_site12345',
  'requesttypedescriptions' => array('RISKDEC'),
  'accounttypedescription' => 'FRAUDCONTROL',
  'currencyiso3a' => 'GBP',
  'baseamount' => '1011',
  'orderreference' => 'My_Order_123',
  'pan' => '4111111111111111',
  'expirydate' => '12/2020',
  'securitycode' => '123'
);

$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "[email protected]",
"version": "1.00",
"request": [{
  "currencyiso3a": "GBP",
  "requesttypedescriptions": ["RISKDEC"],
  "sitereference": "test_site12345",
  "baseamount": "1011",
  "orderreference": "My_Order_123",
  "accounttypedescription": "FRAUDCONTROL",
  "pan": "4111111111111111",
  "expirydate": "12/2020",
  "securitycode": "123"
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"GBP","requesttypedescriptions":["RISKDEC"],"sitereference":"test_site12345","baseamount":"1011","orderreference":"My_Order_123","accounttypedescription":"FRAUDCONTROL","pan":"4111111111111111","expirydate":"12\/2020"}]}
<?xml version="1.0" encoding="utf-8"?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="RISKDEC">
    <merchant>
      <orderreference>My_Order_123</orderreference>
    </merchant>
    <billing>
      <amount currencycode="GBP">1011</amount>       
      <payment>
        <expirydate>12/2020</expirydate>
        <pan>4111111111111111</pan>
      </payment>
    </billing>
    <operation>
      <accounttypedescription>FRAUDCONTROL</accounttypedescription>
      <sitereference>test_site12345</sitereference>
    </operation>
  </request>
</requestblock>

Replace <DOMAIN> with a supported domain. Click here for a full list.

 

RISKDEC response example

Here is an example of the associated RISKDEC response:

For the RISKDEC response field specification, scroll down to the “Interpreting the response” section.


{
  u 'requestreference': u 'A0dcb11e6',
    u 'version': u '1.00',
    u 'response': [{
      u 'acquirerrecommendedaction': u 'C',
        u 'fraudcontrolresponsecode': u '0100',
        u 'paymenttypedescription': u 'VISA',
        u 'orderreference': u 'My_Order_123',
        u 'transactionstartedtimestamp': u '2016-12-07 16:19:28',
        u 'errormessage': u 'Ok',
        u 'operatorname': u '[email protected]',
        u 'fraudcontrolreference': u 'TEST',
        u 'accounttypedescription': u 'FRAUDCONTROL',
        u 'errorcode': u '0',
        u 'transactionreference': u '1-2-345678',
        u 'maskedpan': u '411111######1111',
        u 'requesttypedescription': u 'RISKDEC',
        u 'fraudcontrolshieldstatuscode': u 'ACCEPT',
        u 'livestatus': u '0'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A58cdfkpy"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0] => array(15) {
        ["errorcode"] => string(1) "0"
        ["orderreference"] => string(12) "My_Order_123"
        ["fraudcontrolresponsecode"] => string(4) "0100"
        ["paymenttypedescription"] => string(4) "VISA"
        ["maskedpan"] => string(16) "411111######1111"
        ["transactionstartedtimestamp"] => string(19) "2016-12-09 11:12:39"
        ["errormessage"] => string(2) "Ok"
        ["operatorname"] => string(23) "[email protected]"
        ["accounttypedescription"] => string(12) "FRAUDCONTROL"
        ["acquirerrecommendedaction"] => string(1) "C"
        ["transactionreference"] => string(9) "1-2-345678"
        ["requesttypedescription"] => string(7) "RISKDEC"
        ["fraudcontrolreference"] => string(4) "TEST"
        ["fraudcontrolshieldstatuscode"] => string(6) "ACCEPT"
        ["livestatus"] => string(1) "0"
      }
  }
}
{"requestreference":"W23-wt77f0n8","version":"1.00","response":[{"errorcode":"0","fraudcontrolresponsecode":"0100","paymenttypedescription":"VISA","orderreference":"My_Order_123","transactionstartedtimestamp":"2016-12-07 16:23:03","errormessage":"Ok","operatorname":"[email protected]","accounttypedescription":"FRAUDCONTROL","acquirerrecommendedaction":"C","transactionreference":"1-2-345678","requesttypedescription":"RISKDEC","maskedpan":"411111######1111","fraudcontrolreference":"TEST","fraudcontrolshieldstatuscode":"ACCEPT","livestatus":"0"}],"secrand":"E0ksvyuH5VKg"}
<?xml version="1.0" encoding="utf-8"?>
<responseblock version="3.67">
  <requestreference>X336659733</requestreference>
  <response type="RISKDEC">
    <merchant>
      <orderreference>My_Order_123</orderreference>
      <operatorname>[email protected]</operatorname>
    </merchant>
    <transactionreference>1-2-345678</transactionreference>
    <billing>
      <payment type="VISA">
        <pan>411111######1111</pan>
      </payment>
    </billing>
    <timestamp>2012-06-21 13:32:43</timestamp>
    <fraudcontrol>
      <shieldstatuscode>ACCEPT</shieldstatuscode>
      <reference>TEST</reference>
      <recommendedaction>C</recommendedaction>
      <responsecode>0100</responsecode>
    </fraudcontrol>
    <live>0</live>
    <error>
      <message>Ok</message>
      <code>0</code>
    </error>
    <operation>
      <accounttypedescription>FRAUDCONTROL</accounttypedescription>
    </operation>
  </response>
  <secrand>2ngbLQ3DO</secrand>
</responseblock>

 

AUTH then RISKDEC request

Process overview

  1. When the customer clicks “Pay” on your checkout, the JavaScript library submits a request to Trust Payments.
  2. Trust Payments contacts the acquiring bank to process the payment.
  3. Trust Payments returns the response JWT to your system. You will need to interpret the response.
  4. Following this, your system submits a RISKDEC request to Trust Payments using the Webservices API, including the field parenttransactionreference, which is the unique transactionreference value returned in the response JWT (we provide an example of how to structure this request below).
  5. Trust Payments checks the payment details, generates a fraudcontrolshieldstatuscode and returns this information to your system in a RISKDEC response.
  6. Your system will need to check the shield status code and determine whether or not to proceed with the payment.
  7. If you want to suspend or cancel a payment, you will need to process a transaction update request using the Webservices API.

 

Request example

Here is an example of a RISKDEC request to be submitted using our Webservices API, following a payment processed using our JavaScript Library.


#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

riskdec= {
    "sitereference": "test_site12345",
    "requesttypedescriptions": ["RISKDEC"],
    "accounttypedescription": "FRAUDCONTROL",
    "currencyiso3a": "GBP",
    "baseamount": "1011",
    "orderreference": "My_Order_123",
    "parenttransactionreference": "1-2-3"
}

strequest = securetrading.Request()
strequest.update(riskdec)
stresponse = st.process(strequest) #stresponse contains the transaction response
<?php

if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
  throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);

$configData = array(
'username' => '[email protected]',
'password' => 'Password1^',
);

$requestData = array(
  'sitereference' => 'test_site12345',
  'requesttypedescriptions' => array('RISKDEC'),
  'accounttypedescription' => 'FRAUDCONTROL',
  'currencyiso3a' => 'GBP',
  'baseamount' => '1011',
  'orderreference' => 'My_Order_123',
  'parenttransactionreference' => '1-2-3'
);

$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -d '{
"alias": "[email protected]",
"version": "1.00",
"request": [{
  "currencyiso3a": "GBP",
  "requesttypedescriptions": ["RISKDEC"],
  "sitereference": "test_site12345",
  "baseamount": "1011",
  "orderreference": "My_Order_123",
  "accounttypedescription": "FRAUDCONTROL",
  "parenttransactionreference": "1-2-3"
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"GBP","requesttypedescriptions":["RISKDEC"],"sitereference":"test_site12345","baseamount":"1011","orderreference":"My_Order_123","accounttypedescription":"FRAUDCONTROL","parenttransactionreference":"1-2-3"}]}
<?xml version="1.0" encoding="utf-8"?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="RISKDEC">
    <merchant>
      <orderreference>My_Order_123</orderreference>
    </merchant>
    <billing>
      <amount currencycode="GBP">1011</amount>       
    </billing>
    <operation>
      <parenttransactionreference>1-2-3</parenttransactionreference>
      <accounttypedescription>FRAUDCONTROL</accounttypedescription>
      <sitereference>test_site12345</sitereference>
    </operation>
  </request>
</requestblock>

Replace <DOMAIN> with a supported domain. Click here for a full list.

 

Response example

Here is an example of the associated RISKDEC response:

For the RISKDEC response field specification, scroll down to the “Interpreting the response” section.


{
  u 'requestreference': u 'Ad4ft45gp',
    u 'version': u '1.00',
    u 'response': [{
        u 'acquirerrecommendedaction': u 'C',
        u 'fraudcontrolresponsecode': u '0100',
        u 'paymenttypedescription': u 'VISA',
        u 'orderreference': u 'My_Order_123',
        u 'transactionstartedtimestamp': u '2016-12-07 16:25:19',
        u 'errormessage': u 'Ok',
        u 'operatorname': u '[email protected]',
        u 'parenttransactionreference': u '1-2-345678',
        u 'fraudcontrolreference': u 'TEST',
        u 'accounttypedescription': u 'FRAUDCONTROL',
        u 'errorcode': u '0',
        u 'transactionreference': u '1-2-345679',
        u 'maskedpan': u '411111######1111',
        u 'requesttypedescription': u 'RISKDEC',
        u 'fraudcontrolshieldstatuscode': u 'ACCEPT',
        u 'livestatus': u '0'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A0bjmprty"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
      [0] => array(16) {
        ["errorcode"] => string(1) "0"
        ["orderreference"] => string(12) "My_Order_123"
        ["fraudcontrolresponsecode"] => string(4) "0100"
        ["paymenttypedescription"] => string(4) "VISA"
        ["maskedpan"] => string(16) "411111######1111"
        ["transactionstartedtimestamp"] => string(19) "2016-12-09 11:14:35"
        ["errormessage"] => string(2) "Ok"
        ["operatorname"] => string(23) "[email protected]"
        ["parenttransactionreference"] => string(10) "1-2-345678"
        ["accounttypedescription"] => string(12) "FRAUDCONTROL"
        ["acquirerrecommendedaction"] => string(1) "C"
        ["transactionreference"] => string(9) "1-2-345679"
        ["requesttypedescription"] => string(7) "RISKDEC"
        ["fraudcontrolreference"] => string(4) "TEST"
        ["fraudcontrolshieldstatuscode"] => string(6) "ACCEPT"
        ["livestatus"] => string(1) "0"
      }
  }
}
{"requestreference":"W23-eyqd5u3x","version":"1.00","response":[{"errorcode":"0","fraudcontrolresponsecode":"0150","paymenttypedescription":"VISA","orderreference":"My_Order_123","transactionstartedtimestamp":"2016-12-07 16:24:50","errormessage":"Ok","operatorname":"[email protected]","parenttransactionreference":"1-2-345678","accounttypedescription":"FRAUDCONTROL","acquirerrecommendedaction":"C","transactionreference":"1-2-345679","requesttypedescription":"RISKDEC","maskedpan":"411111######1111","fraudcontrolreference":"TEST","fraudcontrolshieldstatuscode":"ACCEPT","livestatus":"0"}],"secrand":"ft9j6l"}
<?xml version="1.0" encoding="utf-8"?>
<responseblock version="3.67">
  <requestreference>X336659733</requestreference>
  <response type="RISKDEC">
    <merchant>
      <orderreference>My_Order_123</orderreference>
      <operatorname>[email protected]</operatorname>
    </merchant>
    <transactionreference>18-65-2</transactionreference>
    <billing>
      <payment type="VISA">
        <pan>411111######1111</pan>
      </payment>
    </billing>
    <timestamp>2012-06-21 13:32:43</timestamp>
    <fraudcontrol>
      <shieldstatuscode>ACCEPT</shieldstatuscode>
      <reference>TEST</reference>
      <recommendedaction>C</recommendedaction>
      <responsecode>0150</responsecode>
    </fraudcontrol>
    <live>0</live>
    <error>
      <message>Ok</message>
      <code>0</code>
    </error>
    <operation>
      <parenttransactionreference>1-2-345679</parenttransactionreference>
      <accounttypedescription>FRAUDCONTROL</accounttypedescription>
    </operation>
  </response>
  <secrand>UIPGZ</secrand>
</responseblock>

 

Interpreting the response

Here is the field specification for a RISKDEC response:

 

Field Format Description
acquirerrecommendedaction
XPath: /fraudcontrol/recommendedaction
Char (1) Either:

  • “C” – Continue with the transaction.
  • “S” – Stop transaction.

Note that this is ONLY a recommendation. Protect Plus does not guarantee against fraud.

fraudcontrolreference
XPath: /fraudcontrol/reference
Alphanumeric (255) Unique reference to identify the Risk Decision check performed.
fraudcontrolresponsecode
XPath: /fraudcontrol/responsecode
Numeric (4) A numeric code that is mapped to a description of the results of the Risk Decision checks performed.
fraudcontrolshieldstatuscode
XPath: /fraudcontrol/shieldstatuscode
Alpha (10) One of the following values:

  • “ACCEPT” – The details are not deemed suspicious.
  • “CHALLENGE” – Further investigation is recommended.
  • “DENY” – The details are suspicious and a transaction should not be performed.
  • “NOSCORE” – Returned when a parent AUTH request has been declined.
requesttypedescription
XPath: /@type
Alpha (20) You will be returned “RISKDEC”.
rulecategoryflag
XPath: /fraudcontrol/categoryflag
Alphanumeric (255) Reference used to identify a condition that was met to return the DENY or CHALLENGE fraudcontrolshieldstatuscode.
rulecategorymessage
XPath: /fraudcontrol/categorymessage
Text (undefined length) Condition that was met to return the DENY or CHALLENGE fraudcontrolshieldstatuscode.

 

Testing

We recommend that you thoroughly test your solution before enabling on your live Site Reference.
Click here for details that you can submit to simulate different RISKDEC responses on our test system.

 

paysafecard

 

The requests outlined in this document will need to be processed manually using our Webservices API.

 

This page explains how to configure your site to accept transactions using paysafecard.

 

PAYMENT PAYSAFECARD
What is paysafecard?

 

  • A “paysafecard” is a pre-paid card that can be purchased by your customers from sales outlets worldwide (e.g. at PayPoint outlets). Each paysafecard contains a unique PIN that the customer can enter on the checkout page in order to complete a purchase.

 

  • “my paysafecard” is a personal online payments account to help customers keep track of multiple paysafecard PINs. The customer can opt to sign in to their “my paysafecard” account at time of purchase, which allows them to pay with paysafecard PINs stored on their account.
Info
Why implement paysafecard?

  • Customers can pay online without entering any personal information, bank or credit card details.
  • Funds are settled into your account immediately.
  • paysafecard is available worldwide at 500,000 sales outlets.
  • Customers can combine up to ten PINs to pay larger amounts.

 

Features

Supported customer countries No restrictions on customer countries.
Supported currencies
ARS, AUD, BGN, CAD, CHF, CZK, DKK, EUR, GBP, HRK, HUF, MXN, NOK, NZD, PEN, PLN, RON, SEK, TRY, USD, UYU
Protect Plus
Supported.
Refunds Refunds not supported.
Chargebacks
Payments are not subject to chargebacks.

 


 

Configuration

To enable paysafecard on your account, please get in touch with your account manager.
A test sandbox account will be provided, which you will need when testing your implementation.

 


 

Process overview

What will the customer see?

  • During the checkout process, your website presents paysafecard as a payment method.
  • The customer selects their preferred delivery address on your checkout page and opts to pay using paysafecard.
  • The customer is redirected to paysafecard, where they either enter their PIN(s), or signs into their “my paysafecard” account.
  • The customer reviews their order and agrees to the payment on paysafecard.
  • The customer is redirected to your website, where a confirmation is displayed (e.g. “Payment successful”).

 

 

How does it work behind the scenes?

The paysafecard payment flow can be split into three main parts, as shown below:

1

Initiate the customer

2

Redirect to paysafecard

3

Processing the authorisation

 


 

1. Initiate the customer

When the customer chooses to pay with paysafecard, your system will need to perform an ORDER request and interpret the response returned.

 

ORDER request example


#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

order = {
    "currencyiso3a": "GBP",
    "requesttypedescription": "ORDER",
    "accounttypedescription": "ECOM",
    "sitereference": "test_site12345",
    "baseamount": "2001",
    "paymenttypedescription": "PAYSAFECARD",
    "returnurl": "https://www.example.com/return",
    "cancelurl": "https://www.example.com/cancel",
    "billingid": "000001",
    "paysafeminage": "18",
    "paysafekyclevel": "SIMPLE",
    "paysafecountryrestriction": "DE"
}

strequest = securetrading.Request()
strequest.update(order)
stresponse = st.process(strequest) #stresponse contains the transaction response
<?php

if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
  throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);

$configData = array(
    'username' => '[email protected]',
    'password' => 'Password1^'
);

$requestData = array(
    'currencyiso3a' => 'GBP',
    'requesttypedescription' => 'ORDER',
    'accounttypedescription' => 'ECOM',
    'sitereference' => 'test_site12345',
    'baseamount' => '2001',
    'paymenttypedescription' => 'PAYSAFECARD',
    'returnurl' => 'https://www.example.com/return',
    'cancelurl' => 'https://www.example.com/cancel',
    'billingid' => '000001',
    'paysafeminage' => '18',
    'paysafekyclevel' => 'SIMPLE',
    'paysafecountryrestriction' => 'DE'
);

$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "[email protected]",
"version": "1.00",
"request": [{
    "currencyiso3a": "GBP",
    "requesttypedescription": "ORDER",
    "accounttypedescription": "ECOM",
    "sitereference": "test_site12345",
    "baseamount": "2001",
    "paymenttypedescription": "PAYSAFECARD",
    "returnurl": "https://www.example.com/return",
    "cancelurl": "https://www.example.com/cancel",
    "billingid": "000001",
    "paysafeminage": "18",
    "paysafekyclevel": "SIMPLE",
    "paysafecountryrestriction": "DE"
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"GBP","requesttypedescription":"ORDER","accounttypedescription":"ECOM","sitereference":"test_site12345","baseamount":"2001","paymenttypedescription":"PAYSAFECARD","returnurl":"https:\/\/www.example.com\/return","cancelurl":"https:\/\/www.example.com\/cancel","billingid":"000001","paysafeminage":"18","paysafekyclevel":"SIMPLE","paysafecountryrestriction":"DE"}]}
<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="ORDER">
    <merchant>
      <returnurl>https://www.example.com/return</returnurl>
      <cancelurl>https://www.example.com/cancel</cancelurl>
    </merchant>
    <billing id="000001">
      <amount currencycode="GBP">100</amount>
      <payment type="PAYSAFECARD">
        <paysafe>
          <minage>18</minage>
          <kyclevel>SIMPLE</kyclevel>
          <countryrestriction>DE</countryrestriction>
        </paysafe>
      </payment>
    </billing>
    <operation>
      <sitereference>test_site12345</sitereference>
      <accounttypedescription>ECOM</accounttypedescription>
    </operation>
  </request>
</requestblock>

Replace <DOMAIN> with a supported domain. Click here for a full list.

 

Field specification

Field Format Description
accounttypedescription
XPath: /operation/accounttypedescription
Alpha (20) Only “ECOM” (e-commerce) is supported.
baseamount
XPath: /billing/amount
Numeric (11) The amount of the transaction in base units, with no commas or decimal points, so €10 is submitted as 1000. This value must be greater than zero.
billingid
XPath: /billing/@id
Alphanumeric (100) An id provided by you, used to identify the customer.

 You must always submit a billingid:

  • Each customer must be assigned a unique id.
  • This id must be re-used by returning customers.
cancelurl
XPath: /merchant/cancelurl
URL (2048) The URL that the customer will be returned to if they cancel the authorisation while on paysafecard’s servers.
currencyiso3a
XPath: /billing/amount/@currencycode
Alpha (3) The currency that the transaction will be processed in. paysafecard transactions can be processed in the following currencies:

ARS, AUD, BGN, CAD, CHF, CZK, DKK, EUR, GBP, HRK, HUF, MXN, NOK, NZD, PEN, PLN, RON, SEK, TRY, USD, UYU

Click here for further information on currency codes.

orderreference
XPath: /merchant/orderreference
Alphanumeric including
symbols (255)
Your unique order reference that can be stored on the Trust Payments system.
paymenttypedescription
XPath: /billing/payment/@type
Alpha (20) This value must be submitted as “PAYSAFECARD”.
paysafecountryrestriction
XPath: /billing/payment/paysafe/countryrestriction
Alpha (2) Restricts the payment to be processed exclusively from the country specified (in iso2a format).

e.g. “GB” for United Kingdom.

Click here for a full list of country codes.

paysafekyclevel
XPath: /billing/payment/paysafe/kyclevel
Alpha (6) Specifies the required KYC level for the “my paysafecard” account holder. There are two levels:

  • SIMPLE” – The customer has successfully completed the initial registration process and confirmed their mobile number and email address.
  • FULL” – In addition to the above, the customer has also provided proof of identification (e.g. passport, driving license) and proof of address (e.g. utility bill).
paysafeminage
XPath: /billing/payment/paysafe/minage
Numeric (3) Specifies the minimum age of the “my paysafecard” account holder.

e.g. To restrict to over-18s only, submit “18” in this field.

requesttypedescription
XPath: /@type
Alpha (20) The value in the request must be “ORDER”.
returnurl
XPath: /merchant/returnurl
URL (2048) The URL that the customer will be returned to following a successful authorisation.
sitereference
XPath: /operation/sitereference
Alphanumeric
& underscore (50)
The site reference relates to your individual account which you received on setup. If you do not know your site reference, please contact our Support team.

 

ORDER response example


{
  u 'requestreference': u 'A0bxh87wt',
    u 'version': u '1.00',
    u 'response': [{
      u 'transactionreference': u '72-32-20002',
      u 'paymenttypedescription': u 'PAYSAFECARD',
      u 'settleduedate': u '2016-12-23',
      u 'transactionstartedtimestamp': u '2016-12-23 15:35:40',
      u 'errormessage': u 'Ok',
      u 'accounttypedescription': u 'ECOM',
      u 'errorcode': u '0',
      u 'customerredirecturl': u 'https://www.paysafecard.com/etc',
      u 'requesttypedescription': u 'ORDER',
      u 'settlestatus': u '0',
      u 'operatorname': u '[email protected]',
      u 'livestatus': u '0',
      u 'paysafeminage': u '18',
      u 'paysafekyclevel': u 'SIMPLE',
      u 'paysafecountryrestriction': u 'DE',
      u 'paysafeid': u '23842'
    }]
}
array(3) {
    ["requestreference"] => string(9) "A349bdehj"
    ["version"] => string(4) "1.00"
    ["response"] =>array(1) {
    [0] => array(16) {
        ["transactionreference"] => string(11) "72-32-20002"
        ["paymenttypedescription"] => string(11) "PAYSAFECARD"
        ["settleduedate" ]=> string(10) "2016-12-23"
        ["transactionstartedtimestamp"] => string(19) "2016-12-23 15:35:40"
        ["errormessage"] => string(2) "Ok"
        ["accounttypedescription"] => string(4) "ECOM"
        ["errorcode"] => string(1) "0"
        ["customerredirecturl"] => string(137) "https://www.paysafecard.com/etc"
        ["requesttypedescription"] => string(5) "ORDER"
        ["settlestatus"] => string(1) "0"
        ["operatorname"] => string(23) "[email protected]"
        ["livestatus"] => string(1) "0"
        ["paysafeminage"] => string(2) "18"
        ["paysafekyclevel"] => string(6) "SIMPLE"
        ["paysafecountryrestriction"] => string(2) "DE"
        ["paysafeid"] => string(5) "23842"
    }
  }
}
{"requestreference":"W23-fjgvn3d8","version":"1.00","response":[{"transactionreference":"72-32-20002","paymenttypedescription":"PAYSAFECARD","settleduedate":"2016-12-23","transactionstartedtimestamp":"2016-12-23 15:35:40","errormessage":"Ok","accounttypedescription":"ECOM","errorcode":"0","customerredirecturl":"https:\/\/www.paysafecard.com\/etc","requesttypedescription":"ORDER","settlestatus":"0","operatorname":"[email protected]","livestatus":"0","paysafeminage":"18","paysafekyclevel":"SIMPLE","paysafecountryrestriction":"DE","paysafeid":"23842"}],"secrand":"zO9"}
<?xml version='1.0' encoding='utf-8'?>
<responseblock version="3.67">
  <requestreference>X62d3qhev</requestreference>
  <response type="ORDER">
    <merchant>
      <operatorname>[email protected]</operatorname>
    </merchant>
    <customer>
      <redirecturl>https://www.paysafecard.com/etc</redirecturl>
    </customer>
    <transactionreference>1-2-345</transactionreference>
    <billing id="000001">
      <payment type="PAYSAFECARD">
        <paysafe>
          <!--Elements only returned if submitted in the request-->
          <minage>18</minage>
          <kyclevel>SIMPLE</kyclevel>
          <countryrestriction>DE</countryrestriction>
        </paysafe>
      </payment>
    </billing>
    <timestamp>2014-11-27 12:08:04</timestamp>
    <settlement>
      <settleduedate>2014-11-27</settleduedate>
      <settlestatus>0</settlestatus>
    </settlement>
    <live>0</live>
    <error>
      <message>Ok</message>
      <code>0</code>
    </error>
    <operation>
      <accounttypedescription>ECOM</accounttypedescription>
    </operation>
    <paysafe id="23842"/>
  </response>
  <secrand>vSQ</secrand>
</responseblock>

 

Field specification

Field Format Description
accounttypedescription
XPath: /operation/accounttypedescription
Alpha (20) The value returned is “ECOM”.
customerredirecturl
XPath: /customer/redirecturl
URL (500) You will need to redirect the customer’s browser to this URL to continue with the payment.
errorcode
XPath: /error/code
Numeric (1-5) The error code should be used to determine if the request was successful or not.

  • If the error code is “0” then the transaction was successful.
  • If the error code is not “0” then the transaction was not successful.

Click here for a full list of errorcode and message values.

errordata
XPath: /error/data
Alphanumeric (255) Additional information to help troubleshoot the error.
errormessage
XPath: /error/message
Alphanumeric (255) This is the corresponding message to the above code.

Click here for a full list of errorcode and message values.

livestatus
XPath: /live
Numeric (1)
  • 0 – Transaction processed using a test account.
  • 1 – Transaction processed using a live account.
operatorname
XPath: /merchant/operatorname
Alphanumeric (255) The value of this field contains the name of the user that processed the request.
paymenttypedescription
XPath: /billing/payment/@type
Alpha (20) This value returned is “PAYSAFECARD”.
paysafecountryrestriction
XPath: /billing/payment/paysafe/countryrestriction
Alpha (2) Restricts the payment to be processed exclusively from the country specified (in iso2a format).

e.g. “GB” for United Kingdom.

Click here for a full list of country codes.

paysafeid
XPath: /paysafe/@id
Alphanumeric (255) A unique id assigned to the transaction by paysafecard. You can store these ids for future correspondence with paysafecard.
paysafekyclevel
XPath: /billing/payment/paysafe/kyclevel
Alpha (6) Specifies the required KYC level for the “my paysafecard” account holder. There are two levels:

  • SIMPLE” – The customer has successfully completed the initial registration process and confirmed their mobile number and email address.
  • FULL” – In addition to the above, the customer has also provided proof of identification (e.g. passport, driving license) and proof of address (e.g. utility bill).
paysafeminage
XPath: /billing/payment/paysafe/minage
Numeric (3) The minimum age of the “my paysafecard” account holder, as specified in the ORDER request.
requesttypedescription
XPath: /@type
Alpha (20) The value returned is “ORDER”.
settleduedate
XPath: /settlement/settleduedate
Date YYYY-MM-DD The date on which the transaction will be settled.
settlestatus
XPath: /settlement/settlestatus
Numeric (3)
  • “0” indicates no issues have been raised so far that would prevent settlement from taking place.
  • “3” indicates the request was unsuccessful.
transactionreference
XPath: /transactionreference
Alphanumeric including
hyphens (25)
A unique reference for the request assigned by Trust Payments.

You will need to submit this reference in the AUTH request that follows.

transactionstartedtimestamp
XPath: /timestamp
Date time YYYY-MM-DD hh:mm:ss The time the request was processed.

 


 

2. Redirect to paysafecard

After successfully submitting an ORDER Request, your system will be returned a customerredirecturl in the response. Your system will need to redirect the customer to this URL, which is a page hosted by paysafecard, in order to process the payment.

When testing, you will be redirected to paysafecard’s sandbox page, which simulates the page that will be displayed to your customers (screenshot below).

The customer will be offered the choice between either:

The customer can proceed with the payment by clicking the “Pay” button.

User
If you specify certain restrictions in the ORDER Request (e.g. a minimum age requirement), the customer may be forced to sign in to their “my paysafecard” account to verify their details (e.g. to check their age). For further information, please refer to paysafecard’s own resources.

 

If successful authentication

The customer’s browser is redirected to the returnurl specified in the ORDER Request.

Warning
The payment is not completed until you successfully process the AUTH request described below.
You must wait for the customer to return from paysafecard to the returnurl hosted on your servers before continuing.

 

If customer cancels

The customer can cancel by clicking the cross in the upper-right. This redirects the customer’s browser to the cancelurl specified in the ORDER Request. You can then provide alternative methods of payment. If the customer wants to try again with paysafecard, you must start again by submitting a new ORDER Request.

 

Info
When testing, you will be displayed the sandbox as provided by paysafecard. To complete a test transaction, you will need to follow the instructions displayed on screen. Please contact your account manager for test credentials to enter while on the sandbox.

 


 

3. Processing the authorisation

Status attention
If the customer is redirected to the cancelurl:
Present your customer with alternative payment methods so they can try again.
Status good
If the customer is redirected to the returnurl:
Follow the instructions below.

 

AUTH request example

This example demonstrates how to process an AUTH request for paysafecard.


#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth = {
    "requesttypedescription": "AUTH",
    "sitereference": "test_site12345",
    "parenttransactionreference": "72-32-20002",
    "paymenttypedescription": "PAYSAFECARD"
}

strequest = securetrading.Request()
strequest.update(auth)
stresponse = st.process(strequest) #stresponse contains the transaction response
<?php

if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
  throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);

$configData = array(
    'username' => '[email protected]',
    'password' => 'Password1^'
);

$requestData = array(
                'requesttypedescription' => 'AUTH',
                'sitereference' => 'test_site12345',
                'parenttransactionreference' => '72-32-20002',
                'paymenttypedescription' => 'PAYSAFECARD'
);

$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
	"alias": "[email protected]",
	"version": "1.00",
	"request": [{
                "requesttypedescription": "AUTH",
                "sitereference": "test_site12345",
                "parenttransactionreference": "72-32-20002",
                "paymenttypedescription": "PAYSAFECARD"
		}]
}'
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescription":"AUTH","sitereference":"test_site12345","parenttransactionreference":"72-32-20002","paymenttypedescription":"PAYSAFECARD"}]}
<?xml version="1.0" encoding="utf-8"?>
<requestblock version="3.67">
<alias>[email protected]</alias>
 <request type="AUTH">
  <operation>
   <sitereference>test_site12345</sitereference>
   <parenttransactionreference>1-2-345</parenttransactionreference>
  </operation>
  <billing>
   <payment type="PAYSAFECARD"/>
  </billing>
 </request>
</requestblock>

Replace <DOMAIN> with a supported domain. Click here for a full list.

 

Field specification

Field Format Description
parenttransactionreference
XPath: /operation/parenttransactionreference
Alphanumeric
& hyphens (25)
In the request, submit the transactionreference of the preceding ORDER.
paymenttypedescription
XPath: /billing/payment/@type
Alpha (20) This value must be submitted as “PAYSAFECARD”.
requesttypedescription
XPath: /@type
Alpha (20) The value in the request must be “AUTH”.
sitereference
XPath: /operation/sitereference
Alphanumeric
& underscore (50)
The site reference relates to your individual account which you received on setup. If you do not know your site reference, please contact our Support team.

 

AUTH response example

Here is an example of an AUTH response for paysafecard.


{
  u 'requestreference': u 'A0dcb11e6',
    u 'version': u '1.00',
    u 'response': [{
      u 'transactionreference': u '72-32-20004',
      u 'merchantname': u 'Test Merchant',
      u 'paymenttypedescription': u 'PAYSAFECARD',
      u 'transactionstartedtimestamp': u '2016-12-23 15:36:31',
      u 'errormessage': u 'Ok',
      u 'parenttransactionreference': u '72-32-20003',
      u 'accounttypedescription': u 'ECOM',
      u 'errorcode': u '0',
      u 'settleduedate': u '2017-05-30',
      u 'currencyiso3a': u 'GBP',
      u 'baseamount': u '2001',
      u 'requesttypedescription': u 'AUTH',
      u 'operatorname': u '[email protected]',
      u 'livestatus': u '0',
      u 'settlestatus': u '0',
      u 'paysafeminage': u '18',
      u 'paysafekyclevel': u 'SIMPLE',
      u 'paysafecountryrestriction': u 'DE',
      u 'paysafeid': u '23842'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A58cdfkpy"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
      [1] =>array(19) {
        ["transactionreference"] => string(11) "72-32-20004"
        ["merchantname"] => string(13) "Test Merchant"
        ["paymenttypedescription"] => string(11) "PAYSAFECARD"
        ["transactionstartedtimestamp"] => string(19) "2016-12-23 15:36:31"
        ["errormessage"] => string(2) "Ok"
        ["parenttransactionreference"] => string(11) "72-32-20003"
        ["accounttypedescription"] => string(4) "ECOM"
        ["errorcode"] => string(1) "0"
        ["settleduedate"] => string(10) "2017-05-30"
        ["currencyiso3a"] => string(3) "GBP"
        ["baseamount"] => string(4) "2001"
        ["requesttypedescription"] => string(4) "AUTH"
        ["operatorname"] => string(23) "[email protected]"
        ["livestatus"] => string(1) "0"
        ["settlestatus"] => string(1) "0"
        ["paysafeminage"] => string(2) "18"
        ["paysafekyclevel"] => string(6) "SIMPLE"
        ["paysafecountryrestriction"] => string(2) "DE"
        ["paysafeid"] => string(5) "23842"
      }
  }
}
{"requestreference":"W23-fjgvn3d8","version":"1.00","response":[{"transactionreference":"72-32-20004","merchantname":"Test Merchant","paymenttypedescription":"PAYSAFECARD","transactionstartedtimestamp":"2016-12-23 15:36:31","errormessage":"Ok","parenttransactionreference":"72-32-20003","accounttypedescription":"ECOM","errorcode":"0","settleduedate":"2017-05-30","currencyiso3a":"GBP","baseamount":"2001","requesttypedescription":"AUTH","operatorname":"[email protected]","livestatus":"0","settlestatus":"0","paysafeminage":"18","paysafekyclevel":"SIMPLE","paysafecountryrestriction":"DE","paysafeid":"23842"}],"secrand":"zO9"}
<?xml version='1.0' encoding='utf-8'?>
<responseblock version="3.67">
  <requestreference>X538160153</requestreference>
  <response type="AUTH">
    <merchant>
      <merchantname>My Test Site</merchantname>
      <merchantnumber>00000000</merchantnumber>
      <operatorname>[email protected]</operatorname>
    </merchant>
    <transactionreference>1-2-347</transactionreference>
    <timestamp>2016-09-30 16:40:02</timestamp>
    <operation>
  <parenttransactionreference>1-2-346</parenttransactionreference>
      <accounttypedescription>ECOM</accounttypedescription>
    </operation>
    <settlement>
      <settleduedate>2016-10-01</settleduedate>
      <settlestatus>100</settlestatus>
    </settlement>
    <billing>
      <amount currencycode="GBP">100</amount>
      <payment type="PAYSAFECARD">
        <paysafe>
          <minage>18</minage>
          <kyclevel>SIMPLE</kyclevel>
          <countryrestriction>DE</countryrestriction>
        </paysafe>
      </payment>
    </billing>
    <live>0</live>
    <error>
      <message>Ok</message>
      <code>0</code>
    </error>
    <paysafe id="23842"/>
  </response>
  <secrand>7iNleP44</secrand>
</responseblock>

 

Field specification

Field Format Description
accounttypedescription
XPath: /operation/accounttypedescription
Alpha (20) The value returned is “ECOM”.
baseamount
XPath: /billing/amount
Numeric (11) The amount of the transaction in base units, with no commas or decimal points, so €10 is returned as 1000.
currencyiso3a
XPath: /billing/amount/@currencycode
Alpha (3) The currency that the transaction was processed in (in ISO3A format).
errorcode
XPath: /error/code
Numeric (1-5) The error code should be used to determine if the request was successful or not.

  • If the error code is “0” then the transaction was successful.
  • If the error code is not “0” then the transaction was not successful.

Click here for a full list of errorcode and message values.

errordata
XPath: /error/data
Alphanumeric (255) Additional information to help troubleshoot the error.
errormessage
XPath: /error/message
Alphanumeric (255) This is the corresponding message to the above code.

Click here for a full list of errorcode and message values.

livestatus
XPath: /live
Numeric (1)
  • 0 – Transaction processed using a test account.
  • 1 – Transaction processed using a live account.
merchantname
XPath: /merchant/merchantname
Alphanumeric (255) These are details associated with the account used to process the transaction.

To amend these fields, please contact our Support Team.

operatorname
XPath: /merchant/operatorname
Alphanumeric (255) The value of this field contains the name of the user that processed the request.
parenttransactionreference
XPath: /operation/parenttransactionreference
Alphanumeric
& hyphens (25)
The transactionreference of the preceding ORDER.
paymenttypedescription
XPath: /billing/payment/@type
Alpha (20) This value returned is “PAYSAFECARD”.
paysafecountryrestriction
XPath: /billing/payment/paysafe/countryrestriction
Alpha (2) Restricts the payment to be processed exclusively from the country specified (in iso2a format).

e.g. “GB” for United Kingdom.

Click here for a full list of country codes.

paysafeid
XPath: /paysafe/@id
Alphanumeric (255) A unique id assigned to the transaction by paysafecard. You can store these ids for future correspondence with paysafecard.
paysafekyclevel
XPath: /billing/payment/paysafe/kyclevel
Alpha (6) Specifies the required KYC level for the “my paysafecard” account holder. There are two levels:

  • SIMPLE” – The customer has successfully completed the initial registration process and confirmed their mobile number and email address.
  • FULL” – In addition to the above, the customer has also provided proof of identification (e.g. passport, driving license) and proof of address (e.g. utility bill).
paysafeminage
XPath: /billing/payment/paysafe/minage
Numeric (3) The minimum age of the “my paysafecard” account holder, as specified in the ORDER request.
requesttypedescription
XPath: /@type
Alpha (20) The value returned is “AUTH”.
settleduedate
XPath: /settlement/settleduedate
Date YYYY-MM-DD The date on which the transaction will be settled.
settlestatus
XPath: /settlement/settlestatus
Numeric (3)
  • “100” indicates funds will be captured immediately.
  • “3” indicates the request was unsuccessful.
transactionreference
XPath: /transactionreference
Alphanumeric including
hyphens (25)
A unique reference for the transaction assigned by Trust Payments.
transactionstartedtimestamp
XPath: /timestamp
Date time YYYY-MM-DD hh:mm:ss The time the transaction was processed.

 


 

Notifications

Before you begin testing, we recommend that you contact our Support team and request that rules are enabled on your account, which submit URL notifications to your system when a payment has been authorised.

 

Configuring the notification

We recommend including at least the following fields in URL notifications sent on authorisation:

*Please choose your preferred format.

 

Check the notification

You will need to check the contents of each notification received and respond accordingly by following the processes outlined in the “URL notifications” section of our Action types page. In particular, you will need to look at the settlestatus value:

 


 

Settlement

Provided the requests were successful, the funds are settled immediately after the customer has completed the payment. You will not be able to cancel or otherwise update paysafecard transactions after you have submitted the AUTH request.

 


 

Additional notes

Fraud-prevention

Fraud and duplicate checks

Fraud and duplicate checks are not performed on paysafecard transactions.

 

Address Verification Service (AVS) checks

AVS checks cannot be performed on paysafecard transactions.

 

Protect Plus

Protect Plus can be enabled on your account to check the billing details submitted by the customer. Click here for further information.

 

Frozen cards

At the customer’s request, paysafecards can be “frozen”, to prevent all further purchases. Click here for further information.

 

If the customer fails to enter their PIN

After performing the ORDER request and receiving a successful response, the customer will have 30 minutes to enter their payment details on paysafecard’s website, after which the payment will be flagged as “expired” by paysafecard, and the customer will need to start again with a new ORDER.

 

Currencies

The following is a list of currencies that we support when processing paysafecard transactions:

ARS, AUD, BGN, CAD, CHF, CZK, DKK, EUR, GBP, HRK, HUF, MXN, NOK, NZD, PEN, PLN, RON, SEK, TRY, USD, UYU

Before you can process paysafecard transactions in any of these currencies, you must first ensure that they are enabled on your paysafecard account.

 

Account type

Only “ECOM” (e-commerce) is supported as the account type for paysafecard transactions. The customer must be present at time-of-purchase to enter their PIN, or to sign in to their account.

 

iframes

The paysafecard-hosted page can be hosted in an iframe.

Always allow vertical scrolling or dynamic sizing. Maximum height of 840px.

paysafecard’s payment page is optimised automatically for mobile devices.

If a customer is using a device with a resolution with width smaller than 600px, a payment panel optimised for mobile devices will be automatically shown. This is also the case if the embedded iframe has a smaller width than 600px.

Protect Plus

Protect Plus is a sophisticated counter-fraud service that provides your site with an extra layer of security against fraudulent transactions. It makes use of the industry’s largest negative database to perform a comprehensive suite of fraud assessments, including identity checks against the UK electoral roll and BT databases.

 

Process overview

Status good
Sign up for Protect Plus
Before you can get started, you will need to contact our Sales team and enable Protect Plus on your account.

 

What checks are performed?

We analyse the customer’s billing, delivery and payment details using a rule-based system to detect suspicious patterns in user activity. Our system will assist you in deciding on whether to process a customer’s transaction based on the perceived level of risk. Checks performed include:

 

Warning
Protect Plus does not guarantee against fraud
You should consider all data regarding a transaction before accepting the payment.

 

What happens after the checks are performed?

The Protect Plus system will analyse transaction details and issue one of the following fraudcontrolshieldstatuscode values:

“ACCEPT” The details are not deemed suspicious.
“CHALLENGE” Further investigation is recommended.
“DENY” The details are suspicious and a transaction should not be performed.
“NOSCORE” Transaction was declined by the acquirer before checks were performed.

 

Order of requests

Protect Plus checks are performed when you submit a RISKDEC request. You can update a standard AUTH request to also include a RISKDEC in two different ways:

 

RISKDEC then AUTH request

Process overview

 

Info
By default, when you opt to perform the RISKDEC before the AUTH, we automatically suspend authorised transactions when the fraudcontrolshieldstatuscode is “CHALLENGE” or “DENY”. This will allow you to investigate further and make a more informed choice on whether or not to authorise a suspicious transaction. This behaviour can be changed. Please contact the Support team for further information.

 

Request example

Here is an example of a combined RISKDEC then AUTH request. Notice how the structure is the same as a standard AUTH request, except “RISKDEC” is included in the requesttypedescriptions field before “AUTH”.


#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth= {
    "sitereference": "test_site12345",
    "requesttypedescriptions": ["RISKDEC","AUTH"],
    "accounttypedescription": "ECOM",
    "currencyiso3a": "GBP",
    "baseamount": "1011",
    "orderreference": "My_Order_123",
    "cachetoken": "token_posted_by_st.js"
}

strequest = securetrading.Request()
strequest.update(auth)
stresponse = st.process(strequest) #stresponse contains the transaction response
<?php

if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
  throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);

$configData = array(
'username' => '[email protected]',
'password' => 'Password1^',
);

$requestData = array(
  'sitereference' => 'test_site12345',
  'requesttypedescriptions' => array('RISKDEC','AUTH'),
  'accounttypedescription' => 'ECOM',
  'currencyiso3a' => 'GBP',
  'baseamount' => '1011',
  'orderreference' => 'My_Order_123',
  'cachetoken' => 'token_posted_by_st.js'
);

$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user [email protected]:Password1^ https://webservices.securetrading.net/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "[email protected]",
"version": "1.00",
"request": [{
  "currencyiso3a": "GBP",
  "requesttypedescriptions": ["RISKDEC","AUTH"],
  "sitereference": "test_site12345",
  "baseamount": "1011",
  "orderreference": "My_Order_123",
  "accounttypedescription": "ECOM",
  "cachetoken": "token_posted_by_st.js"
}]}'

 

Response example

Here is an example of a combined RISKDEC then AUTH response. Notice how the response is divided into two parts; the first represents the “RISKDEC” response and the second represents the “AUTH” response (as indicated by the values of the requesttypedescription fields).

For the RISKDEC response field specification, scroll down to the “Interpreting the response” section.


{
  u 'requestreference': u 'A0dcb11e6',
    u 'version': u '1.00',
    u 'response': [{
      u 'acquirerrecommendedaction': u 'C',
        u 'fraudcontrolresponsecode': u '0100',
        u 'paymenttypedescription': u 'VISA',
        u 'orderreference': u 'My_Order_123',
        u 'transactionstartedtimestamp': u '2016-12-07 16:19:28',
        u 'errormessage': u 'Ok',
        u 'operatorname': u '[email protected]',
        u 'fraudcontrolreference': u 'TEST',
        u 'accounttypedescription': u 'FRAUDCONTROL',
        u 'errorcode': u '0',
        u 'transactionreference': u '1-2-345678',
        u 'maskedpan': u '411111######1111',
        u 'requesttypedescription': u 'RISKDEC',
        u 'fraudcontrolshieldstatuscode': u 'ACCEPT',
        u 'livestatus': u '0'
    }, {
      u 'transactionstartedtimestamp': u '2016-12-07 16:19:28',
        u 'parenttransactionreference': u '1-2-345678',
        u 'livestatus': u '0',
        u 'issuer': u 'SecureTrading Test Issuer1',
        u 'splitfinalnumber': u '1',
        u 'dccenabled': u '0',
        u 'settleduedate': u '2016-12-07',
        u 'errorcode': u '0',
        u 'orderreference': u 'My_Order_123',
        u 'tid': u '27882788',
        u 'merchantnumber': u '00000000',
        u 'merchantcountryiso2a': u 'GB',
        u 'transactionreference': u '1-2-345679',
        u 'merchantname': u 'Test Merchant',
        u 'paymenttypedescription': u 'VISA',
        u 'baseamount': u '1011',
        u 'accounttypedescription': u 'ECOM',
        u 'acquirerresponsecode': u '00',
        u 'requesttypedescription': u 'AUTH',
        u 'securityresponsesecuritycode': u '2',
        u 'currencyiso3a': u 'GBP',
        u 'authcode': u 'TEST19',
        u 'errormessage': u 'Ok',
        u 'operatorname': u '[email protected]',
        u 'securityresponsepostcode': u '0',
        u 'maskedpan': u '411111######1111',
        u 'securityresponseaddress': u '0',
        u 'issuercountryiso2a': u 'US',
        u 'settlestatus': u '0'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A58cdfkpy"
  ["version"] => string(4) "1.00"
  ["response"] => array(2) {
    [0] => array(15) {
        ["errorcode"] => string(1) "0"
        ["orderreference"] => string(12) "My_Order_123"
        ["fraudcontrolresponsecode"] => string(4) "0100"
        ["paymenttypedescription"] => string(4) "VISA"
        ["maskedpan"] => string(16) "411111######1111"
        ["transactionstartedtimestamp"] => string(19) "2016-12-09 11:12:39"
        ["errormessage"] => string(2) "Ok"
        ["operatorname"] => string(23) "[email protected]"
        ["accounttypedescription"] => string(12) "FRAUDCONTROL"
        ["acquirerrecommendedaction"] => string(1) "C"
        ["transactionreference"] => string(9) "1-2-345678"
        ["requesttypedescription"] => string(7) "RISKDEC"
        ["fraudcontrolreference"] => string(4) "TEST"
        ["fraudcontrolshieldstatuscode"] => string(6) "ACCEPT"
        ["livestatus"] => string(1) "0"
      }
      [1] =>array(29) {
        ["transactionstartedtimestamp"] => string(19) "2016-12-09 11:12:39"
        ["parenttransactionreference"] => string(9) "1-2-345678"
        ["livestatus"] => string(1) "0"
        ["issuer"] => string(26) "SecureTrading Test Issuer1"
        ["splitfinalnumber"] => string(1) "1"
        ["dccenabled"] => string(1) "0"
        ["settleduedate"] => string(10) "2016-12-09"
        ["errorcode"] => string(1) "0"
        ["orderreference"] => string(12) "My_Order_123"
        ["tid"] => string(8) "27882788"
        ["merchantnumber"] => string(8) "00000000"
        ["merchantcountryiso2a"] => string(2) "GB"
        ["transactionreference"] => string(10) "1-2-345679"
        ["merchantname"] => string(13) "Test Merchant"
        ["paymenttypedescription"] => string(4) "VISA"
        ["baseamount"] => string(4) "1011"
        ["accounttypedescription"] => string(4) "ECOM"
        ["acquirerresponsecode"] => string(2) "00"
        ["requesttypedescription"] => string(4) "AUTH"
        ["securityresponsesecuritycode"] => string(1) "2"
        ["currencyiso3a"] => string(3) "GBP"
        ["authcode"] => string(6) "TEST53"
        ["errormessage"] => string(2) "Ok"
        ["operatorname"] => string(23) "[email protected]"
        ["securityresponsepostcode"] => string(1) "0"
        ["maskedpan"] => string(16) "411111######1111"
        ["securityresponseaddress"] => string(1) "0"
        ["issuercountryiso2a"] => string(2) "US"
        ["settlestatus"] => string(1) "0"
    }
  }
}
{"requestreference":"W23-wt77f0n8","version":"1.00","response":[{"errorcode":"0","fraudcontrolresponsecode":"0100","paymenttypedescription":"VISA","orderreference":"My_Order_123","transactionstartedtimestamp":"2016-12-07 16:23:03","errormessage":"Ok","operatorname":"[email protected]","accounttypedescription":"FRAUDCONTROL","acquirerrecommendedaction":"C","transactionreference":"1-2-345678","requesttypedescription":"RISKDEC","maskedpan":"411111######1111","fraudcontrolreference":"TEST","fraudcontrolshieldstatuscode":"ACCEPT","livestatus":"0"},{"transactionstartedtimestamp":"2016-12-07 16:23:03","parenttransactionreference":"1-2-345678","livestatus":"0","issuer":"SecureTrading Test Issuer1","splitfinalnumber":"1","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","baseamount":"1011","tid":"27882788","merchantnumber":"00000000","merchantcountryiso2a":"GB","transactionreference":"1-2-345679","merchantname":"Test Merchant","paymenttypedescription":"VISA","orderreference":"My_Order_123","accounttypedescription":"ECOM","acquirerresponsecode":"00","requesttypedescription":"AUTH","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST14","errormessage":"Ok","operatorname":"[email protected]","securityresponsepostcode":"0","maskedpan":"411111######1111","securityresponseaddress":"0","issuercountryiso2a":"US","settlestatus":"0"}],"secrand":"E0ksvyuH5VKg"}

 

AUTH then RISKDEC request

Process overview

 

 

Info
Specifying for the RISKDEC to be performed after the AUTH allows Trust Payments to take into account the results of AVS, Security Code Checks and 3-D Secure checks performed when analysing the submitted details for fraud.

 

Request example

Here is an example of a combined AUTH then RISKDEC request. Notice how the structure is the same as a standard AUTH request, except “RISKDEC” is included in the requesttypedescriptions field after “AUTH”.


#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth= {
    "sitereference": "test_site12345",
    "requesttypedescriptions": ["AUTH","RISKDEC"],
    "accounttypedescription": "ECOM",
    "currencyiso3a": "GBP",
    "baseamount": "1011",
    "orderreference": "My_Order_123",
    "cachetoken": "token_posted_by_st.js"
}

strequest = securetrading.Request()
strequest.update(auth)
stresponse = st.process(strequest) #stresponse contains the transaction response
<?php

if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
  throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);

$configData = array(
'username' => '[email protected]',
'password' => 'Password1^',
);

$requestData = array(
  'sitereference' => 'test_site12345',
  'requesttypedescriptions' => array('AUTH','RISKDEC'),
  'accounttypedescription' => 'ECOM',
  'currencyiso3a' => 'GBP',
  'baseamount' => '1011',
  'orderreference' => 'My_Order_123',
  'cachetoken' => 'token_posted_by_st.js'
);

$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user [email protected]:Password1^ https://webservices.securetrading.net/json/ -H "Content-type: application/json" -H "Accept: application/json" -d '{
"alias": "[email protected]",
"version": "1.00",
"request": [{
  "currencyiso3a": "GBP",
  "requesttypedescriptions": ["AUTH","RISKDEC"],
  "sitereference": "test_site12345",
  "baseamount": "1011",
  "orderreference": "My_Order_123",
  "accounttypedescription": "ECOM",
  "cachetoken": "token_posted_by_st.js"
}]}'

 

Response example

Here is an example of a combined AUTH then RISKDEC response. Notice how the response is divided into two parts; the first represents the “AUTH” response and the second represents the “RISKDEC” response (as indicated by the values of the requesttypedescription fields).

For the RISKDEC response field specification, scroll down to the “Interpreting the response” section.


{
  u 'requestreference': u 'Ad4ft45gp',
    u 'version': u '1.00',
    u 'response': [{
      u 'transactionstartedtimestamp': u '2016-12-07 16:25:19',
        u 'livestatus': u '0',
        u 'issuer': u 'SecureTrading Test Issuer1',
        u 'splitfinalnumber': u '1',
        u 'dccenabled': u '0',
        u 'settleduedate': u '2016-12-07',
        u 'errorcode': u '0',
        u 'orderreference': u 'My_Order_123',
        u 'tid': u '27882788',
        u 'merchantnumber': u '00000000',
        u 'merchantcountryiso2a': u 'GB',
        u 'transactionreference': u '1-2-345678',
        u 'merchantname': u 'Test Merchant',
        u 'paymenttypedescription': u 'VISA',
        u 'baseamount': u '1011',
        u 'accounttypedescription': u 'ECOM',
        u 'acquirerresponsecode': u '00',
        u 'requesttypedescription': u 'AUTH',
        u 'securityresponsesecuritycode': u '2',
        u 'currencyiso3a': u 'GBP',
        u 'authcode': u 'TEST57',
        u 'errormessage': u 'Ok',
        u 'operatorname': u '[email protected]',
        u 'securityresponsepostcode': u '0',
        u 'maskedpan': u '411111######1111',
        u 'securityresponseaddress': u '0',
        u 'issuercountryiso2a': u 'US',
        u 'settlestatus': u '0'
    }, {
      u 'acquirerrecommendedaction': u 'C',
        u 'fraudcontrolresponsecode': u '0100',
        u 'paymenttypedescription': u 'VISA',
        u 'orderreference': u 'My_Order_123',
        u 'transactionstartedtimestamp': u '2016-12-07 16:25:19',
        u 'errormessage': u 'Ok',
        u 'operatorname': u '[email protected]',
        u 'parenttransactionreference': u '1-2-345678',
        u 'fraudcontrolreference': u 'TEST',
        u 'accounttypedescription': u 'FRAUDCONTROL',
        u 'errorcode': u '0',
        u 'transactionreference': u '1-2-345679',
        u 'maskedpan': u '411111######1111',
        u 'requesttypedescription': u 'RISKDEC',
        u 'fraudcontrolshieldstatuscode': u 'ACCEPT',
        u 'livestatus': u '0'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A0bjmprty"
  ["version"] => string(4) "1.00"
  ["response"] => array(2) {
    [0] => array(28) {
        ["transactionstartedtimestamp"] => string(19) "2016-12-09 11:14:35"
        ["livestatus"] => string(1) "0"
        ["issuer"] => string(26) "SecureTrading Test Issuer1"
        ["splitfinalnumber"] => string(1) "1"
        ["dccenabled"] => string(1) "0"
        ["settleduedate"] => string(10) "2016-12-09"
        ["errorcode"] => string(1) "0"
        ["orderreference"] => string(12) "My_Order_123"
        ["tid"] => string(8) "27882788"
        ["merchantnumber"] => string(8) "00000000"
        ["securityresponsepostcode"] => string(1) "0"
        ["transactionreference"] => string(10) "1-2-345678"
        ["merchantname"] => string(13) "Test Merchant"
        ["paymenttypedescription"] => string(4) "VISA"
        ["baseamount"] => string(4) "1011"
        ["accounttypedescription"] => string(4) "ECOM"
        ["acquirerresponsecode"] => string(2) "00"
        ["requesttypedescription"] => string(4) "AUTH"
        ["securityresponsesecuritycode"] => string(1) "2"
        ["currencyiso3a"] => string(3) "GBP"
        ["authcode"] => string(6) "TEST01"
        ["errormessage"] => string(2) "Ok"
        ["operatorname"] => string(23) "[email protected]"
        ["merchantcountryiso2a"] => string(2) "GB"
        ["maskedpan"] => string(16) "411111######1111"
        ["securityresponseaddress"] => string(1) "0"
        ["issuercountryiso2a"] => string(2) "US"
        ["settlestatus"] => string(1) "0"
      }
      [1] => array(16) {
        ["errorcode"] => string(1) "0"
        ["orderreference"] => string(12) "My_Order_123"
        ["fraudcontrolresponsecode"] => string(4) "0100"
        ["paymenttypedescription"] => string(4) "VISA"
        ["maskedpan"] => string(16) "411111######1111"
        ["transactionstartedtimestamp"] => string(19) "2016-12-09 11:14:35"
        ["errormessage"] => string(2) "Ok"
        ["operatorname"] => string(23) "[email protected]"
        ["parenttransactionreference"] => string(10) "1-2-345678"
        ["accounttypedescription"] => string(12) "FRAUDCONTROL"
        ["acquirerrecommendedaction"] => string(1) "C"
        ["transactionreference"] => string(9) "1-2-345679"
        ["requesttypedescription"] => string(7) "RISKDEC"
        ["fraudcontrolreference"] => string(4) "TEST"
        ["fraudcontrolshieldstatuscode"] => string(6) "ACCEPT"
        ["livestatus"] => string(1) "0"
      }
  }
}
{"requestreference":"W23-eyqd5u3x","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 16:24:50","livestatus":"0","issuer":"SecureTrading Test Issuer1","splitfinalnumber":"1","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","baseamount":"1011","tid":"27882788","merchantnumber":"00000000","merchantcountryiso2a":"GB","transactionreference":"1-2-345678","merchantname":"Test Merchant","paymenttypedescription":"VISA","orderreference":"My_Order_123","accounttypedescription":"ECOM","acquirerresponsecode":"00","requesttypedescription":"AUTH","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST12","errormessage":"Ok","operatorname":"[email protected]","securityresponsepostcode":"0","maskedpan":"411111######1111","securityresponseaddress":"0","issuercountryiso2a":"US","settlestatus":"0"},{"errorcode":"0","fraudcontrolresponsecode":"0150","paymenttypedescription":"VISA","orderreference":"My_Order_123","transactionstartedtimestamp":"2016-12-07 16:24:50","errormessage":"Ok","operatorname":"[email protected]","parenttransactionreference":"1-2-345678","accounttypedescription":"FRAUDCONTROL","acquirerrecommendedaction":"C","transactionreference":"1-2-345679","requesttypedescription":"RISKDEC","maskedpan":"411111######1111","fraudcontrolreference":"TEST","fraudcontrolshieldstatuscode":"ACCEPT","livestatus":"0"}],"secrand":"ft9j6l"}

 

Interpreting the response

The AUTH part of the response follows the same structure as a standard AUTH response. The RISKDEC part of the response contains new fields that are described below:

 

Key

Field name Type Length Response Description
requesttypedescription Alpha 20 You will be returned “RISKDEC”.
fraudcontrolshieldstatuscode Alpha 10 One of the following values:

  • “ACCEPT” – The details are not deemed suspicious.
  • “CHALLENGE” – Further investigation is recommended.
  • “DENY” – The details are suspicious and a transaction should not be performed.
  • “NOSCORE” – Returned when a parent AUTH Request has been declined.
fraudcontrolreference Alphanumeric 255 Unique reference to identify the Risk Decision check performed.
fraudcontrolresponsecode Numeric 4 A numeric code that is mapped to further information on the results of the Risk Decision checks performed.
acquirerrecommendedaction Char 1 Either:

  • “C” – Continue with the transaction.
  • “S” – Stop transaction.

Note that this ONLY a recommendation. Protect Plus does not guarantee against fraud.

rulecategoryflag Alphanumeric 255 Reference used to identify a condition that was met to return the DENY or CHALLENGE fraudcontrolshieldstatuscode.
rulecategorymessage Alphanumeric Not defined Condition that was met to return the DENY or CHALLENGE fraudcontrolshieldstatuscode.

 

Testing

We recommend that you thoroughly test your solution before enabling on your live Site Reference.
Click here for details that you can submit to simulate different RISKDEC responses on our test system.

 

Protect Plus with 3-D Secure

Protect Plus can be used in conjunction with 3-D Secure.

 

Method A – RISKDEC before THREEDQUERY and AUTH

When performing the RISKDEC request before the THREEDQUERY and AUTH, the RISKDEC response can assist you in deciding whether or not to proceed with the transaction. We automatically suspend transactions deemed suspicious by the Protect Plus system.

Here is the flow to follow:

  1. Your system submits a RISKDEC request.
  2. Your system submits a THREEDQUERY request, ensuring the transactionreference returned in the RISKDEC response is submitted in the parenttransactionreference field.
    Note: If the fraudcontrolshieldstatuscode is “CHALLENGE” or “DENY”, the THREEDQUERY will fail, returning the errorcode “60107”.
  3. You will need to redirect the customer’s browser to the ACS, and then process the AUTH (if the customer has been successfully authenticated).

 

Method B – THREEDQUERY and AUTH before RISKDEC

When performing the RISKDEC request after the THREEDQUERY and AUTH, information on whether or not the customer is enrolled in 3-D Secure (in addition to the results of the AVS and security code checks) can be used by the Protect Plus system to assist you in deciding whether or not to proceed with the transaction.

Here is the flow to follow:

  1. Your system submits a THREEDQUERY request.
  2. You will need to redirect the customer’s browser to the ACS, and then process the AUTH (if the customer has been successfully authenticated).
  3. Your system submits a RISKDEC request, ensuring the transactionreference returned in the AUTH response is submitted in the parenttransactionreference field.
    Note: If the fraudcontrolshieldstatuscode is “CHALLENGE” or “DENY”, we recommend that you suspend the transaction for review (update to settle status “2”).

 

investors in people logo   pci - security standards council logo

TRUST Payments LTD, No.1 Royal Exchange, London, EC3V 3DG.
A company registered in England and Wales with Company Number 04591066. VAT Number 756265116