apms – Documentation

Alipay In-App Payments

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

Alipay is a Chinese e-wallet that belongs to AntFinancial, an affiliate of the Alibaba group, the largest e-commerce company in the world. When selecting Alipay, customers will be redirected to their hosted pages, enter their personal details and agree to the payment, before being redirected back to your app. Once completed, you will receive confirmation via a URL notification.

Features

Supported customer countries	AUD, CAD, CHF, DKK, EUR, GBP, HKD, JPY, KRW, NOK, NZD, SEK, SGD, THB, USD
Supported currencies	EUR, GBP, USD
Protect Plus	Supported.
Refunds	Full and partial refunds supported.
Chargebacks	Payments are not subject to chargebacks.

Configuration

To enable Alipay 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.

Before you can begin processing In-App Payments, you will need to contact Alipay and request your account is enabled for In-App Payments.

Click here to learn more about In-App Payments >>>

Process overview

Initiate the customer

Redirect to Alipay

Payment completion

Settlement

1. Initiate the customer

When the customer chooses to pay with Alipay, 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 (In-App Payments)

The example request below is for an Alipay AUTH request using the In-App Payments interface:

Python
PHP
cURL
Raw JSON
Raw XML

#!/usr/bin/python
import securetrading

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

auth = {
    "currencyiso3a": "EUR",
    "paymenttypedescription": "ALIPAY",
    "billinglastname": "Bloggs",
    "requesttypedescriptions": ["AUTH"],
    "sitereference": "test_site12345",
    "accounttypedescription": "ECOM",
    "billingcountryiso2a": "DE",
    "baseamount": "1050",
    "billingfirstname": "Joe",
    "orderreference": "My_Order_123",
    "applicationtype": "APP",
    "applicationsystem": "ios"
}

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' => 'ALIPAY',
    'billingfirstname' => 'Joe',
    'billinglastname' => 'Bloggs',
    'billingcountryiso2a' => 'DE',
    'orderreference' => 'My_Order_123',
    'applicationtype' => 'APP',
    'applicationsystem' => 'ios',
);

$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": "ALIPAY",
    "billingfirstname": "Joe",
    "billinglastname": "Bloggs",
    "billingcountryiso2a": "DE",
    "orderreference": "My_Order_123",
    "applicationtype": "APP",
    "applicationsystem": "ios"
}]}'

{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"EUR","requesttypedescriptions":["AUTH"],"accounttypedescription":"ECOM","sitereference":"test_site12345","baseamount":"1050","paymenttypedescription":"ALIPAY","billingfirstname":"Joe","billinglastname":"Bloggs","billingcountryiso2a":"DE","orderreference":"My_Order_123","applicationtype":"APP","applicationsystem":"ios"}]}

<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="AUTH">
    <merchant>
      <orderreference>MyOrder123</orderreference>
    </merchant>
    <billing>
      <name>
        <first>Joe</first>
        <last>Bloggs</last>
      </name>
      <amount currencycode="EUR">1050</amount>
      <payment type="ALIPAY"/>
    </billing>
    <operation>
      <sitereference>test_site12345</sitereference>
      <accounttypedescription>ECOM</accounttypedescription>
      <applicationtype>APP</applicationtype>
      <applicationsystem>ios</applicationsystem>
    </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.
applicationsystem XPath: /operation/applicationsystem	Alpha (7)	Required if applicationtype is “APP”. Defines the platform on which the app is being run. Supported values are “android” and “ios”.
applicationtype XPath: /operation/applicationtype	Alpha (3)	Determines the payment interface displayed to the customer after they have been redirected to the checkout hosted by Alipay: If “APP” is submitted – The transaction is processed using the Alipay In-App Payments interface, which is primarily designed for use from within mobile apps. Note: Before processing transactions using In-App Payments (both through the sandbox environment and with live payments), you will need to contact Alipay and request for the functionality to be enabled on your Alipay account.
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).
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 Alipay, refer to the list found at the top of this page.
orderreference XPath: /merchant/orderreference	Alphanumeric including symbols (255)	Your unique order reference that can be stored on Trust Payments and Alipay’s systems.
paymenttypedescription XPath: /billing/payment/@type	Alpha (20)	This value must be submitted as “ALIPAY”.
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.

{
  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'ALIPAY',
    u'orderreference': u'My_Order_123',
    u'settleduedate': u'2017-03-16',
    u'baseamount': u'1050',
    u'transactionstartedtimestamp': u'2020-03-16 16:25:08',
    u'errormessage': u'Ok',
    u'settlestatus': u'10',
    u'accounttypedescription': u'ECOM',
    u'errorcode': u'0',
    u'requesttypedescription': u'AUTH',
    u'operatorname': u'[email protected]',
    u'livestatus': u'0',
    u'currencyiso3a': u'EUR',
    u'partner id': u'2088611221573217'
  }]
}

array(3) {
  ["requestreference"] => string(9) "A0345jmuw"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0]=> array(17) {
      ["transactionreference"] => string(9) "23-86-113"
      ["merchantname"] => string(4) "Test Merchant"
      ["paymenttypedescription"] => string(6) "ALIPAY"
      ["orderreference"] => string(12) "My_Order_123"
      ["transactionstartedtimestamp"] => string(19) "2020-03-16 16:25:08"
      ["errormessage"] => string(2) "Ok"
      ["accounttypedescription"] => string(4) "ECOM"
      ["errorcode"] => string(1) "0"
      ["settleduedate"] => string(10) "2017-03-16"
      ["currencyiso3a"] => string(3) "EUR"
      ["baseamount"] => string(4) "1050"
      ["requesttypedescription"] => string(4) "AUTH"
      ["operatorname"] => string(11) "[email protected]"
      ["livestatus"] => string(1) "0"
      ["settlestatus"] => string(2) "10"
      ["partner id"] => string(16) "2088611221573217"
    }
  }
}

{"requestreference":"W23-fjgvn3d8","version":"1.00","response":[{"transactionreference":"23-86-113","merchantname":"Test Merchant","paymenttypedescription":"ALIPAY","orderreference":"My_Order_123","settleduedate":"2017-03-16","baseamount":"1050","transactionstartedtimestamp":"2020-03-16 16:25:08","errormessage":"Ok","settlestatus":"10","accounttypedescription":"ECOM","errorcode":"0","requesttypedescription":"AUTH","operatorname":"[email protected]","livestatus":"0","currencyiso3a":"EUR","partner id":"2088611221573217"}],"secrand":"zO9"}

<?xml version='1.0' encoding='utf-8'?>
<responseblock version="3.67">
  <requestreference>Xd4nk260v</requestreference>
  <response type="AUTH">
    <merchant>
      <merchantname>Test Merchant</merchantname>
      <orderreference>MyOrder123</orderreference>
      <operatorname>[email protected]</operatorname>
      <partnerid>2088101122136241</partnerid>
    </merchant>
    <transactionreference>44-86-102</transactionreference>
    <timestamp>2020-03-16 17:34:16</timestamp>
    <operation>
      <accounttypedescription>ECOM</accounttypedescription>
    </operation>
    <settlement>
      <settleduedate>2017-03-16</settleduedate>
      <settlestatus>10</settlestatus>
    </settlement>
    <billing>
      <amount currencycode="EUR">1050</amount>
      <payment type="ALIPAY"/>
    </billing>
    <live>0</live>
    <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”.
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).
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.
orderreference XPath: /merchant/orderreference	Alphanumeric including symbols (255)	The unique order reference stored on Trust Payments and Alipay’s system.
partnerid XPath: /merchant/partnerid	Numeric (16)	A unique identifier for Alipay partners.
paymenttypedescription XPath: /billing/payment/@type	Alpha (20)	This value returned is “ALIPAY”.
requesttypedescription XPath: /@type	Alpha (20)	The value returned is “AUTH”.
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.
signeddata XPath: /other/signeddata		Returned from Alipay. Must be submitted using the SDK when customer is being redirected to the Alipay app.

Handling the response

When handling the AUTH response for Alipay payments, the recommendations outlined in our Best practices still need to be followed, with exception to the handling of the settlestatus field, which is subject to different conditions that are detailed below:

The settlestatus returned in the AUTH response is used to determine the status of the Alipay payment:

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 device to the Alipay app using their SDK to continue with the payment.

Funds will not be settled into your account until the customer is redirected to Alipay’s app, 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.

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 rare cases, the settlestatus can be updated from “3” to “100” (indicating payment has successfully settled). If this occurs, you will receive another URL notification to inform you. e.g. This can be due to the customer contacting Alipay directly to resolve an issue on their account that was preventing the payment from being processed successfully.

2. Redirect to Alipay app

After checking the AUTH response, if the request was successful, you will need to redirect the customer’s device to the Alipay app using their SDK, including the signeddata returned in the AUTH response.

For further information on how to parse the signed data and submit this using the SDK, please refer to Alipay’s technical documentation.

Once on the app, the customer will be prompted to enter additional information in order to complete the payment. At a later time, providing the customer has successfully completed the required steps on the Alipay app, the customer’s device will be redirected back to your app.

When testing, you will be displayed the sandbox as provided by Alipay. 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. Verify Auth Response

To verify that the payment was processed successfully while the customer was using the Alipay app, you will need to submit a VERIFYAUTHRESPONSE request to Trust Payments:

VERIFYAUTHRESPONSE request

Python
PHP
cURL
Raw JSON
Raw XML

#!/usr/bin/python
import securetrading

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

verifyAuthResponse = {
    "requesttypedescriptions": ["VERIFYAUTHRESPONSE"],
    "parenttransactionreference": "44-86-102",
    "sitereference": "test_site12345",
    "verifystring": "ALIPAY SYNC RESPONSE STRING"
}

strequest = securetrading.Request()
strequest.update(verifyAuthResponse)
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('VERIFYAUTHRESPONSE'),
    'parenttransactionreference' => '44-86-102',
    'sitereference' => 'test_site12345',
    'verifystring' => 'ALIPAY SYNC RESPONSE STRING'
);

$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": ["VERIFYAUTHRESPONSE"],
    "parenttransactionreference": "44-86-102",
    "sitereference": "test_site12345",
    "verifystring": "ALIPAY SYNC RESPONSE STRING"
}]}'

{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["VERIFYAUTHRESPONSE"],"parenttransactionreference":"44-86-102","sitereference":"test_site12345","verifystring":"ALIPAY SYNC RESPONSE STRING"}]}

<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="VERIFYAUTHRESPONSE">
    <operation>
       <parenttransactionreference>44-86-102</parenttransactionreference>
       <sitereference>test_site12345</sitereference>
       <verifystring>ALIPAY SYNC RESPONSE STRING</verifystring>
    </operation>
  </request>
</requestblock>

Field specification

Field	Format	Description
parenttransactionreference XPath: /operation/parenttransactionreference	Alphanumeric & hyphens (25)	The transactionreference returned in the AUTH response.
requesttypedescriptions XPath: /@type	Alpha (20)	You must submit “VERIFYAUTHRESPONSE”, as shown in the request example.
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.
verifystring XPath: /operation/verifystring		Returned when customer is redirected back from the Alipay app.

VERIFYAUTHRESPONSE response

The information returned in the VERIFYAUTHRESPONSE response should be used to determine the message displayed to the customer following their payment attempt.

Python
PHP
Raw JSON
Raw XML

{
  u'requestreference': u'An3ug1kap',
  u'version': u'1.00',
  u'response': [{
    u'transactionstartedtimestamp': u'2020-03-16 16:25:08',
    u'errormessage': u'Ok',
    u'errorcode': u'0',
    u'requesttypedescription': u'VERIFYAUTHRESPONSE',
  }]
}

array(3) {
  ["requestreference"] => string(9) "A0345jmuw"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0]=> array(4) {
      ["transactionstartedtimestamp"] => string(19) "2020-03-16 16:25:08"
      ["errormessage"] => string(2) "Ok"
      ["errorcode"] => string(1) "0"
      ["requesttypedescription"] => string(18) "VERIFYAUTHRESPONSE"
    }
  }
}

{"requestreference":"W23-fjgvn3d8","version":"1.00","response":[{"transactionstartedtimestamp":"2020-03-16 16:25:08","errormessage":"Ok","errorcode":"0","requesttypedescription":"VERIFYAUTHRESPONSE"}],"secrand":"zO9"}

<?xml version='1.0' encoding='utf-8'?>
<responseblock version="3.67">
  <requestreference>Xd4nk260v</requestreference>
  <response type="VERIFYAUTHRESPONSE">
    <timestamp>2020-03-16 17:34:16</timestamp>
    <error>
      <message>Ok</message>
      <code>0</code>
    </error>
  </response>
  <secrand>Z1W</secrand>
</responseblock>

Field specification

Field	Format	Description
errorcode XPath: /error/code	Numeric (1-5)	The error code should be used to determine if the request was successful or not. If the error code is “0” then the transaction was successful. If the error code is not “0” then the transaction was not successful. Click here for a full list of errorcode and message values.
errormessage XPath: /error/message	Alphanumeric (255)	This is the corresponding message to the above code. Click here for a full list of errorcode and message values.
requesttypedescription XPath: /@type	Alpha (20)	The value returned is “VERIFYAUTHRESPONSE”.
transactionstartedtimestamp XPath: /timestamp	Date time YYYY-MM-DD hh:mm:ss	The time the request was processed.

4. Payment completion

After receiving the VERIFYAUTHRESPONSE response, you will need to use the data returned in order to display the appropriate response message stating the outcome of the payment (e.g. success / error).

If configured, our system will submit a URL notification to inform you of the authorisation outcome. Following authorisation, funds will be settled at a later time, as determined by Alipay.

The settlement process for Alipay differs from the standard process followed with card-based payment methods.

The notification may not be sent immediately after processing the AUTH. For this reason, you should display a success or error message to the customer immediately after they return from Alipay’s hosted pages, and not wait for this notification.

In the unlikely event that payment is still pending settlement after 7 days (settlestatus “10”), this will be scheduled for investigation and we will contact you with further information.

Before you begin testing, we recommend that you contact our Support team and request that rules are enabled on your account, which submit URL notifications to your system in the following scenarios:

When a payment is authorised.
When funds have been settled into your account.

Configuring the authorisation notification

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

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

*Please choose your preferred format.

Configuring the settlement notification

We recommend including the following fields in URL notifications sent on settlement:

Settle Status (settlestatus)
Site Reference (sitereference)
Transaction Reference (transactionreference)

Check the notification

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

On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).
On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled into your account. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

Refunds

After processing a payment with Alipay, it is possible to pay the customer back by submitting a REFUND request.

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

Requirements

You cannot refund a payment until the AUTH has been settled (settlestatus is “100”).
You cannot refund a greater amount than was originally settled.

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

WeChat Pay

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

With over a billion users, WeChat is the most popular instant messaging app in China. Users who have provided bank account information may use the app to pay bills, order goods and services, transfer money to other users, and pay in participating stores. When the customer selects WeChat Pay to process a payment on your checkout, the WeChat app will open on the customer’s device. The customer checks the recipient of the funds and the amount displayed, then selects to pay either with a bank card, or using their WeChat balance. The customer enters their password to complete the payment. A confirmation is displayed following a successful transaction, before the customer’s device is redirected back to your website. Once completed, you will receive confirmation via a URL notification.

Features

Supported customer countries	CN
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 WeChat Pay 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

Initiate the customer

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

Redirect to WeChat Pay

Merchant redirects the customer’s browser to the redirecturl.
Customer follows instructions on WeChat Pay’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.

Payment completion

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

Python
PHP
cURL
Raw JSON
Raw XML

#!/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": "WECHATPAY",
    "successfulurlredirect": "https://yourwebsite.com",
    "errorurlredirect": "https://yourwebsite.com",
    "billingfirstname": "\u4F1F",
    "billinglastname": "\u5F20",
    "billingcountryiso2a": "CN"
}

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' => 'WECHATPAY',
    'successfulurlredirect' => 'https://yourwebsite.com',
    'errorurlredirect' => 'https://yourwebsite.com',
    'billingfirstname' => '\u4F1F',
    'billinglastname' => '\u5F20',
    'billingcountryiso2a' => 'CN'
);

$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": "WECHATPAY",
    "successfulurlredirect": "https://www.example.com/success",
    "errorurlredirect": "https://www.example.com/error",
    "billingfirstname": "\u4F1F",
    "billinglastname": "\u5F20",
    "billingcountryiso2a": "CN"
}]}'

{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"EUR","requesttypedescription":"AUTH","accounttypedescription":"ECOM","sitereference":"test_site12345","baseamount":"1050","paymenttypedescription":"WECHATPAY","successfulurlredirect":"https:\/\/www.example.com\/success","errorurlredirect":"https:\/\/www.example.com\/error","billingfirstname":"\u4f1f","billinglastname":"\u5f20","billingcountryiso2a":"CN"}]}

<?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>Wei</first>
        <last>Zhang</last>
      </name>
      <country>CN</country>
      <amount currencycode="EUR">1050</amount>
      <payment type="WECHATPAY"/>
    </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 WeChat Pay, 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 WeChat Pay, 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 WeChat Pay 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 “WECHATPAY”.
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 WeChat Pay.

AUTH response

Python
PHP
Raw JSON
Raw XML

{
  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'WECHATPAY',
    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(9) "WECHATPAY"
      ["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":"WECHATPAY","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="WECHATPAY"/>
    </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 WeChat Pay.
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 WeChat Pay, 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 “WECHATPAY”.
redirecturl XPath: /other/redirecturl	URL (255)	Redirect the customer’s browser to this URL to allow them to complete the payment on WeChat Pay’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 WeChat Pay payment:

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 WeChat Pay’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.

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 WeChat Pay

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

If the customer is redirected to the successfulurlredirect:
The customer successfully completed the required steps on WeChat Pay’s pages.
Recommended actions: Display confirmation that the payment was successful.

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.

When testing, you will be displayed the sandbox as provided by WeChat Pay. 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 WeChat Pay hosted page to either the successfulurlredirect or errorurlredirect hosted on your site, you will need to display either a confirmation or error message respectively.

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

The settlement process for WeChat Pay differs from the standard process followed with card-based payment methods.

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:

When a payment is authorised.
When funds have been settled.

Configuring the authorisation notification

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

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

*Please choose your preferred format.

Configuring the settlement notification

We recommend including the following fields in your settlement notification:

Settle Status (settlestatus)
Site Reference (sitereference)
Transaction Reference (transactionreference)

Check the notification

On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).
On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

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.

Requirements

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

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

Refunds for WeChat Pay are settled immediately (settlestatus “100”).

Requirements

You cannot refund a payment until the AUTH has been settled (settlestatus is “100”).
You cannot refund a greater amount than was originally settled.

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

SafetyPay

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

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

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.

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.

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:

Python
PHP
cURL
Raw JSON
Raw XML

#!/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

Python
PHP
Raw JSON
Raw XML

{
  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:

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.

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.

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.

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.

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

The settlement process for SafetyPay differs from the standard process followed with card-based payment methods.

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:

When a payment is authorised.
When funds have been settled.

Configuring the authorisation notification

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

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

*Please choose your preferred format.

Configuring the settlement notification

We recommend including the following fields in your settlement notification:

Settle Status (settlestatus)
Site Reference (sitereference)
Transaction Reference (transactionreference)

Check the notification

On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).
On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

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.

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.

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

Requirements

You cannot refund a payment until the AUTH has been settled (settlestatus is “100”).
You cannot refund a greater amount than was originally settled.

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

QIWI

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

QIWI is an e-wallet that operates in Russia, Kazakhstan and Ukraine. Customers will be prompted for their QIWI wallet credentials (phone number and password), after which they can complete the order using their preferred payment method. Once completed, you will receive confirmation via a URL notification.

Features

Supported customer countries	KZ, RU, UA
Supported currencies	EUR, KZT, RUB, USD
Protect Plus	Supported.
Refunds	Refunds not supported.
Chargebacks	Payments are not subject to chargebacks.

Configuration

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

Initiate the customer

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

Redirect to QIWI

Merchant redirects the customer’s browser to the redirecturl.
Customer follows instructions on QIWI’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.

Payment completion

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

Python
PHP
cURL
Raw JSON
Raw XML

#!/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": "QIWI",
    "successfulurlredirect": "https://yourwebsite.com",
    "errorurlredirect": "https://yourwebsite.com",
    "billingfirstname": "Joe",
    "billinglastname": "Bloggs",
    "billingcountryiso2a": "RU",
    "billingtelephone": "07890123456",
    "billingtelephonetype": "M"
}

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' => 'QIWI',
    'successfulurlredirect' => 'https://yourwebsite.com',
    'errorurlredirect' => 'https://yourwebsite.com',
    'billingfirstname' => 'Joe',
    'billinglastname' => 'Bloggs',
    'billingcountryiso2a' => 'RU',
    'billingtelephone' => '07890123456',
    'billingtelephonetype' => 'M'
);

$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": "QIWI",
     "successfulurlredirect": "https://www.example.com/success",
     "errorurlredirect": "https://www.example.com/error",
     "billingfirstname": "Joe",
     "billinglastname": "Bloggs",
     "billingcountryiso2a": "RU",
     "billingtelephone": "07890123456",
     "billingtelephonetype": "M"
 }]}'

{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"EUR","requesttypedescriptions":["AUTH"],"accounttypedescription":"ECOM","sitereference":"test_site12345","baseamount":"1050","paymenttypedescription":"QIWI","successfulurlredirect":"https:\/\/www.example.com\/success","errorurlredirect":"https:\/\/www.example.com\/error","billingfirstname":"Joe","billinglastname":"Bloggs","billingcountryiso2a":"RU","billingtelephone":"07890123456","billingtelephonetype":"M"}]}

<?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>RU</country>
      <telephone type="M">0777777777</telephone>
      <amount currencycode="EUR">1050</amount>
      <payment type="QIWI"/>
    </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 QIWI, refer to the list found at the top of this page.
billingtelephonetype XPath: /billing/telephone/@type	Char (1)	At time of writing, only a mobile phone number can be submitted to QIWI. To indicate the billingtelephone submitted is a mobile phone number, the billingtelephonetype must be submitted as “M”.
billingtelephone XPath: /billing/telephone	Alphanumeric including symbols (20)	The customer’s telephone number. Valid characters: Numbers 0-9 Spaces Special characters: + – ( )
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 QIWI, 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 QIWI-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 “QIWI”.
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 QIWI.

AUTH response

Python
PHP
Raw JSON
Raw XML

{
  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'QIWI',
    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) "QIWI"
      ["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":"QIWI","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="QIWI"/>
    </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 QIWI.
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 QIWI, 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 “QIWI”.
redirecturl XPath: /other/redirecturl	URL (255)	Redirect the customer’s browser to this URL to allow them to complete the payment on QIWI’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 QIWI payment:

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

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 QIWI

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

If the customer is redirected to the successfulurlredirect:
The customer successfully completed the required steps on QIWI’s pages.
Recommended actions: Display confirmation that the payment was successful.

When testing, you will be displayed the sandbox as provided by QIWI. 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 QIWI hosted page to either the successfulurlredirect or errorurlredirect hosted on your site, you will need to display either a confirmation or error message respectively.

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

The settlement process for QIWI differs from the standard process followed with card-based payment methods.

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:

When a payment is authorised.
When funds have been settled.

Configuring the authorisation notification

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

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

*Please choose your preferred format.

Configuring the settlement notification

We recommend including the following fields in your settlement notification:

Settle Status (settlestatus)
Site Reference (sitereference)
Transaction Reference (transactionreference)

Check the notification

On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).
On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

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.

Requirements

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

When performing test transactions, the redirect URL returned in the AUTH response will redirect your browser to the QIWI testing environment to simulate a payment. Other than this, the process will be exactly the same as processing live payments.

PayU

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

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

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.

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.

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:

Python
PHP
cURL
Raw JSON
Raw XML

#!/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

Python
PHP
Raw JSON
Raw XML

{
  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:

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.

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.

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.

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.

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

The settlement process for PayU differs from the standard process followed with card-based payment methods.

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:

When a payment is authorised.
When funds have been settled.

Configuring the authorisation notification

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

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

*Please choose your preferred format.

Configuring the settlement notification

We recommend including the following fields in your settlement notification:

Settle Status (settlestatus)
Site Reference (sitereference)
Transaction Reference (transactionreference)

Check the notification

On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).
On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

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.

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.

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

Requirements

You cannot refund a payment until the AUTH has been settled (settlestatus is “100”).
You cannot refund a greater amount than was originally settled.

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

MyBank

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

MyBank is a real-time bank transfer system that operates in Italy. When processing a payment with MyBank, 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	IT
Supported currencies	EUR
Protect Plus	Supported.
Refunds	Full refunds supported (permitted for up to 365 days).
Chargebacks	Payments are not subject to chargebacks.

Configuration

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

Initiate the customer

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

Redirect to MyBank

Merchant redirects the customer’s browser to the redirecturl.
Customer follows instructions on MyBank’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.

Payment completion

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

Python
PHP
cURL
Raw JSON
Raw XML

#!/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": "MYBANK",
    "successfulurlredirect": "https://yourwebsite.com",
    "errorurlredirect": "https://yourwebsite.com",
    "billingfirstname": "Joe",
    "billinglastname": "Bloggs",
    "billingcountryiso2a": "IT"
}

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' => 'MYBANK',
    'successfulurlredirect' => 'https://yourwebsite.com',
    'errorurlredirect' => 'https://yourwebsite.com',
    'billingfirstname' => 'Joe',
    'billinglastname' => 'Bloggs',
    'billingcountryiso2a' => 'IT'
);

$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": "MYBANK",
     "successfulurlredirect": "https://www.example.com/success",
     "errorurlredirect": "https://www.example.com/error",
     "billingfirstname": "Joe",
     "billinglastname": "Bloggs",
     "billingcountryiso2a": "IT"
 }]}'

{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"EUR","requesttypedescription":"AUTH","accounttypedescription":"ECOM","sitereference":"test_site12345","baseamount":"1050","paymenttypedescription":"MYBANK","successfulurlredirect":"https:\/\/www.example.com\/success","errorurlredirect":"https:\/\/www.example.com\/error","billingfirstname":"Joe","billinglastname":"Bloggs","billingcountryiso2a":"IT"}]}

<?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>IT</country>
      <amount currencycode="EUR">1050</amount>
      <payment type="MYBANK"/>
    </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 MyBank, 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 MyBank, 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 MyBank-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 “MYBANK”.
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 MyBank.

AUTH response

Python
PHP
Raw JSON
Raw XML

{
  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'MYBANK',
    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) "MYBANK"
      ["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":"MYBANK","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="MYBANK"/>
    </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 MyBank.
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 MyBank, 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 “MYBANK”.
redirecturl XPath: /other/redirecturl	URL (255)	Redirect the customer’s browser to this URL to allow them to complete the payment on MyBank’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 MyBank payment:

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

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 MyBank

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

If the customer is redirected to the successfulurlredirect:
The customer successfully completed the required steps on MyBank’s pages.
Recommended actions: Display confirmation that the payment was successful.

When testing, you will be displayed the sandbox as provided by MyBank. 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 MyBank hosted page to either the successfulurlredirect or errorurlredirect hosted on your site, you will need to display either a confirmation or error message respectively.

The settlement process for MyBank differs from the standard process followed with card-based payment methods.

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

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:

When a payment is authorised.
When funds have been settled.

Configuring the authorisation notification

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

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

*Please choose your preferred format.

Configuring the settlement notification

We recommend including the following fields in your settlement notification:

Settle Status (settlestatus)
Site Reference (sitereference)
Transaction Reference (transactionreference)

Check the notification

On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).
On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

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.

Requirements

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

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

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

Requirements

You cannot refund a payment until the AUTH has been settled (settlestatus is “100”).
You cannot refund a greater amount than was originally settled.
Partial refunds are not supported for MyBank payments.

The REFUND request and response for MyBank 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.

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

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.

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.

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:

Python
PHP
cURL
Raw JSON
Raw XML

#!/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

Python
PHP
Raw JSON
Raw XML

{
  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:

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.

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.

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.

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.

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

The settlement process for giropay differs from the standard process followed with card-based payment methods.

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:

When a payment is authorised.
When funds have been settled.

Configuring the authorisation notification

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

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

*Please choose your preferred format.

Configuring the settlement notification

We recommend including the following fields in your settlement notification:

Settle Status (settlestatus)
Site Reference (sitereference)
Transaction Reference (transactionreference)

Check the notification

On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).
On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

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.

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.

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

Requirements

You cannot refund a payment until the AUTH has been settled (settlestatus is “100”).
You cannot refund a greater amount than was originally settled.

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

Przelewy24

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

Przelewy24 is a Polish real-time bank transfer method. When selecting Przelewy24, 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 authorise the payment, before being redirected back to your website. Once completed, you will receive confirmation via a URL notification.

Features

Supported customer countries	PL
Supported currencies	EUR, PLN
Protect Plus	Supported.
Refunds	Full and partial refunds supported (permitted for up to 90 days). After 90 days, the customer must seek refund directly with P24.
Chargebacks	Payments are not subject to chargebacks.

Configuration

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

Initiate the customer

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

Redirect to Przelewy24

Merchant redirects the customer’s browser to the redirecturl.
Customer follows instructions on Przelewy24’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.

Payment completion

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

Python
PHP
cURL
Raw JSON
Raw XML

#!/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": "PRZELEWY24",
    "successfulurlredirect": "https://yourwebsite.com",
    "errorurlredirect": "https://yourwebsite.com",
    "billingfirstname": "Joe",
    "billinglastname": "Bloggs",
    "billingcountryiso2a": "PL",
    "billingemail": "[email protected]"
}

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' => 'PRZELEWY24',
    'successfulurlredirect' => 'https://yourwebsite.com',
    'errorurlredirect' => 'https://yourwebsite.com',
    'billingfirstname' => 'Joe',
    'billinglastname' => 'Bloggs',
    'billingcountryiso2a' => 'PL',
    'billingemail' => '[email protected]'
);

$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": "PRZELEWY24",
    "successfulurlredirect": "https://www.example.com/success",
    "errorurlredirect": "https://www.example.com/error",
    "billingfirstname": "Joe",
    "billinglastname": "Bloggs",
    "billingcountryiso2a": "PL",
    "billingemail" : "[email protected]"
}]}'

{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"EUR","requesttypedescriptions":["AUTH"],"accounttypedescription":"ECOM","sitereference":"test_site12345","baseamount":"1050","paymenttypedescription":"PRZELEWY24","successfulurlredirect":"https:\/\/www.example.com\/success","errorurlredirect":"https:\/\/www.example.com\/error","billingfirstname":"Joe","billinglastname":"Bloggs","billingcountryiso2a":"PL","billingemail":"[email protected]"}]}

<?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>PL</country>
      <email>[email protected]</email>
      <amount currencycode="EUR">1050</amount>
      <payment type="PRZELEWY24"/>
    </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 Przelewy24, refer to the list found at the top of this page.
billingemail XPath: /billing/email	Email (255)	The customer’s billing email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
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 Przelewy24, 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 Przelewy24-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 “PRZELEWY24”.
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 Przelewy24.

AUTH response

Python
PHP
Raw JSON
Raw XML

{
  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'PRZELEWY24',
    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) "PRZELEWY24"
      ["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":"PRZELEWY24","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="PRZELEWY24"/>
    </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 Przelewy24.
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 Przelewy24, 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 “PRZELEWY24”.
redirecturl XPath: /other/redirecturl	URL (255)	Redirect the customer’s browser to this URL to allow them to complete the payment on Przelewy24’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 Przelewy24 payment:

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

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 Przelewy24

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

If the customer is redirected to the successfulurlredirect:
The customer successfully completed the required steps on Przelewy24’s pages.
Recommended actions: Display confirmation that the payment was successful.

When testing, you will be displayed the sandbox as provided by Przelewy24. 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 Przelewy24 hosted page to either the successfulurlredirect or errorurlredirect hosted on your site, you will need to display either a confirmation or error message respectively.

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

The settlement process for Przelewy24 differs from the standard process followed with card-based payment methods.

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:

When a payment is authorised.
When funds have been settled.

Configuring the authorisation notification

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

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

*Please choose your preferred format.

Configuring the settlement notification

We recommend including the following fields in your settlement notification:

Settle Status (settlestatus)
Site Reference (sitereference)
Transaction Reference (transactionreference)

Check the notification

On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).
On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

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.

Requirements

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

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

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

Requirements

You cannot refund a payment until the AUTH has been settled (settlestatus is “100”).
You cannot refund a greater amount than was originally settled.

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

Sofort

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

Sofort is a real-time bank transfer method that operates in Germany, Austria, The Netherlands and Belgium. When selecting Sofort, 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	AT, BE, CH, DE, ES, IT, NL, PL
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 Sofort 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

Initiate the customer

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

Redirect to Sofort

Merchant redirects the customer’s browser to the redirecturl.
Customer follows instructions on Sofort’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.

Payment completion

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

Python
PHP
cURL
Raw JSON
Raw XML

#!/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": "SOFORT",
    "successfulurlredirect": "https://yourwebsite.com",
    "errorurlredirect": "https://yourwebsite.com",
    "billingfirstname": "Joe",
    "billinglastname": "Bloggs",
    "billingcountryiso2a": "DE",
    "bankid": "12345"
}

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' => 'SOFORT',
    'successfulurlredirect' => 'https://yourwebsite.com',
    'errorurlredirect' => 'https://yourwebsite.com',
    'billingfirstname' => 'Joe',
    'billinglastname' => 'Bloggs',
    'billingcountryiso2a' => 'DE',
    'bankid' => '12345'
);

$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": "SOFORT",
    "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","requesttypedescriptions":["AUTH"],"accounttypedescription":"ECOM","sitereference":"test_site12345","baseamount":"1050","paymenttypedescription":"SOFORT","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>NL</country>
      <bankid>12345</bankid>
      <amount currencycode="EUR">1050</amount>
      <payment type="SOFORT"/>
    </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.
bankid XPath: /billing/bankid	Alphanumeric (25)	The customer’s Bank Identification Code (BIC).
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 Sofort, 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 Sofort, 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 Sofort-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 “SOFORT”.
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 Sofort.

AUTH response

Python
PHP
Raw JSON
Raw XML

{
  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'SOFORT',
    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) "SOFORT"
      ["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":"SOFORT","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="SOFORT"/>
    </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 Sofort.
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 Sofort, 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 “SOFORT”.
redirecturl XPath: /other/redirecturl	URL (255)	Redirect the customer’s browser to this URL to allow them to complete the payment on Sofort’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 Sofort payment:

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

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 Sofort

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

If the customer is redirected to the successfulurlredirect:
The customer successfully completed the required steps on Sofort’s pages.
Recommended actions: Display confirmation that the payment was successful.

When testing, you will be displayed the sandbox as provided by Sofort. 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 Sofort hosted page to either the successfulurlredirect or errorurlredirect hosted on your site, you will need to display either a confirmation or error message respectively.

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

The settlement process for Sofort differs from the standard process followed with card-based payment methods.

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:

When a payment is authorised.
When funds have been settled.

Configuring the authorisation notification

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

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

*Please choose your preferred format.

Configuring the settlement notification

We recommend including the following fields in your settlement notification:

Settle Status (settlestatus)
Site Reference (sitereference)
Transaction Reference (transactionreference)

Check the notification

On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).
On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

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.

Requirements

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

When performing test transactions, the redirect URL returned in the AUTH response will redirect your browser to the Sofort testing environment to simulate a payment. Other than this, the process will be exactly the same as processing live payments.

When your browser has been redirected to the Sofort test environment, you will be prompted for test credentials in order to complete a payment.

When prompted, select “Demo bank” as your bank and enter “12345” as your account number and PIN.

Finally, select from the list of sandbox bank accounts presented, then follow on-screen instructions to enter the transaction confirmation code and complete the payment.

Refunds

After processing a payment with Sofort, it is possible to refund the customer by submitting a REFUND request.

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

Requirements

You cannot refund a payment until the AUTH has been settled (settlestatus is “100”).
You cannot refund a greater amount than was originally settled.

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

iDEAL

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

iDEAL is a Dutch real-time bank transfer method. When selecting iDEAL, 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	NL
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 iDEAL 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

Initiate the customer

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

Redirect to iDEAL

Merchant redirects the customer’s browser to the redirecturl.
Customer follows instructions on iDEAL’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.

Payment completion

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

Python
PHP
cURL
Raw JSON
Raw XML

#!/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": "IDEAL",
    "successfulurlredirect": "https://yourwebsite.com",
    "errorurlredirect": "https://yourwebsite.com",
    "billingfirstname": "Joe",
    "billinglastname": "Bloggs",
    "billingcountryiso2a": "NL"
}

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' => 'IDEAL',
    'successfulurlredirect' => 'https://yourwebsite.com',
    'errorurlredirect' => 'https://yourwebsite.com',
    'billingfirstname' => 'Joe',
    'billinglastname' => 'Bloggs',
    'billingcountryiso2a' => 'NL'
);

$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": "IDEAL",
     "successfulurlredirect": "https://www.example.com/success",
     "errorurlredirect": "https://www.example.com/error",
     "billingfirstname": "Joe",
     "billinglastname": "Bloggs",
     "billingcountryiso2a": "NL"
 }]}'

{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"EUR","requesttypedescription":"AUTH","accounttypedescription":"ECOM","sitereference":"test_site12345","baseamount":"1050","paymenttypedescription":"IDEAL","successfulurlredirect":"https:\/\/www.example.com\/success","errorurlredirect":"https:\/\/www.example.com\/error","billingfirstname":"Joe","billinglastname":"Bloggs","billingcountryiso2a":"NL"}]}

<?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>NL</country>
      <amount currencycode="EUR">1050</amount>
      <payment type="IDEAL"/>
    </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 iDEAL, 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 iDEAL, 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 iDEAL-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 “IDEAL”.
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 iDEAL.

AUTH response

Python
PHP
Raw JSON
Raw XML

{
  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'IDEAL',
    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) "IDEAL"
      ["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":"IDEAL","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="IDEAL"/>
    </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 iDEAL.
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 iDEAL, 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 “IDEAL”.
redirecturl XPath: /other/redirecturl	URL (255)	Redirect the customer’s browser to this URL to allow them to complete the payment on iDEAL’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 iDEAL payment:

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

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 iDEAL

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

If the customer is redirected to the successfulurlredirect:
The customer successfully completed the required steps on iDEAL’s pages.
Recommended actions: Display confirmation that the payment was successful.

When testing, you will be displayed the sandbox as provided by iDEAL. 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 iDEAL hosted page to either the successfulurlredirect or errorurlredirect hosted on your site, you will need to display either a confirmation or error message respectively.

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

The settlement process for iDEAL differs from the standard process followed with card-based payment methods.

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:

When a payment is authorised.
When funds have been settled.

Configuring the authorisation notification

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

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

*Please choose your preferred format.

Configuring the settlement notification

We recommend including the following fields in your settlement notification:

Settle Status (settlestatus)
Site Reference (sitereference)
Transaction Reference (transactionreference)

Check the notification

On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).
On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

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.

Requirements

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

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

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

Requirements

You cannot refund a payment until the AUTH has been settled (settlestatus is “100”).
You cannot refund a greater amount than was originally settled.

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