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

Features
![]() |
![]() |
![]() |
![]() |
![]() |
Supported.![]() |
![]() |
![]() |
![]() |
![]() |
Configuration
To enable SafetyPay 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

- Customer agrees to a payment using SafetyPay on the merchant’s website.
- Merchant submits AUTH request to initiate the session, including the successfulurlredirect and errorurlredirect.
- Merchant receives AUTH response, including redirecturl.

- Merchant redirects the customer’s browser to the redirecturl.
- Customer follows instructions on SafetyPay’s hosted pages to authorise the payment.
- If successful, the browser is redirected to the successfulurlredirect, a page hosted by the merchant that displays confirmation of payment.
- If there has been a problem with the payment, the browser is redirected to the errorurlredirect, a page hosted by the merchant that displays an error to the customer.

- At a later time, SafetyPay will contact Trust Payments with confirmation that funds have been settled.
- Trust Payments will submit a URL notification to the merchant’s system to confirm funds have settled.
- Merchant receives the notification and responds to inform Trust Payments the notification was received successfully.
1. Initiate the customer
When the customer chooses to pay with SafetyPay, your system will need to perform an AUTH request and, if successful, redirect the customer’s browser to the URL returned in the response.
AUTH request
The example request below is for a SafetyPay AUTH request:
#!/usr/bin/python import securetrading stconfig = securetrading.Config() stconfig.username = "[email protected]" stconfig.password = "Password1^" st = securetrading.Api(stconfig) auth = { "currencyiso3a": "EUR", "requesttypedescription": "AUTH", "accounttypedescription": "ECOM", "sitereference": "test_site12345", "baseamount": "1050", "paymenttypedescription": "SAFETYPAY", "successfulurlredirect": "https://yourwebsite.com", "errorurlredirect": "https://yourwebsite.com", "billingfirstname": "Joe", "billinglastname": "Bloggs", "billingcountryiso2a": "DE" } 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( 'currencyiso3a' => 'EUR', 'requesttypedescription' => 'AUTH', 'accounttypedescription' => 'ECOM', 'sitereference' => 'test_site12345', 'baseamount' => '1050', 'paymenttypedescription' => 'SAFETYPAY', 'successfulurlredirect' => 'https://yourwebsite.com', 'errorurlredirect' => 'https://yourwebsite.com', 'billingfirstname' => 'Joe', 'billinglastname' => 'Bloggs', 'billingcountryiso2a' => '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": "EUR", "requesttypedescription": "AUTH", "accounttypedescription": "ECOM", "sitereference": "test_site12345", "baseamount": "1050", "paymenttypedescription": "SAFETYPAY", "successfulurlredirect": "https://www.example.com/success", "errorurlredirect": "https://www.example.com/error", "billingfirstname": "Joe", "billinglastname": "Bloggs", "billingcountryiso2a": "DE" }]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"EUR","requesttypedescription":"AUTH","accounttypedescription":"ECOM","sitereference":"test_site12345","baseamount":"1050","paymenttypedescription":"SAFETYPAY","successfulurlredirect":"https:\/\/www.example.com\/success","errorurlredirect":"https:\/\/www.example.com\/error","billingfirstname":"Joe","billinglastname":"Bloggs","billingcountryiso2a":"DE"}]}
<?xml version='1.0' encoding='utf-8'?> <requestblock version="3.67"> <alias>[email protected]</alias> <request type="AUTH"> <merchant> <successfulurlredirect>https://www.example.com/success</successfulurlredirect> <errorurlredirect>https://www.example.com/error</errorurlredirect> </merchant> <billing> <name> <first>Joe</first> <last>Bloggs</last> </name> <country>ES</country> <amount currencycode="EUR">1050</amount> <payment type="SAFETYPAY"/> </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 (13) | 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. (Max length may vary depending on your acquiring bank – Contact your bank for further info) |
![]() |
billingprefixname XPath: /billing/name/prefix |
Alphanumeric including symbols (25) |
The prefix of the customer’s billing name (e.g. Mr, Miss, Dr). |
![]() |
billingfirstname XPath: /billing/name/first |
Alphanumeric including symbols (127) |
The customer’s billing first name. |
![]() |
billingmiddlename XPath: /billing/name/middle |
Alphanumeric including symbols (127) |
The customer’s billing middle name(s). |
![]() |
billinglastname XPath: /billing/name/last |
Alphanumeric including symbols (127) |
The customer’s billing last name. |
![]() |
billingsuffixname XPath: /billing/name/suffix |
Alphanumeric including symbols (25) |
The suffix of the customer’s billing name (e.g. Bsc). |
![]() |
billingcountryiso2a XPath: /billing/country |
Alpha (2) | The country for the customer’s billing address. This will need to be in ISO2A format.
For a list of country codes supported by SafetyPay, refer to the list found at the top of this page. |
![]() |
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 SafetyPay, refer to the list found at the top of this page. |
![]() |
errorurlredirect XPath: /merchant/errorurlredirect |
URL (2048) | The URL that the customer will be returned to following an error on the SafetyPay-hosted pages. |
![]() |
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 “SAFETYPAY”. |
![]() |
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. |
![]() |
successfulurlredirect XPath: /merchant/successfulurlredirect |
URL (2048) | The URL that the customer will be returned to following a successful authorisation by SafetyPay. |
AUTH response
{ u'requestreference': u'An3ug1kap', u'version': u'1.00', u'response': [{ u'transactionreference': u'23-86-113', u'merchantname': u'Test Merchant', u'paymenttypedescription': u'SAFETYPAY', u'settleduedate': u'2017-03-16', u'baseamount': u'1050', u'transactionstartedtimestamp': u'2017-03-16 16:25:08', u'errormessage': u'Ok', u'settlestatus': u'10', u'accounttypedescription': u'ECOM', u'errorcode': u'0', u'redirecturl': u'https://example.com', u'acquirertransactionreference': u'12', u'acquirersecret': u'q9gy5ppgdyd5fh60kfe2j0f26peu2xww', u'requesttypedescription': u'AUTH', u'acquirerresponsemessage': u'PENDING', u'operatorname': u'[email protected]', u'livestatus': u'0', u'currencyiso3a': u'EUR' }] }
array(3) { ["requestreference"] => string(9) "A0345jmuw" ["version"] => string(4) "1.00" ["response"] => array(1) { [0] => array(18) { ["transactionreference"] => string(9) "23-86-113" ["merchantname"] => string(4) "Test Merchant" ["paymenttypedescription"] => string(10) "SAFETYPAY" ["settleduedate"] => string(10) "2017-03-16" ["baseamount"] => string(4) "1050" ["transactionstartedtimestamp"] => string(19) "2017-03-16 16:25:08" ["errormessage"] => string(2) "Ok" ["settlestatus"] => string(2) "10" ["accounttypedescription"] => string(4) "ECOM" ["errorcode"] => string(1) "0" ["redirecturl"] => string(107) "https://example.com" ["acquirertransactionreference"] => string(2) "12" ["acquirersecret"] => string(32) "q9gy5ppgdyd5fh60kfe2j0f26peu2xww" ["requesttypedescription"] => string(4) "AUTH" ["acquirerresponsemessage"] => string(7) "PENDING" ["operatorname"] => string(11) "[email protected]" ["livestatus"] => string(1) "0" ["currencyiso3a"] => string(3) "EUR" } } }
{"requestreference":"W23-fjgvn3d9","version":"1.00","response":[{"transactionreference":"23-86-113","merchantname":"Test Merchant","paymenttypedescription":"SAFETYPAY","settleduedate":"2017-03-16","baseamount":"1050","transactionstartedtimestamp":"2017-03-16 16:25:08","errormessage":"Ok","settlestatus":"10","accounttypedescription":"ECOM","errorcode":"0","redirecturl":"https:\/\/example.com","acquirertransactionreference":"12","acquirersecret":"q9gy5ppgdyd5fh60kfe2j0f26peu2xww","requesttypedescription":"AUTH","acquirerresponsemessage":"PENDING","operatorname":"[email protected]","livestatus":"0","currencyiso3a":"EUR"}]}
<?xml version='1.0' encoding='utf-8'?> <responseblock version="3.67"> <requestreference>Xd4nk260v</requestreference> <response type="AUTH"> <merchant> <merchantname>Test Merchant</merchantname> <operatorname>[email protected]</operatorname> </merchant> <transactionreference>44-86-102</transactionreference> <timestamp>2017-03-16 17:34:16</timestamp> <acquirersecret>gfc8mx0p2fx26f1n5tpy6mtk21naap8c</acquirersecret> <operation> <accounttypedescription>ECOM</accounttypedescription> </operation> <settlement> <settleduedate>2017-03-16</settleduedate> <settlestatus>10</settlestatus> </settlement> <acquirerresponsemessage>PENDING</acquirerresponsemessage> <billing> <amount currencycode="EUR">1050</amount> <payment type="SAFETYPAY"/> </billing> <live>0</live> <other> <redirecturl>https://example.com</redirecturl> </other> <acquirertransactionreference>4</acquirertransactionreference> <error> <message>Ok</message> <code>0</code> </error> </response> <secrand>Z1W</secrand> </responseblock>
Field specification
Field | Format | Description | |
![]() |
accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) | The value returned is “ECOM”. |
![]() |
acquirerresponsemessage XPath: /acquirerresponsemessage |
Alphanumeric (255) | Used by your acquirer to indicate the outcome of the request. |
![]() |
acquirersecret XPath: /acquirersecret |
Alphanumeric (64) | Used by Trust Payments to verify the response from the acquirer. (Your system does not need to verify this) |
![]() |
acquirertransactionreference XPath: /acquirertransactionreference |
Alphanumeric including symbols (127) | Unique transaction reference assigned by SafetyPay. |
![]() |
baseamount XPath: /billing/amount |
Numeric (13) | 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).
For a list of currency codes supported by SafetyPay, refer to the list found at the top of this page. |
![]() |
errorcode XPath: /error/code |
Numeric (1-5) | The error code should be used to determine if the request was successful or not.
|
![]() |
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. |
![]() |
livestatus XPath: /live |
Numeric (1) |
|
![]() |
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. |
![]() |
paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | This value returned is “SAFETYPAY”. |
![]() |
redirecturl XPath: /other/redirecturl |
URL (255) | Redirect the customer’s browser to this URL to allow them to complete the payment on SafetyPay’s hosted pages. |
![]() |
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) | This allows you to determine the status of the payment. Refer to the Handling the response section below for information on how to best interpret this field. |
![]() |
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. |
Handling the response
The settlestatus returned in the AUTH response is used to determine the status of the SafetyPay payment:

- The funds have not yet been settled into your bank account.
- The next step is to redirect the customer’s browser to the redirecturl to complete the payment.
Funds will not be settled into your account until the customer is redirected to SafetyPay’s pages, in order to complete the payment. Read on for further information.
- When there is an update to the settle status of the AUTH, you will receive a URL notification to inform you that the settlestatus has been updated to either “3” or “100”.
- Further information on the notifications can be found below.

- The payment has been declined, or has encountered an error.
- To learn more about why the payment was unsuccessful, you will need to look at the errorcode. e.g. “70000” indicates that the payment was declined. Click here for a full list of error codes.
In addition to the above, we also recommend following our Best practices.
2. Redirect to SafetyPay
Your system will need to redirect the customer’s browser to the redirecturl, which is a page hosted by SafetyPay, in order to process the payment. At a later time, the customer will be redirected back to either the successfulurlredirect or the errorurlredirect provided in the AUTH request.

The customer successfully completed the required steps on SafetyPay’s pages.
Recommended actions: Display confirmation that the payment was successful.

The customer encountered a problem that has prevented them from completing the payment.
Recommended actions: Inform the customer that there was a problem with the payment, displaying sufficient transaction details for the customer to query the payment attempt.

3. Payment completion
Once the customer returns from the SafetyPay hosted page to either the successfulurlredirect or errorurlredirect hosted on your site, you will need to display either a confirmation or error message respectively.

Once a payment has been authorised, funds will be settled at a later time, as determined by SafetyPay.


In the unlikely event that payment is still pending settlement after 7 days (settlestatus “10”), this will be scheduled for investigation and we will contact you with further information.
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 in the following scenarios:
- When a payment is authorised.
- When funds have been settled.
Configuring the authorisation notification
We recommend including at least the following fields in your authorisation notification:
- Acquirer Response Message (acquirerresponsemessage)
- 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.
Configuring the settlement notification
We recommend including the following fields in your settlement notification:
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
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 updated settlestatus value:
- On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).
- On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

Testing
You will need to test your solution before you can begin processing live payments. Test transactions are processed through your test Site Reference.

You will need to contact our Support team, providing your SafetyPay test account details. We will then configure your test site reference to connect directly to the SafetyPay testing environment.
When performing test transactions, the redirect URL returned in the AUTH response will redirect your browser to the SafetyPay testing environment to simulate a payment. Other than this, the process will be exactly the same as processing live payments.
Refunds
After processing a payment with SafetyPay, it is possible to pay the customer back by submitting a REFUND request.

Requirements
- You cannot refund a payment until the AUTH has been settled (settlestatus is “100”).
- You cannot refund a greater amount than was originally settled.
The REFUND request and response for SafetyPay payments follow the same field specification as outlined in our standard REFUND documentation. Click here for further information.
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.

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

- 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![]() |
![]() |
![]() |
![]() |
![]() |
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 “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
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:
|
![]() |
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 |
![]() |
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. |
![]() |
paysafekyclevel XPath: /billing/payment/paysafe/kyclevel |
Alpha (6) | Specifies the required KYC level for the “my paysafecard” account holder. There are two levels:
|
![]() |
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.
|
![]() |
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. |
![]() |
livestatus XPath: /live |
Numeric (1) |
|
![]() |
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. |
![]() |
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:
|
![]() |
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) |
|
![]() |
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:
- Entering the PIN found on their card (they can enter multiple PINs if needed).
- Signing in to their “my paysafecard” account.
The customer can proceed with the payment by clicking the “Pay” button.

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

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.

3. Processing the authorisation

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

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.
|
![]() |
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. |
![]() |
livestatus XPath: /live |
Numeric (1) |
|
![]() |
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. |
![]() |
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:
|
![]() |
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) |
|
![]() |
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:
- 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 the “URL notifications” section of our Action types page. 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.
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.