Contents

SafetyPay

 

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

 

PAYMENT SAFETYPAY
SafetyPay is a real-time bank transfer / cash payment method. When selecting SafetyPay, customers will be presented with two options. The first allows the customer to pay via online banking, by signing in to their online banking account. After reviewing the pre-filled payment details, they can agree to the payment, before being redirected back to your website. The second option allows the customer to pay the amount in cash at a bank. Once completed, you will receive confirmation via a URL notification.

 

Features

Supported customer countries AT, BE, CL, CO, CR, DE, EC, ES, MX, NL, PE, PR 
Supported currencies
EUR, USD
Protect Plus
Supported.
Refunds Full and partial refunds supported (permitted for up to 90 days).
Chargebacks
Payments are not subject to chargebacks.

 


 

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

1
Initiate the customer

  • 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.
2
Redirect to SafetyPay

  • 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.
3
Payment completion

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

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

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

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

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

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

To amend these fields, please contact our Support Team.

operatorname
XPath: /merchant/operatorname
Alphanumeric (255) The value of this field contains the name of the user that processed the request.
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:

Settle status 10
If the settlestatus is “10”, the payment is pending settlement.

  • 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.
Settle status 3
If the settlestatus is “3”, the payment has been cancelled.

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

Status good
If the customer is redirected to the successfulurlredirect:
The customer successfully completed the required steps on SafetyPay’s pages.
Recommended actions: Display confirmation that the payment was successful.
Status attention
If the customer is redirected to the errorurlredirect:
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.
Info
When testing, you will be displayed the sandbox as provided by SafetyPay. 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. 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.

Info
Please check for any URL redirect rules that may be enabled in the MyST Rule manager on your site reference(s), as these may conflict and take precedence over the successfulurlredirect and errorurlredirect fields submitted in the AUTH request.

 

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

PAYMENT
The settlement process for SafetyPay differs from the standard process followed with card-based payment methods.
Info
The settlement notification may not be sent immediately after processing the AUTH.

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:

 

Configuring the authorisation notification

We recommend including at least the following fields in your authorisation notification:

*Please choose your preferred format.

 

Configuring the settlement notification

We recommend including the following fields in your settlement notification:

 

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:

Info
Cancelled transactions (settlestatus “3”) may be settled at a later time. In situations where the customer has completed the steps required to fulfil the payment, the settlestatus is updated to “100” to indicate the funds have been transferred to your account.

 

If you have contacted the Support Team to configure settlement notifications (as described above), you will be notified when this occurs.

 


 

Testing

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

Info
Requirements

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.

Info
Refunds for SafetyPay are settled immediately (settlestatus “100”).

 

Requirements

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.

PayU

 

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

 

PAYMENT PAYU
PayU is a real-time bank transfer system. When selecting PayU, customers will be prompted to select their bank and then to sign in to their online banking account. After reviewing the pre-filled payment details, they can agree to the payment, before being redirected back to your website. Once completed, you will receive confirmation via a URL notification.

 

Features

Supported customer countries CZ, PL
Supported currencies
CZK, PLN
Protect Plus
Supported.
Refunds Full and partial refunds supported (permitted for up to 365 days).
Chargebacks
Payments are not subject to chargebacks.

 


 

Configuration

To enable PayU 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

1
Initiate the customer

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

  • Merchant redirects the customer’s browser to the redirecturl.
  • Customer follows instructions on PayU’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.
3
Payment completion

  • At a later time, PayU 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 PayU, 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 PayU AUTH request:


#!/usr/bin/python
import securetrading

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

auth = {
    "currencyiso3a": "PLN",
    "requesttypedescription": "AUTH",
    "accounttypedescription": "ECOM",
    "sitereference": "test_site12345",
    "baseamount": "1050",
    "paymenttypedescription": "PAYU",
    "successfulurlredirect": "https://yourwebsite.com",
    "errorurlredirect": "https://yourwebsite.com",
    "billingfirstname": "Joe",
    "billinglastname": "Bloggs",
    "billingcountryiso2a": "PL"
}

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' => 'PLN',
    'requesttypedescription' => 'AUTH',
    'accounttypedescription' => 'ECOM',
    'sitereference' => 'test_site12345',
    'baseamount' => '1050',
    'paymenttypedescription' => 'PAYU',
    'successfulurlredirect' => 'https://yourwebsite.com',
    'errorurlredirect' => 'https://yourwebsite.com',
    'billingfirstname' => 'Joe',
    'billinglastname' => 'Bloggs',
    'billingcountryiso2a' => 'PL'
);

$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": "PLN",
     "requesttypedescription": "AUTH",
     "accounttypedescription": "ECOM",
     "sitereference": "test_site12345",
     "baseamount": "1050",
     "paymenttypedescription": "PAYU",
     "successfulurlredirect": "https://www.example.com/success",
     "errorurlredirect": "https://www.example.com/error",
     "billingfirstname": "Joe",
     "billinglastname": "Bloggs",
     "billingcountryiso2a": "PL"
 }]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"PLN","requesttypedescription":"AUTH","accounttypedescription":"ECOM","sitereference":"test_site12345","baseamount":"1050","paymenttypedescription":"PAYU","successfulurlredirect":"https:\/\/www.example.com\/success","errorurlredirect":"https:\/\/www.example.com\/error","billingfirstname":"Joe","billinglastname":"Bloggs","billingcountryiso2a":"PL"}]}
<?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>CZ</country>
      <amount currencycode="CZK">1050</amount>
      <payment type="PAYU"/>
    </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 PayU, 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 PayU, 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 PayU-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 “PAYU”.
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 PayU.

 

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'PAYU',
    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'PLN'
  }]
}
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) "PAYU"
      ["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) "PLN"
    }
  }
}
{"requestreference":"W23-fjgvn3d9","version":"1.00","response":[{"transactionreference":"23-86-113","merchantname":"Test Merchant","paymenttypedescription":"PAYU","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":"PLN"}]}
<?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="CZK">1050</amount>
      <payment type="PAYU"/>
    </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 PayU.
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 PayU, 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.

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

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

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

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

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

To amend these fields, please contact our Support Team.

operatorname
XPath: /merchant/operatorname
Alphanumeric (255) The value of this field contains the name of the user that processed the request.
paymenttypedescription
XPath: /billing/payment/@type
Alpha (20) This value returned is “PAYU”.
redirecturl
XPath: /other/redirecturl
URL (255) Redirect the customer’s browser to this URL to allow them to complete the payment on PayU’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 PayU payment:

Settle status 10
If the settlestatus is “10”, the payment is pending settlement.

  • 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 PayU’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.
Settle status 3
If the settlestatus is “3”, the payment has been cancelled.

  • 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 PayU

Your system will need to redirect the customer’s browser to the redirecturl, which is a page hosted by PayU, 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.

Status good
If the customer is redirected to the successfulurlredirect:
The customer successfully completed the required steps on PayU’s pages.
Recommended actions: Display confirmation that the payment was successful.
Status attention
If the customer is redirected to the errorurlredirect:
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.
Info
When testing, you will be displayed the sandbox as provided by PayU. 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. Payment completion

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

Info
Please check for any URL redirect rules that may be enabled in the MyST Rule manager on your site reference(s), as these may conflict and take precedence over the successfulurlredirect and errorurlredirect fields submitted in the AUTH request.

 

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

PAYMENT
The settlement process for PayU differs from the standard process followed with card-based payment methods.
Info
The settlement notification may not be sent immediately after processing the AUTH.

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:

 

Configuring the authorisation notification

We recommend including at least the following fields in your authorisation notification:

*Please choose your preferred format.

 

Configuring the settlement notification

We recommend including the following fields in your settlement notification:

 

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:

Info
Cancelled transactions (settlestatus “3”) may be settled at a later time. In situations where the customer has completed the steps required to fulfil the payment, the settlestatus is updated to “100” to indicate the funds have been transferred to your account.

 

If you have contacted the Support Team to configure settlement notifications (as described above), you will be notified when this occurs.

 


 

Testing

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

Info
Requirements

You will need to contact our Support team, providing your PayU test account details. We will then configure your test site reference to connect directly to the PayU testing environment.

When performing test transactions, the redirect URL returned in the AUTH response will redirect your browser to the PayU 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 PayU, it is possible to pay the customer back by submitting a REFUND request.

Info
Refunds for PayU are settled immediately (settlestatus “100”).

 

Requirements

The REFUND request and response for PayU payments follow the same field specification as outlined in our standard REFUND documentation. Click here for further information.

giropay

 

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

 

PAYMENT GIROPAY
giropay is a German online payment method that is supported by over 1,500 German banks. When selecting giropay, customers will be prompted to select their bank and then to sign in to their online banking account. After reviewing the pre-filled payment details, they can agree to the payment, before being redirected back to your website. Once completed, you will receive confirmation via a URL notification.

 

Features

Supported customer countries DE
Supported currencies
EUR
Protect Plus
Supported.
Refunds Full and partial refunds supported (permitted for up to 365 days).
Chargebacks
Payments are not subject to chargebacks.

 


 

Configuration

To enable giropay 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

1
Initiate the customer

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

  • Merchant redirects the customer’s browser to the redirecturl.
  • Customer follows instructions on giropay’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.
3
Payment completion

  • At a later time, giropay 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 giropay, 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 giropay AUTH request:


#!/usr/bin/python
import securetrading

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

auth = {
    "currencyiso3a": "EUR",
    "requesttypedescriptions": ["AUTH"],
    "accounttypedescription": "ECOM",
    "sitereference": "test_site12345",
    "baseamount": "1050",
    "paymenttypedescription": "GIROPAY",
    "successfulurlredirect": "https://yourwebsite.com",
    "errorurlredirect": "https://yourwebsite.com",
    "billingfirstname": "Joe",
    "billinglastname": "Bloggs",
    "billingcountryiso2a": "DE",
    "bic": "12345678"
}

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',
    'requesttypedescriptions' => array('AUTH'),
    'accounttypedescription' => 'ECOM',
    'sitereference' => 'test_site12345',
    'baseamount' => '1050',
    'paymenttypedescription' => 'GIROPAY',
    'successfulurlredirect' => 'https://yourwebsite.com',
    'errorurlredirect' => 'https://yourwebsite.com',
    'billingfirstname' => 'Joe',
    'billinglastname' => 'Bloggs',
    'billingcountryiso2a' => 'DE',
    'bic' => '12345678'
);

$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",
     "requesttypedescriptions": ["AUTH"],
     "accounttypedescription": "ECOM",
     "sitereference": "test_site12345",
     "baseamount": "1050",
     "paymenttypedescription": "GIROPAY",
     "successfulurlredirect": "https://www.example.com/success",
     "errorurlredirect": "https://www.example.com/error",
     "billingfirstname": "Joe",
     "billinglastname": "Bloggs",
     "billingcountryiso2a": "DE",
     "bic": "12345678"
 }]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"EUR","requesttypedescriptions":["AUTH"],"accounttypedescription":"ECOM","sitereference":"test_site12345","baseamount":"1050","paymenttypedescription":"GIROPAY","successfulurlredirect":"https:\/\/www.example.com\/success","errorurlredirect":"https:\/\/www.example.com\/error","billingfirstname":"Joe","billinglastname":"Bloggs","billingcountryiso2a":"DE","bic":"12345678"}]}
<?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>DE</country>
      <bic>12345678</bic>
      <amount currencycode="EUR">1050</amount>
      <payment type="GIROPAY"/>
    </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)
bic
XPath: /billing/payment/bic
Alphanumeric (8 or 11) Valid BIC (Bank Identifier Code) of customer’s bank.
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 giropay, 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 giropay, 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 giropay-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 “GIROPAY”.
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 giropay.

 

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'GIROPAY',
    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) "GIROPAY"
      ["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":"GIROPAY","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="GIROPAY"/>
    </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 giropay.
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 giropay, 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.

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

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

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

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

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

To amend these fields, please contact our Support Team.

operatorname
XPath: /merchant/operatorname
Alphanumeric (255) The value of this field contains the name of the user that processed the request.
paymenttypedescription
XPath: /billing/payment/@type
Alpha (20) This value returned is “GIROPAY”.
redirecturl
XPath: /other/redirecturl
URL (255) Redirect the customer’s browser to this URL to allow them to complete the payment on giropay’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 giropay payment:

Settle status 10
If the settlestatus is “10”, the payment is pending settlement.

  • 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 giropay’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.
Settle status 3
If the settlestatus is “3”, the payment has been cancelled.

  • 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 giropay

Your system will need to redirect the customer’s browser to the redirecturl, which is a page hosted by giropay, 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.

Status good
If the customer is redirected to the successfulurlredirect:
The customer successfully completed the required steps on giropay’s pages.
Recommended actions: Display confirmation that the payment was successful.
Status attention
If the customer is redirected to the errorurlredirect:
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.
Info
When testing, you will be displayed the sandbox as provided by giropay. 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. Payment completion

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

Info
Please check for any URL redirect rules that may be enabled in the MyST Rule manager on your site reference(s), as these may conflict and take precedence over the successfulurlredirect and errorurlredirect fields submitted in the AUTH request.

 

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

PAYMENT
The settlement process for giropay differs from the standard process followed with card-based payment methods.
Info
The settlement notification may not be sent immediately after processing the AUTH.

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:

 

Configuring the authorisation notification

We recommend including at least the following fields in your authorisation notification:

*Please choose your preferred format.

 

Configuring the settlement notification

We recommend including the following fields in your settlement notification:

 

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:

Info
Cancelled transactions (settlestatus “3”) may be settled at a later time. In situations where the customer has completed the steps required to fulfil the payment, the settlestatus is updated to “100” to indicate the funds have been transferred to your account.

 

If you have contacted the Support Team to configure settlement notifications (as described above), you will be notified when this occurs.

 


 

Testing

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

Info
Requirements

You will need to contact our Support team, providing your giropay test account details. We will then configure your test site reference to connect directly to the giropay testing environment.

When performing test transactions, the redirect URL returned in the AUTH response will redirect your browser to the giropay 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 giropay, it is possible to pay the customer back by submitting a REFUND request.

Info
Refunds for giropay are settled immediately (settlestatus “100”).

 

Requirements

The REFUND request and response for giropay payments follow the same field specification as outlined in our standard REFUND documentation. Click here for further information.

Refunds

 

For customers that have completed a payment using DCC, it is possible to process refunds by manually submitting a REFUND request using our Webservices API.

 

Info
Remember!

  • The customer’s currency is the currency associated with their card.
  • The merchant’s currency is the local currency associated with your account.

 

DCC refunds have a similar structure to standard REFUND requests, but are subject to additional requirements that are outlined below. There are four DCC refund options available:

 

Warning
It is your responsibility to ensure that all DCC field values you include in any DCC REFUND requests are correct and agreed with your conversion rate provider.

Your conversion rate provider will specify the required process to handle refunds on your account. We recommend that you review the options available and contact our Support Team for further information.


 

Option 1: Refund using original rate

 

Request

The request has the same structure as a standard REFUND request, except your system will also need to resubmit either the customer currency fields OR the merchant currency fields, as shown below:

 

Either submit the following two customer currency fields in the request:

currencyiso3a The customer’s currency.
baseamount The amount in the customer’s currency.

 

Or, if you prefer to submit the merchant currency fields in the request:

dcccurrencyiso3a The merchant’s currency.
dccbaseamount The amount in the merchant’s currency.

 

Info
As with standard REFUND requests, the submitted parenttransactionreference field must refer to the parent AUTH request being refunded (not the CURRENCYRATE request).

#!/usr/bin/python
import securetrading
  
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
  
refund= {
  "requesttypedescriptions": ["REFUND"],
  "sitereference": "test_site12345",
  "parenttransactionreference": "1-2-345678",
  "currencyiso3a": "USD",
  "baseamount": "1641"
}
  
strequest = securetrading.Request()
strequest.update(refund)
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(
  'requesttypedescriptions' => array('REFUND'),
  'sitereference' => 'test_site12345',
  'parenttransactionreference' => '1-2-345678',
  'currencyiso3a' => 'USD',
  'baseamount' => '1641'
);

$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": [{
  "requesttypedescriptions": ["REFUND"],
  "sitereference": "test_site12345",
  "parenttransactionreference": "1-2-345678",
  "currencyiso3a": "USD",
  "baseamount": "1641"
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["REFUND"],"sitereference":"test_site12345","parenttransactionreference":"1-2-345678","currencyiso3a":"USD","baseamount":"1641"}]}
<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="REFUND">
    <billing>
      <amount currencycode="USD">1641</amount>
    </billing>
    <operation>
      <sitereference>test_site12345</sitereference>
      <parenttransactionreference>1-2-345678</parenttransactionreference>
    </operation>
  </request>
</requestblock>

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

 

Field specification

Field Format Description

Submit one of these amounts

baseamount
XPath: /billing/amount
Numeric (13) The amount to be refunded in the customer’s currency (this includes the fee added as part of the Margin Rate Percentage calculation). This should be in base units with no commas or decimal points, so £10 would be 1000.

Note: When submitting the baseamount, you must also submit the associated currencyiso3a field.

dccbaseamount
XPath: /billing/dcc/amount
Numeric (13) The amount to be refunded in the merchant’s currency. This should be in base units with no commas or decimal points, so £10 would be 1000.

Note: When submitting the dccbaseamount, you must also submit the associated dcccurrencyiso3a field.

Submit one of these currencies

currencyiso3a
XPath: /billing/amount/@currencycode
Alpha (3) The customer’s currency in iso3a format. Click here for a full list of available currencies.

Required if the baseamount is submitted.

dcccurrencyiso3a
XPath: /billing/dcc/amount/@currencycode
Alpha (3) The merchant’s currency in iso3a format. Click here for a full list of available currencies.

Required if the dccbaseamount is submitted.

dccconversionrate
XPath: /billing/dcc/conversionrate
Numeric (255) The conversion rate originally used to calculate the amount in the customer’s currency (returned in the original CURRENCYRATE response).
dccconversionratesource
XPath: /billing/dcc/conversionratesource
Alphanumeric (255) The source of the original conversion rate returned from the DCC provider (returned in the original CURRENCYRATE response).
dccmarginratepercentage
XPath: /billing/dcc/marginratepercentage
Numeric (11) The percentage (4 decimal places) used as part of the CURRENCYRATE request to calculate the currency conversion fee, which is automatically appended to the amount in the customer’s currency, following calculation.
dccprovider
XPath: /billing/dcc/provider
Alphanumeric (255) The name of the third-party DCC provider that has provided the conversion rate used in the payment (returned in the original CURRENCYRATE response).
dccproviderdata
XPath: /billing/dcc/dccproviderdata
Alphanumeric (255) A unique string that contains information on the calculated conversion rate, returned directly from participating conversion rate providers (returned in the original CURRENCYRATE response).
dcctype
XPath: /billing/dcc/dcctype
Alpha (3) If submitted, this must be “DCC”.
parenttransactionreference
XPath: /operation/parenttransactionreference
Alphanumeric
& hyphens (25)
This field must contain the transaction reference of the AUTH request that you would like to refund.
requesttypedescriptions
XPath: /@type
Alpha (20) You must submit “REFUND”.
sitereference
XPath: /operation/sitereference
Alphanumeric
& underscore (50)
Identifies your site on the Trust Payments system.

If you do not know your site reference, please contact our Support Team.

 

Request REFUND
Partial refund

By submitting a baseamount OR dccbaseamount with a lower value than originally authorised, your system can process partial refunds. We will automatically recalculate the amount in the other currency and this will be returned in the response.

 

Response

The response returned will follow a similar structure to a standard REFUND response, with the addition of DCC-specific fields, as described below.

The DCC-specific fields returned will have the same values as in the initial CURRENCYRATE and AUTH requests, reflecting that the same conversion data has been applied.

Info
The dccratio value is calculated using the refund amount in the customer and merchant currencies. Because this value is calculated after the conversion has taken place, and the converted amount is rounded, the dccratio returned in the response may differ slightly from that used in the initial payment.

 

Field specification

Field Format Description
baseamount
XPath: /billing/amount
Numeric (13) The amount refunded in the customer’s currency (this includes the fee added as part of the Margin Rate Percentage calculation). This is in base units with no commas or decimal points, so £10 would be 1000.
dccbaseamount
XPath: /billing/dcc/amount
Numeric (13) The amount refunded in the merchant’s currency. This is in base units with no commas or decimal points, so £10 would be 1000.
currencyiso3a
XPath: /billing/amount/@currencycode
Alpha (3) The customer’s currency in iso3a format. Click here for a full list of available currencies.
dcccurrencyiso3a
XPath: /billing/dcc/amount/@currencycode
Alpha (3) The merchant’s currency in iso3a format. Click here for a full list of available currencies.
dccconversionrate
XPath: /billing/dcc/conversionrate
Numeric (255) The conversion rate originally used to calculate the amount in the customer’s currency.
dccconversionratesource
XPath: /billing/dcc/conversionratesource
Alphanumeric (255) The source of the original conversion rate returned from the DCC provider.
dccenabled
XPath: /billing/dcc/@enabled
Numeric (1) The value returned will be “1”, indicating the account used for processing this payment is enabled for DCC.
dccmarginratepercentage
XPath: /billing/dcc/marginratepercentage
Numeric (11) The percentage (4 decimal places) used as part of the CURRENCYRATE request to calculate the currency conversion fee, which is automatically appended to the amount in the customer’s currency, following calculation.
dccoffered
XPath: /billing/dcc/offered
Numeric (1) This value represents whether the REFUND was processed in the customer’s currency or the merchant’s currency:

1 – The customer was refunded in the customer’s currency.

3 – The customer was refunded in the merchant’s currency.

dccproviderdata
XPath: /billing/dcc/dccproviderdata
Alphanumeric (255) A unique string that contains information on the calculated conversion rate, returned directly from participating conversion rate providers.
dccratio
XPath: /billing/dcc/ratio
Numeric (255) The ratio between both amounts processed in the request in main units.
dcctype
XPath: /billing/dcc/dcctype
Alpha (3) This is returned as “DCC”.
parenttransactionreference
XPath: /operation/parenttransactionreference
Alphanumeric
& hyphens (25)
The transaction reference of the AUTH request refunded.
requesttypedescription
XPath: /@type
Alpha (20) This is returned as “REFUND”.

 


 

Option 2: Refund using new rate

 

Process overview

1
Perform a new CURRENCYRATE request.

Note: When performing a partial refund, you will need to submit a lower dccbaseamount in the request.

2
Perform a REFUND request, ensuring all DCC-specific fields returned in the new CURRENCYRATE response are submitted (see list below).
Info
As with standard REFUND requests, the submitted parenttransactionreference field must refer to the parent AUTH request being refunded (not the CURRENCYRATE request).

 

Request

The following is an example of a request to process a REFUND using a new conversion rate. This presumes you have already performed a new CURRENCYRATE request and are including the new data in the REFUND request (Refer to the field specification below for further information on these fields)


#!/usr/bin/python
import securetrading
  
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
  
refund= {
  "requesttypedescriptions": ["REFUND"],
  "sitereference": "test_site12345",
  "parenttransactionreference": "1-2-345678",
  "currencyiso3a": "USD",
  "baseamount": "1260",
  "dcctype": "DCC",
  "dccconversionrate": "1.2",
  "dccconversionratesource": "Rate Source",
  "dccmarginratepercentage": "2.5000",
  "dcccurrencyiso3a": "GBP",
  "dccbaseamount": "1050",
  "dccprovider": "Test Provider",
 
 "dccproviderdata": "01020304120021250373330603INR0803356200513800210875190000300124306MBB01"
}
  
strequest = securetrading.Request()
strequest.update(refund)
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(
  'requesttypedescriptions' => array('REFUND'),
  'sitereference' => 'test_site12345',
  'parenttransactionreference' => '1-2-345678',
  'currencyiso3a' => 'USD',
  'baseamount' => '1260',
  'dcctype' => 'DCC',
  'dccconversionrate' => '1.2',
  'dccmarginratepercentage' => '2.5000',
  'dcccurrencyiso3a' => 'GBP',
  'dccbaseamount' => '1050'

  'requesttypedescriptions' => array('REFUND'),
  'sitereference' => 'test_site12345',
  'parenttransactionreference' => '1-2-345678',
  'currencyiso3a' => 'USD',
  'baseamount' => '1260',
  'dcctype' => 'DCC',
  'dccconversionrate' => '1.2',
  'dccconversionratesource' => 'Rate Source',
  'dccmarginratepercentage' => '2.5000',
  'dcccurrencyiso3a' => 'GBP',
  'dccbaseamount' => '1050',
  'dccprovider' => 'Test Provider',
 
 'dccproviderdata' => '01020304120021250373330603INR0803356200513800210875190000300124306MBB01'
);

$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": [{
  "requesttypedescriptions": ["REFUND"],
  "sitereference": "test_site12345",
  "parenttransactionreference": "1-2-345678",
  "currencyiso3a": "USD",
  "baseamount": "1260",
  "dcctype": "DCC",
  "dccconversionrate": "1.2",
  "dccconversionratesource": "Rate Source",
  "dccmarginratepercentage": "2.5000",
  "dcccurrencyiso3a": "GBP",
  "dccbaseamount": "1050",
  "dccprovider": "Test Provider",
 
 "dccproviderdata": "01020304120021250373330603INR0803356200513800210875190000300124306MBB01"
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["REFUND"],"sitereference":"test_site12345","parenttransactionreference":"1-2-345678","currencyiso3a":"USD","baseamount":"1260","dcctype":"DCC","dccconversionrate":"1.2","dccconversionratesource":"Rate Source","dccmarginratepercentage":"2.5000","dcccurrencyiso3a":"GBP","dccbaseamount":"1050","dccprovider":"Test Provider","dccproviderdata":"01020304120021250373330603INR0803356200513800210875190000300124306MBB01"}]}
<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="REFUND">
    <billing>
      <amount currencycode="USD">1260</amount>
      <dcc type="DCC">
        <amount currencycode="GBP">1050</amount>
        <conversionrate>1.2</conversionrate>
        <conversionratesource>Rate Source</conversionratesource>
        <provider>Test Provider</provider>
<dccproviderdata>01020304120021250373330603INR0803356200513800210875190000300124306MBB015</dccproviderdata>
        <marginratepercentage>2.5000</marginratepercentage>
      </dcc>
    </billing>
    <operation>
      <sitereference>test_site12345</sitereference>
      <parenttransactionreference>1-2-345678</parenttransactionreference>
    </operation>
  </request>
</requestblock>

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

 

Field specification

Field Format Description
baseamount
XPath: /billing/amount
Numeric (13) The amount to be refunded in the customer’s currency (this includes the fee added as part of the Margin Rate Percentage calculation). This should be in base units with no commas or decimal points, so £10 would be 1000.

dccbaseamount
XPath: /billing/dcc/amount
Numeric (13) The amount to be refunded in the merchant’s currency. This should be in base units with no commas or decimal points, so £10 would be 1000.
currencyiso3a
XPath: /billing/amount/@currencycode
Alpha (3) The customer’s currency in iso3a format. Click here for a full list of available currencies.
dcccurrencyiso3a
XPath: /billing/dcc/amount/@currencycode
Alpha (3) The merchant’s currency in iso3a format. Click here for a full list of available currencies.
dccconversionrate
XPath: /billing/dcc/conversionrate
Numeric (255) The conversion rate used to calculate the new amounts (returned in the new CURRENCYRATE response).
dccconversionratesource
XPath: /billing/dcc/conversionratesource
Alphanumeric (255) The source of the new conversion rate returned from the DCC provider (returned in the new CURRENCYRATE response).
dccmarginratepercentage
XPath: /billing/dcc/marginratepercentage
Numeric (11) The percentage used as part of the new CURRENCYRATE request, to calculate the currency conversion fee (4 decimal places), automatically added to the amount in the customer’s currency by the DCC provider.
dccprovider
XPath: /billing/dcc/provider
Alphanumeric (255) The name of the third-party DCC provider that has provided the conversion rate used in the payment (returned in the new CURRENCYRATE response).
dccproviderdata
XPath: /billing/dcc/dccproviderdata
Alphanumeric (255) A unique string that contains information on the calculated conversion rate, returned directly from participating conversion rate providers (returned in the new CURRENCYRATE response).
dcctype
XPath: /billing/dcc/dcctype
Alpha (3) You must submit “DCC”.
parenttransactionreference
XPath: /operation/parenttransactionreference
Alphanumeric
& hyphens (25)
This field must contain the transaction reference of the AUTH request that you would like to refund.
requesttypedescriptions
XPath: /@type
Alpha (20) You must submit “REFUND”.
sitereference
XPath: /operation/sitereference
Alphanumeric
& underscore (50)
Identifies your site on the Trust Payments system.

If you do not know your site reference, please contact our Support Team.

 

Response

The response returned will follow a similar structure to a standard REFUND response, with the addition of DCC-specific fields, as described below.

The DCC-specific fields returned will have the same values as in the new CURRENCYRATE request, reflecting that the new conversion data has been applied.

Field specification

Field Format Description
baseamount
XPath: /billing/amount
Numeric (13) The amount refunded in the customer’s currency (this includes the fee added as part of the Margin Rate Percentage calculation). This is in base units with no commas or decimal points, so £10 would be 1000.
dccbaseamount
XPath: /billing/dcc/amount
Numeric (13) The amount refunded in the merchant’s currency. This is in base units with no commas or decimal points, so £10 would be 1000.
currencyiso3a
XPath: /billing/amount/@currencycode
Alpha (3) The customer’s currency in iso3a format. Click here for a full list of available currencies.
dcccurrencyiso3a
XPath: /billing/dcc/amount/@currencycode
Alpha (3) The merchant’s currency in iso3a format. Click here for a full list of available currencies.
dccconversionrate
XPath: /billing/dcc/conversionrate
Numeric (255) The conversion rate used to calculate the new amounts (returned in the new CURRENCYRATE response).
dccconversionratesource
XPath: /billing/dcc/conversionratesource
Alphanumeric (255) The source of the new conversion rate returned from the DCC provider (returned in the new CURRENCYRATE response).
dccenabled
XPath: /billing/dcc/@enabled
Numeric (1) The value returned will be “1”, indicating the account used for processing this payment is enabled for DCC.
dccmarginratepercentage
XPath: /billing/dcc/marginratepercentage
Numeric (11) The percentage used as part of the new CURRENCYRATE request, to calculate the currency conversion fee (4 decimal places), automatically added to the amount in the customer’s currency by the DCC provider.
dccoffered
XPath: /billing/dcc/offered
Numeric (1) This value represents whether the REFUND was processed in the customer’s currency or the merchant’s currency:

1 – The customer was refunded in the customer’s currency.

3 – The customer was refunded in the merchant’s currency.

dccprovider
XPath: /billing/dcc/provider
Alphanumeric (255) The name of the third-party DCC provider that has provided the conversion rate used in the payment.
dccproviderdata
XPath: /billing/dcc/dccproviderdata
Alphanumeric (255) A unique string that contains information on the calculated conversion rate, returned directly from participating conversion rate providers.
dccratio
XPath: /billing/dcc/ratio
Numeric (255) The ratio between both amounts processed in the request in main units.
dcctype
XPath: /billing/dcc/dcctype
Alpha (3) This is returned as “DCC”.
parenttransactionreference
XPath: /operation/parenttransactionreference
Alphanumeric
& hyphens (25)
The transaction reference of the AUTH request refunded.
requesttypedescription
XPath: /@type
Alpha (20) This is returned as “REFUND”.

 


 

Option 3: Refund using custom rule

 

Process overview

Your conversion rate provider may require you to use a new conversion rate when performing a DCC refund after a pre-specified number of days have passed since the parent AUTH was processed (we’ll refer to this as x days). To address this, our Support team can configure your account to behave in the following way:

To have this configured for your account or to find out further information, please contact our Support Team.

 

Request

The request has the same structure as a standard REFUND request, except your system will also need to resubmit either the customer currency fields OR the merchant currency fields, as shown below:

 

Either submit the following two customer currency fields in the request:

currencyiso3a The customer’s currency.
baseamount The amount in the customer’s currency.

 

Or, if you prefer to submit the merchant currency fields in the request:

dcccurrencyiso3a The merchant’s currency.
dccbaseamount The amount in the merchant’s currency.

 

Info
As with standard REFUND requests, the submitted parenttransactionreference field must refer to the parent AUTH request being refunded (not the CURRENCYRATE request).
Info
This implementation supports both partial refunds and full refunds. Simply submit a lower baseamount OR dccbaseamount and we will calculate the value in the other currency.

 


#!/usr/bin/python
import securetrading
  
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
  
refund= {
  "requesttypedescriptions": ["REFUND"],
  "sitereference": "test_site12345",
  "parenttransactionreference": "1-2-345678",
  "currencyiso3a": "USD",
  "baseamount": "1641"
}
  
strequest = securetrading.Request()
strequest.update(refund)
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(
  'requesttypedescriptions' => array('REFUND'),
  'sitereference' => 'test_site12345',
  'parenttransactionreference' => '1-2-345678',
  'currencyiso3a' => 'USD',
  'baseamount' => '1641'
);

$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": [{
  "requesttypedescriptions": ["REFUND"],
  "sitereference": "test_site12345",
  "parenttransactionreference": "1-2-345678",
  "currencyiso3a": "USD",
  "baseamount": "1641"
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["REFUND"],"sitereference":"test_site12345","parenttransactionreference":"1-2-345678","currencyiso3a":"USD","baseamount":"1641"}]}
<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="REFUND">
    <billing>
      <amount currencycode="USD">1641</amount>
    </billing>
    <operation>
      <sitereference>test_site12345</sitereference>
      <parenttransactionreference>1-2-345678</parenttransactionreference>
    </operation>
  </request>
</requestblock>

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

 


Option 4: Refund using MyST

 

It is also possible to refund DCC payments by using MyST. If the payment was processed using the customer’s currency (shown within MyST as dccoffered = 1), we automatically perform a new CURRENCYRATE request in order to refund the customer using an up-to-date conversion rate. MyST also supports the ability to process partial refunds.

User
The ability to refund transactions using MyST is limited to users with certain user roles (Click here for information on different user roles).

 

paysafecard

 

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

 

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

 

PAYMENT PAYSAFECARD
What is paysafecard?

 

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

 

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

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

 

Features

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

 


 

Configuration

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

 


 

Process overview

What will the customer see?

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

 

 

How does it work behind the scenes?

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

1

Initiate the customer

2

Redirect to paysafecard

3

Processing the authorisation

 


 

1. Initiate the customer

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

 

ORDER request example


#!/usr/bin/python
import securetrading

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

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

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

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

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

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

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

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

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

 

Field specification

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

 You must always submit a billingid:

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

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

Click here for further information on currency codes.

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

e.g. “GB” for United Kingdom.

Click here for a full list of country codes.

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

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

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

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

 

ORDER response example


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

 

Field specification

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

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

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

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

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

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

e.g. “GB” for United Kingdom.

Click here for a full list of country codes.

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

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

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

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

 


 

2. Redirect to paysafecard

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

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

The customer will be offered the choice between either:

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

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

 

If successful authentication

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

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

 

If customer cancels

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

 

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

 


 

3. Processing the authorisation

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

 

AUTH request example

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


#!/usr/bin/python
import securetrading

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

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

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

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

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

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

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

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

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

 

Field specification

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

 

AUTH response example

Here is an example of an AUTH response for paysafecard.


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

 

Field specification

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

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

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

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

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

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

To amend these fields, please contact our Support Team.

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

e.g. “GB” for United Kingdom.

Click here for a full list of country codes.

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

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

 


 

Notifications

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

 

Configuring the notification

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

*Please choose your preferred format.

 

Check the notification

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

 


 

Settlement

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

 


 

Additional notes

Fraud-prevention

Fraud and duplicate checks

Fraud and duplicate checks are not performed on paysafecard transactions.

 

Address Verification Service (AVS) checks

AVS checks cannot be performed on paysafecard transactions.

 

Protect Plus

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

 

Frozen cards

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

 

If the customer fails to enter their PIN

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

 

Currencies

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

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

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

 

Account type

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

 

iframes

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

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

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

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

Payouts

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

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

 

Payouts are similar to standard refunds, except they can be performed independently of other transactions. The benefits of performing payouts include:

Info
Payouts are also known as Credit Fund Transfers (CFT) or Original Credit Transfers (OCT).
Info
Payouts processed with Visa Direct are processed online, with the customer’s account typically being credited within 30 minutes.

 

Please contact your account manager to check if you are eligible to enable Visa Direct on your account.

 

Requirements

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

 

Payout request

Using parent transaction

The following is an example of such a request:

Warning
Ensure the submitted accounttypedescription is “CFT”, otherwise a regular REFUND will be processed instead of a payout.

#!/usr/bin/python
import securetrading
  
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
  
payout= {
  "requesttypedescriptions": ["REFUND"],
  "sitereference": "test_site12345",
  "accounttypedescription": "CFT",
  "parenttransactionreference": "1-2-345678"
}
  
strequest = securetrading.Request()
strequest.update(payout)
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(
'requesttypedescriptions' => array('REFUND'),
'sitereference' => 'test_site12345',
'accounttypedescription' => 'CFT',
'parenttransactionreference' => '1-2-345678'
);

$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": [{
  "requesttypedescriptions": ["REFUND"],
  "sitereference": "test_site12345",
  "accounttypedescription": "CFT",
  "parenttransactionreference": "1-2-345678"
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["REFUND"],"sitereference":"test_site12345","accounttypedescription":"CFT","parenttransactionreference":"1-2-345678"}]}
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="REFUND">
    <operation>
      <sitereference>test_site12345</sitereference>
      <accounttypedescription>CFT</accounttypedescription>
      <parenttransactionreference>1-2-345678</parenttransactionreference>
    </operation>
  </request>
</requestblock>

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

 

Without parent

As an alternative to the above, you can also submit a payout request without reference to a parent transaction. In this scenario, you will instead need to submit the customer’s payment details in the payout request. Please see the following example:


#!/usr/bin/python
import securetrading
  
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
  
payout= {
        "requesttypedescriptions": ["REFUND"],
        "sitereference": "test_site12345",
        "accounttypedescription": "CFT",
        "baseamount": "1050",
        "currencyiso3a": "GBP",
        "pan": "4111111111111111",
        "expirydate": "12/2020",
        "securitycode": "123"
}
  
strequest = securetrading.Request()
strequest.update(payout)
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(
'requesttypedescriptions' => array('REFUND'),
'sitereference' => 'test_site12345',
'accounttypedescription' => 'CFT',
'baseamount' => '1050',
'currencyiso3a' => 'GBP',
'pan' => '4111111111111111',
'expirydate' => '12/2020',
'securitycode' => '123'
);

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

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

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

 

Field specification

Info
When reading the following specification, please ensure that you reference the relevant code examples for your chosen language.

 

Field Format Description
accounttypedescription
XPath: /operation/accounttypedescription
Alpha (20) Must be “CFT”.
baseamount
XPath: /billing/amount
Numeric (13) The refund amount in base units, with no commas or decimal points. e.g. £10.99 would be submitted as “1099” but ¥246 would be submitted as “246”.

(Max length of amount may vary depending on your acquiring bank – Contact your bank for further info)

currencyiso3a
XPath: /billing/amount/@currencycode
Alpha (3) The currency that the transaction will be processed in.

Click here for a full list of available currencies.

expirydate
XPath: /billing/payment/expirydate
Date MM/YYYY If you would like to process a refund with an updated expiry date, the new value is submitted in this field.
orderreference
XPath: /merchant/orderreference
Alphanumeric including
symbols (255)
Your unique order reference that can be stored on Trust Payments’s system.

If this is not submitted, it is inherited from the parent AUTH request, provided a parenttransactionreference has been included.

pan
XPath: /billing/payment/pan
Numeric (12-19) This is the long number printed on the front of the customer’s card.

We return a masked version of this PAN in the response, in the field maskedpan. e.g. “411111######1111”

parenttransactionreference
XPath: /operation/parenttransactionreference
Alphanumeric
& hyphens (25)
You can submit the transaction reference of the AUTH request that you would like to refund.
requesttypedescriptions
XPath: /@type
Alphanumeric
& hyphens (25)
The request type required is “REFUND”.
securitycode
XPath: /security/securitycode
Numeric (3-4) This is the three digit security code printed on the back of the card.

(For AMEX cards, this is a 4 digit code found on the front of the card)

We strongly recommend submitting this value for the processing of security code checks.

Additionally, some banks may decline the payment if the security code is not present.

sitereference
XPath: /operation/sitereference
Alphanumeric
& underscore (50)
A unique reference that identifies your account. You receive this when you first sign up with us.

 

Payout response

The response returned has the same structure as a standard REFUND, except that the accounttypedescription returned is “CFT”:


{
  u 'requestreference': u 'Agv3epv31',
    u 'version': u '1.00',
    u 'response': [{
      u 'transactionstartedtimestamp': u '2016-12-07 15:44:33',
        u 'parenttransactionreference': u '1-2-345678',
        u 'livestatus': u '0',
        u 'issuer': u 'SecureTrading Test Issuer1',
        u 'dccenabled': u '0',
        u 'settleduedate': u '2016-12-07',
        u 'errorcode': u '0',
        u 'orderreference': u 'My_Order_123',
        u 'tid': u '27880001',
        u 'merchantnumber': u '00000000',
        u 'merchantcountryiso2a': u 'GB',
        u 'transactionreference': u '1-2-345679',
        u 'merchantname': u 'Test Merchant',
        u 'paymenttypedescription': u 'VISA',
        u 'baseamount': u '1050',
        u 'accounttypedescription': u 'CFT',
        u 'acquirerresponsecode': u '00',
        u 'requesttypedescription': u 'REFUND',
        u 'securityresponsesecuritycode': u '0',
        u 'currencyiso3a': u 'GBP',
        u 'authcode': u 'TEST REFUND ACCEPTED',
        u 'errormessage': u 'Ok',
        u 'operatorname': u '[email protected]',
        u 'securityresponsepostcode': u '0',
        u 'maskedpan': u '411111######1111',
        u 'securityresponseaddress': u '0',
        u 'issuercountryiso2a': u 'US',
        u 'settlestatus': u '0'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A19beknpr"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0] => array(28) {
      ["transactionstartedtimestamp"] => string(19) "2016-12-09 10:21:13"
      ["parenttransactionreference"] => string(10) "1-2-345678"
      ["livestatus"] => string(1) "0"
      ["issuer"] => string(26) "SecureTrading Test Issuer1"
      ["dccenabled"] => string(1) "0"
      ["settleduedate"] => string(10) "2016-12-09"
      ["errorcode"] => string(1) "0"
      ["orderreference"] => string(12) "My_Order_123"
      ["tid"] => string(8) "27880001"
      ["merchantnumber"] => string(8) "00000000"
      ["securityresponsepostcode"] => string(1) "0"
      ["transactionreference"] => string(10) "1-2-345679"
      ["merchantname"] => string(13) "Test Merchant"
      ["paymenttypedescription"] => string(4) "VISA"
      ["baseamount"] => string(4) "1050"
      ["accounttypedescription"] => string(3) "CFT"
      ["acquirerresponsecode"] => string(2) "00"
      ["requesttypedescription"] => string(6) "REFUND"
      ["securityresponsesecuritycode"] => string(1) "0"
      ["currencyiso3a"] => string(3) "GBP"
      ["authcode"] => string(20) "TEST REFUND ACCEPTED"
      ["errormessage"] => string(2) "Ok"
      ["operatorname"] => string(23) "[email protected]"
      ["merchantcountryiso2a"] => string(2) "GB"
      ["maskedpan"] => string(16) "411111######1111"
      ["securityresponseaddress"] => string(1) "0"
      ["issuercountryiso2a"] => string(2) "US"
      ["settlestatus"] => string(1) "0"
    }
  }
}
{"requestreference":"W23-qc7t4h8a","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 15:50:37","parenttransactionreference":"1-2-345678","livestatus":"0","issuer":"SecureTrading Test Issuer1","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","baseamount":"1050","tid":"27880001","merchantnumber":"00000000","merchantcountryiso2a":"GB","transactionreference":"1-2-345679","merchantname":"Test Merchant","paymenttypedescription":"VISA","orderreference":"My_Order_123","accounttypedescription":"CFT","acquirerresponsecode":"00","requesttypedescription":"REFUND","securityresponsesecuritycode":"0","currencyiso3a":"GBP","authcode":"TEST REFUND ACCEPTED","errormessage":"Ok","operatorname":"[email protected]","securityresponsepostcode":"0","maskedpan":"411111######1111","securityresponseaddress":"0","issuercountryiso2a":"US","settlestatus":"0"}],"secrand":"0V2j6j0kl2R1UU"}
<?xml version='1.0' encoding='utf-8'?>
<responseblock version="3.67">
  <requestreference>X1u3u92dg</requestreference>
  <response type="REFUND">
    <merchant>
      <tid>27880001</tid>
      <merchantnumber>00000000</merchantnumber>
      <merchantcountryiso2a>GB</merchantcountryiso2a>
      <merchantname>Test Merchant</merchantname>
      <orderreference>My_Order_123</orderreference>
      <operatorname>[email protected]</operatorname>
    </merchant>
    <transactionreference>1-2-345679</transactionreference>
    <billing>
      <amount currencycode="GBP">1050</amount>
      <payment type="VISA">
        <pan>411111######1111</pan>
        <issuercountry>US</issuercountry>
        <issuer>SecureTrading Test Issuer1</issuer>
      </payment>
      <dcc enabled="0"/>
    </billing>
    <timestamp>2019-12-17 11:16:05</timestamp>
    <error>
      <message>Ok</message>
      <code>0</code>
    </error>
    <acquirerresponsecode>00</acquirerresponsecode>
    <live>0</live>
    <authcode>TEST REFUND ACCEPTED</authcode>
    <operation>
      <parenttransactionreference>1-2-345678</parenttransactionreference>
      <accounttypedescription>CFT</accounttypedescription>
    </operation>
    <settlement>
      <settleduedate>2019-12-17</settleduedate>
      <settlestatus>0</settlestatus>
    </settlement>
    <security>
      <address>0</address>
      <postcode>0</postcode>
      <securitycode>0</securitycode>
    </security>
  </response>
  <secrand>V1utOQ5A</secrand>
</responseblock>

 

investors in people logo   pci - security standards council logo

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