paysafecard for Webservices API

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.

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

Supported customer countries	No restrictions on customer countries
Supported currencies	ARS, AUD, BGN, CAD, CHF, CZK, DKK, EUR, GBP, HUF, MXN, NOK, NZD, PEN, PLN, RON, SEK, TRY, USD, UYU
Refunds	Only Payouts are supported.
Chargebacks	Payments are not subject to chargebacks.
Zero-authorisation	Not supported.
Recurring payments	Not supported.

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 “myPaysafe” 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:

Initiate the customer
- Customer agrees to a payment using paysafecard on the merchant's website.
- Merchant submits ORDER request to initiate the session, including cancelurl and returnurl.
- Merchant receives ORDER response, including customerredirecturl.
Redirect to paysafecard
- Merchant redirects the customer's browser to the customerredirecturl.
- Customer enters the PIN(s) found on their paysafecard, or signs in.
- If successful, the customer's browser is redirected to the returnurl.
  
  If the paysafecard order is cancelled, the browser is redirected to the cancelurl where an error message can be displayed. We recommend that alternative payment methods are displayed, allowing the customer to try again.
Processing the authorisation
- Only if the above has been successful, the merchant submits an AUTH request to process the payment.
- Merchant receives AUTH response and displays receipt page to the customer.

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 = "webservices@example.com"
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' => 'webservices@example.com',
  '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 webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
  "alias": "webservices@example.com",
  "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":"webservices@example.com",
  "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"
  }]
}'

<requestblock version="3.67">
  <alias>webservices@example.com</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, HUF, MXN, NOK, NZD, PEN, PLN, RON, SEK, TRY, USD, UYU Click here for further information on currency codes.
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 “ORDER”.
returnurl XPath: /merchant/returnurl	URL (2048)	The URL that the customer will be returned to following confirmation of payment by paysafecard.
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.
orderreference XPath: /merchant/orderreference	Alphanumeric including symbols (25) Recommended length 25 characters or less (exact length dependent on acquiring bank). Failure to adhere to this requirement may result in the text being truncated in the transaction.	Your unique order reference that can be stored on the Trust Payments system.
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 “myPaysafe” 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 “myPaysafe” account holder. e.g. To restrict to over-18s only, submit “18” in this field.

ORDER response example

{
u 'requestreference': u 'A0bxh87wt',
u 'version': u '1.00',
u 'responses': [{
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 'webservices@example.com',
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"
  ["responses"] =>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) "webservices@example.com"
      ["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":"webservices@example.com",
    "livestatus":"0",
    "paysafeminage":"18",
    "paysafekyclevel":"SIMPLE",
    "paysafecountryrestriction":"DE",
    "paysafeid":"23842"
  }],
  "secrand":"zO9"
}

<responseblock version="3.67">
  <requestreference>X62d3qhev</requestreference>
  <response type="ORDER">
    <merchant>
      <operatorname>webservices@example.com</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.
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”.
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.
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.
errordata XPath: /error/data	Alphanumeric (255)	Additional information to help troubleshoot the error. Only returned if there has been an error.
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. Returned if submitted in the ORDER request.
paysafekyclevel XPath: /billing/payment/paysafe/kyclevel	Alpha (6)	Specifies the required KYC level for the “myPaysafe” 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). Returned if submitted in the ORDER request.
paysafeminage XPath: /billing/payment/paysafe/minage	Numeric (3)	The minimum age of the “myPaysafe” account holder, as specified in the ORDER request. Returned if submitted in the ORDER request.

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:

Entering the PIN found on their card (they can enter multiple PINs if needed).
Signing in to their “myPaysafe” account.

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

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 “myPaysafe” account to verify their details (e.g. to check their age). For further information, please refer to paysafecard’s own resources (link to external site).

If successful authentication

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

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.

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 authorisations

If the customer is redirected to the cancelurl:

Present your customer with alternative payment methods so they can try again.

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 = "webservices@example.com"
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' => 'webservices@example.com',
  '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 webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
  "alias": "webservices@example.com",
  "version": "1.00",
  "request": [{
    "requesttypedescription": "AUTH",
    "sitereference": "test_site12345",
    "parenttransactionreference": "72-32-20002",
    "paymenttypedescription": "PAYSAFECARD"
  }]
}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "requesttypedescription":"AUTH",
    "sitereference":"test_site12345",
    "parenttransactionreference":"72-32-20002",
    "paymenttypedescription":"PAYSAFECARD"
  }]
}

<requestblock version="3.67">
  <alias>webservices@example.com</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 'responses': [{
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 'webservices@example.com',
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"
  ["responses"] => 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) "webservices@example.com"
      ["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":"webservices@example.com",
    "livestatus":"0",
    "settlestatus":"0",
    "paysafeminage":"18",
    "paysafekyclevel":"SIMPLE",
    "paysafecountryrestriction":"DE",
    "paysafeid":"23842"
  }],
  "secrand":"zO9"
}

<responseblock version="3.67">
  <requestreference>X538160153</requestreference>
  <response type="AUTH">
    <merchant>
      <merchantname>My Test Site</merchantname>
      <merchantnumber>00000000</merchantnumber>
      <operatorname>webservices@example.com</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.
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.
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”.
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.
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.
errordata XPath: /error/data	Alphanumeric (255)	Additional information to help troubleshoot the error. Only returned if there has been an error.
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. Depends on your account configuration.
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. Returned if submitted in the ORDER request.
paysafekyclevel XPath: /billing/payment/paysafe/kyclevel	Alpha (6)	Specifies the required KYC level for the “myPaysafe” 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). Returned if submitted in the ORDER request.
paysafeminage XPath: /billing/payment/paysafe/minage	Numeric (3)	The minimum age of the “myPaysafe” account holder, as specified in the ORDER request. Returned if submitted in the ORDER request.

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:

Base Amount (baseamount) (e.g. £10.50 is “1050”)*
Main Amount (mainamount) (e.g. £10.50 is “10.50”)*
Billing Country (billingcountryiso2a)
Currency (currencyiso3a)
Error Code (errorcode)
Live Status (livestatus)
Order Reference (orderreference)
Payment Type (paymenttypedescription)
Request Type (requesttypedescription)
Settle Status (settlestatus)
Site Reference (sitereference)
Transaction Reference (transactionreference)
Transaction Started Timestamp (transactionstartedtimestamp)

*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 our URL notifications documentation. In particular, you will need to look at the settlestatus value:

If the settlestatus is “100”, this indicates the payment has been authorised and the funds have been settled into your account.
Alternatively, if the settlestatus is “3”, this indicates an error occurred and the payment was cancelled. You can use the errorcode to determine the cause of the error.

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.

Payouts

You can process Payout requests using the Webservices API to transfer funds to the customer's "myPaysafe" account.

You will need to have a paysafecard CFT Merchant Number associated with your Trust Payments account. If you are unsure if your merchant number supports this, we recommend contacting paysafecard for clarification. Additionally, please ensure you are following any guidelines outlined by paysafecard before proceeding.

There are two methods of identifying the customer's account in the request. You can opt to submit either:

customeraccountnumber and customeraccountnumbertype (as shown in the examples below)
OR the billingemail

Following a successful Payout, the funds are settled immediately into the customer's "myPaysafe" account. You cannot cancel or otherwise update paysafecard Payouts following settlement.

Refer to the examples and field schema below to learn how to construct a Payout request to Trust Payments and what to expect to be returned in the response.

Payout request example

This example demonstrates how to process a Payout request for paysafecard.

#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth = {
  "requesttypedescription": "REFUND",
  "sitereference": "test_site12345",
  "accounttypedescription": "CFT",
  "billingid": "000001",
  "currencyiso3a": "GBP",
  "baseamount": "2001",
  "paymenttypedescription": "PAYSAFECARD",
  "billingdob": "2012-01-26",
  "billingfirstname": "Joe",
  "billinglastname": "Bloggs",
  "customeraccountnumbertype": "ACCOUNT",
  "customeraccountnumber": "123456789012"
}

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' => 'webservices@example.com',
  'password' => 'Password1^'
);

$requestData = array(
  'requesttypedescription' => 'REFUND',
  'sitereference' => 'test_site12345',
  'accounttypedescription' => 'CFT',
  'billingid' => '000001',
  'currencyiso3a' => 'GBP',
  'baseamount' => '2001',
  'paymenttypedescription' => 'PAYSAFECARD',
  'billingdob' => '2012-01-26',
  'billingfirstname' => 'Joe',
  'billinglastname' => 'Bloggs',
  'customeraccountnumbertype' => 'ACCOUNT',
  'customeraccountnumber' => '123456789012'
);

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

?>

curl --user webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
  "alias": "webservices@example.com",
  "version": "1.00",
  "request": [{
    "requesttypedescription":"REFUND",
    "sitereference":"test_site12345",
    "accounttypedescription":"CFT",
    "billingid":"000001",
    "currencyiso3a":"GBP",
    "baseamount":"2001",
    "paymenttypedescription":"PAYSAFECARD",
    "billingdob":"2012-01-26",
    "billingfirstname":"Joe",
    "billinglastname":"Bloggs",
    "customeraccountnumbertype":"ACCOUNT",
    "customeraccountnumber":"123456789012"
  }]
}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "requesttypedescription":"REFUND",
    "sitereference":"test_site12345",
    "accounttypedescription":"CFT",
    "billingid":"000001",
    "currencyiso3a":"GBP",
    "baseamount":"2001",
    "paymenttypedescription":"PAYSAFECARD",
    "billingdob":"2012-01-26",
    "billingfirstname":"Joe",
    "billinglastname":"Bloggs",
    "customeraccountnumbertype":"ACCOUNT",
    "customeraccountnumber":"123456789012"
  }]
}'

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="REFUND">
    <operation>
      <sitereference>test_site12345</sitereference>
      <accounttypedescription>CFT</accounttypedescription>
    </operation>
    <billing id="000001">
      <amount currencycode="GBP">2001</amount>
      <payment type="PAYSAFECARD"/>
      <dob>2012-01-26</dob>
      <name>
        <first>Joe</first>
        <last>Bloggs</last>
      </name>
    </billing>
    <customer>
      <accountnumber type="ACCOUNT">123456789012</accountnumber>
    </customer>
  </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)	The value in the request must be “CFT”.
baseamount XPath: /billing/amount	Numeric (11)	The amount of the Payout in base units, with no commas or decimal points, so €10 is submitted as 1000. This value must be greater than zero.
billingdob XPath: /billing/dob	Date YYYY-MM-DD	Customer's date of birth.
billingfirstname XPath: /billing/name/first	Alphanumeric including symbols (127)	Customer's first name.
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.
billinglastname XPath: /billing/name/last	Alphanumeric including symbols (127)	Customer's last name.
currencyiso3a XPath: /billing/amount/@currencycode	Alpha (3)	The currency that the transaction will be processed in (in ISO3A format). For a list of currency codes supported by paysafecard, refer to the list found at the top of this page.
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 “REFUND”.
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.
billingemail XPath: /billing/email	Email (255)	Needs to be the email that the customer used to register for "myPaysafe". Required if customeraccountnumber and customeraccountnumbertype not submitted.
customeraccountnumber XPath: /customer/accountnumber	Numeric (12)	Id of the "myPaysafe" account of the customer. Required if billingemail not submitted.
customeraccountnumbertype XPath: /customer/accountnumber/@type	Alpha (7)	The value in the request must be “ACCOUNT”. Required if billingemail not submitted.

Payout response example

Here is an example of a successful Payout response for paysafecard.

{
u 'requestreference': u 'A0dcb11e6',
u 'version': u '1.00',
u 'responses': [{
u 'requesttypedescription': u 'REFUND',
u 'acquirertransactionreference': u '1234-5678-9012-3456',
u 'baseamount': u '2001',
u 'currencyiso3a': u 'GBP',
u 'paymenttypedescription': u 'PAYSAFECARD',
u 'customeraccountnumbertype': u 'ACCOUNT',
u 'maskedcustomeraccountnumber': u '123456##9012',
u 'errorcode': u '0',
u 'errormessage': u 'Ok',
u 'livestatus': u '0',
u 'merchantname': u 'Test Merchant',
u 'merchantnumber': u '00000000',
u 'operatorname': u 'webservices@example.com',
u 'accounttypedescription': u 'CFT',
u 'paysafeid': u '23843',
u 'settleduedate': u '2022-02-08',
u 'settlestatus': u '100',
u 'transactionstartedtimestamp': u '2022-02-08 14:39:18',
u 'transactionreference': u '1-2-347'
}]
}

array(3) {
  ["requestreference"] => string(9) "A58cdfkpy"
  ["version"] => string(4) "1.00"
  ["responses"] => array(1) {
    [1] =>array(19) {
      ["requesttypedescription"] => string(6) "REFUND"
      ["acquirertransactionreference"] => string(19) "1234-5678-9012-3456"
      ["baseamount"] => string(4) "2001"
      ["currencyiso3a"] => string(3) "GBP"
      ["paymenttypedescription"] => string(11) "PAYSAFECARD"
      ["customeraccountnumbertype"] => string(7) "ACCOUNT"
      ["maskedcustomeraccountnumber"] => string(12) "123456##9012"
      ["errorcode"] => string(1) "0"
      ["errormessage"] => string(2) "Ok"
      ["livestatus"] => string(1) "0"
      ["merchantname"] => string(13) "Test Merchant"
      ["merchantnumber"] => string(8) "00000000"
      ["operatorname"] => string(23) "webservices@example.com"
      ["accounttypedescription"] => string(3) "CFT"
      ["paysafeid"] => string(5) "23843"
      ["settleduedate"] => string(10) "2022-02-08"
      ["settlestatus"] => string(3) "100"
      ["transactionstartedtimestamp"] => string(19) "2022-02-08 14:39:18"
      ["transactionreference"] => string(7) "1-2-347"
    }
  }
}

{
  "requestreference":"W23-fjgvn3d8",
  "version":"1.00",
  "response":[{
    "requesttypedescription":"REFUND",
    "acquirertransactionreference":"1234-5678-9012-3456",
    "baseamount":"2001",
    "currencyiso3a":"GBP",
    "paymenttypedescription":"PAYSAFECARD",
    "customeraccountnumbertype":"ACCOUNT",
    "maskedcustomeraccountnumber":"123456##9012",
    "errorcode":"0",
    "errormessage":"Ok",
    "livestatus":"0",
    "merchantname":"Test Merchant",
    "merchantnumber":"00000000",
    "operatorname":"webservices@example.com",
    "accounttypedescription":"CFT",
    "paysafeid":"23843",
    "settleduedate":"2022-02-08",
    "settlestatus":"100",
    "transactionstartedtimestamp":"2022-02-08 14:39:18",
    "transactionreference":"1-2-347"
  }],
  "secrand":"789"
}

<responseblock version="3.67">
  <requestreference>X19vnxntc</requestreference>
  <response type="REFUND">
    <acquirertransactionreference>1234-5678-9012-3456</acquirertransactionreference>
    <billing>
      <amount currencycode="GBP">2001</amount>
      <payment type="PAYSAFECARD"/>
    </billing>
    <customer>
      <accountnumber type="ACCOUNT">123456##9012</accountnumber>
    </customer>
    <error>
      <code>0</code>
      <message>Ok</message>
    </error>
    <live>0</live>
    <merchant>
      <merchantname>Test Merchant</merchantname>
      <merchantnumber>00000000</merchantnumber>
      <operatorname>webservices@example.com</operatorname>
    </merchant>
    <operation>
      <accounttypedescription>CFT</accounttypedescription>
    </operation>
    <paysafe id="23843"/>
    <settlement>
      <settleduedate>2022-02-08</settleduedate>
      <settlestatus>100</settlestatus>
    </settlement>
    <timestamp>2022-02-08 14:39:18</timestamp>
    <transactionreference>1-2-347</transactionreference>
  </response>
  <secrand>789</secrand>
</responseblock>

Field specification

Field	Format	Description
accounttypedescription XPath: /operation/accounttypedescription	Alpha (20)	The value returned is “CFT”.
acquirertransactionreference XPath: /acquirertransactionreference	Alphanumeric including symbols (127)	Unique transaction reference assigned by paysafecard.
baseamount XPath: /billing/amount	Numeric (11)	The amount of the Payout 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.
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”.
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.
requesttypedescription XPath: /@type	Alpha (20)	The value returned is “REFUND”.
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.
customeraccountnumbertype XPath: /customer/accountnumber/@type	Alpha (7)	The value returned is “ACCOUNT”. Only returned if submitted in the request.
errordata XPath: /error/data	Alphanumeric (255)	Additional information to help troubleshoot the error. Only returned if there has been an error.
maskedcustomeraccountnumber XPath: /customer/accountnumber	Numeric & # (20)	Masked id of the "myPaysafe" account of the customer. Only returned if submitted in the request.
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. Depends on your account configuration.
merchantnumber XPath: /merchant/merchantnumber	Alphanumeric (32)	The merchant number that was used to process the transaction. Provided by the acquiring bank. Depends on your account configuration.

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.

Blocked cards

paysafecards can be blocked to prevent all further purchases at the customer's request.

Click here for further information (link to external site).

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.

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.

Further reading on this topic