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

Features
![]() |
![]() |
![]() |
![]() |
![]() |
Supported.![]() |
![]() |
![]() |
![]() |
![]() |
Configuration
To enable SafetyPay on your account, please get in touch with your account manager.
A test sandbox account will be provided, which you will need when testing your implementation.
Process overview

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

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

- At a later time, SafetyPay will contact Trust Payments with confirmation that funds have been settled.
- Trust Payments will submit a URL notification to the merchant’s system to confirm funds have settled.
- Merchant receives the notification and responds to inform Trust Payments the notification was received successfully.
1. Initiate the customer
When the customer chooses to pay with SafetyPay, your system will need to perform an AUTH request and, if successful, redirect the customer’s browser to the URL returned in the response.
AUTH request
The example request below is for a SafetyPay AUTH request:
#!/usr/bin/python import securetrading stconfig = securetrading.Config() stconfig.username = "[email protected]" stconfig.password = "Password1^" st = securetrading.Api(stconfig) auth = { "currencyiso3a": "EUR", "requesttypedescription": "AUTH", "accounttypedescription": "ECOM", "sitereference": "test_site12345", "baseamount": "1050", "paymenttypedescription": "SAFETYPAY", "successfulurlredirect": "https://yourwebsite.com", "errorurlredirect": "https://yourwebsite.com", "billingfirstname": "Joe", "billinglastname": "Bloggs", "billingcountryiso2a": "DE" } strequest = securetrading.Request() strequest.update(auth) stresponse = st.process(strequest) #stresponse contains the transaction response
<?php if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) { throw new Exception('Composer autoloader file could not be found.'); } require_once($autoload); $configData = array( 'username' => '[email protected]', 'password' => 'Password1^' ); $requestData = array( 'currencyiso3a' => 'EUR', 'requesttypedescription' => 'AUTH', 'accounttypedescription' => 'ECOM', 'sitereference' => 'test_site12345', 'baseamount' => '1050', 'paymenttypedescription' => 'SAFETYPAY', 'successfulurlredirect' => 'https://yourwebsite.com', 'errorurlredirect' => 'https://yourwebsite.com', 'billingfirstname' => 'Joe', 'billinglastname' => 'Bloggs', 'billingcountryiso2a' => 'DE' ); $api = \Securetrading\api($configData); $response = $api->process($requestData); var_dump($response->toArray()); ?>
curl --user [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{ "alias": "[email protected]", "version": "1.00", "request": [{ "currencyiso3a": "EUR", "requesttypedescription": "AUTH", "accounttypedescription": "ECOM", "sitereference": "test_site12345", "baseamount": "1050", "paymenttypedescription": "SAFETYPAY", "successfulurlredirect": "https://www.example.com/success", "errorurlredirect": "https://www.example.com/error", "billingfirstname": "Joe", "billinglastname": "Bloggs", "billingcountryiso2a": "DE" }]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"EUR","requesttypedescription":"AUTH","accounttypedescription":"ECOM","sitereference":"test_site12345","baseamount":"1050","paymenttypedescription":"SAFETYPAY","successfulurlredirect":"https:\/\/www.example.com\/success","errorurlredirect":"https:\/\/www.example.com\/error","billingfirstname":"Joe","billinglastname":"Bloggs","billingcountryiso2a":"DE"}]}
<?xml version='1.0' encoding='utf-8'?> <requestblock version="3.67"> <alias>[email protected]</alias> <request type="AUTH"> <merchant> <successfulurlredirect>https://www.example.com/success</successfulurlredirect> <errorurlredirect>https://www.example.com/error</errorurlredirect> </merchant> <billing> <name> <first>Joe</first> <last>Bloggs</last> </name> <country>ES</country> <amount currencycode="EUR">1050</amount> <payment type="SAFETYPAY"/> </billing> <operation> <sitereference>test_site12345</sitereference> <accounttypedescription>ECOM</accounttypedescription> </operation> </request> </requestblock>
Replace <DOMAIN> with a supported domain. Click here for a full list.
Field specification
Field | Format | Description | |
![]() |
accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) | Only “ECOM” (e-commerce) is supported. |
![]() |
baseamount XPath: /billing/amount |
Numeric (13) | The amount of the transaction in base units, with no commas or decimal points, so €10 is submitted as 1000. This value must be greater than zero. (Max length may vary depending on your acquiring bank – Contact your bank for further info) |
![]() |
billingprefixname XPath: /billing/name/prefix |
Alphanumeric including symbols (25) |
The prefix of the customer’s billing name (e.g. Mr, Miss, Dr). |
![]() |
billingfirstname XPath: /billing/name/first |
Alphanumeric including symbols (127) |
The customer’s billing first name. |
![]() |
billingmiddlename XPath: /billing/name/middle |
Alphanumeric including symbols (127) |
The customer’s billing middle name(s). |
![]() |
billinglastname XPath: /billing/name/last |
Alphanumeric including symbols (127) |
The customer’s billing last name. |
![]() |
billingsuffixname XPath: /billing/name/suffix |
Alphanumeric including symbols (25) |
The suffix of the customer’s billing name (e.g. Bsc). |
![]() |
billingcountryiso2a XPath: /billing/country |
Alpha (2) | The country for the customer’s billing address. This will need to be in ISO2A format.
For a list of country codes supported by SafetyPay, refer to the list found at the top of this page. |
![]() |
currencyiso3a XPath: /billing/amount/@currencycode |
Alpha (3) | The currency that the transaction will be processed in (in ISO3A format).
For a list of currency codes supported by SafetyPay, refer to the list found at the top of this page. |
![]() |
errorurlredirect XPath: /merchant/errorurlredirect |
URL (2048) | The URL that the customer will be returned to following an error on the SafetyPay-hosted pages. |
![]() |
orderreference XPath: /merchant/orderreference |
Alphanumeric including symbols (255) |
Your unique order reference that can be stored on the Trust Payments system. |
![]() |
paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | This value must be submitted as “SAFETYPAY”. |
![]() |
requesttypedescription XPath: /@type |
Alpha (20) | The value in the request must be “AUTH”. |
![]() |
sitereference XPath: /operation/sitereference |
Alphanumeric & underscore (50) |
The site reference relates to your individual account which you received on setup. If you do not know your site reference, please contact our Support team. |
![]() |
successfulurlredirect XPath: /merchant/successfulurlredirect |
URL (2048) | The URL that the customer will be returned to following a successful authorisation by SafetyPay. |
AUTH response
{ u'requestreference': u'An3ug1kap', u'version': u'1.00', u'response': [{ u'transactionreference': u'23-86-113', u'merchantname': u'Test Merchant', u'paymenttypedescription': u'SAFETYPAY', u'settleduedate': u'2017-03-16', u'baseamount': u'1050', u'transactionstartedtimestamp': u'2017-03-16 16:25:08', u'errormessage': u'Ok', u'settlestatus': u'10', u'accounttypedescription': u'ECOM', u'errorcode': u'0', u'redirecturl': u'https://example.com', u'acquirertransactionreference': u'12', u'acquirersecret': u'q9gy5ppgdyd5fh60kfe2j0f26peu2xww', u'requesttypedescription': u'AUTH', u'acquirerresponsemessage': u'PENDING', u'operatorname': u'[email protected]', u'livestatus': u'0', u'currencyiso3a': u'EUR' }] }
array(3) { ["requestreference"] => string(9) "A0345jmuw" ["version"] => string(4) "1.00" ["response"] => array(1) { [0] => array(18) { ["transactionreference"] => string(9) "23-86-113" ["merchantname"] => string(4) "Test Merchant" ["paymenttypedescription"] => string(10) "SAFETYPAY" ["settleduedate"] => string(10) "2017-03-16" ["baseamount"] => string(4) "1050" ["transactionstartedtimestamp"] => string(19) "2017-03-16 16:25:08" ["errormessage"] => string(2) "Ok" ["settlestatus"] => string(2) "10" ["accounttypedescription"] => string(4) "ECOM" ["errorcode"] => string(1) "0" ["redirecturl"] => string(107) "https://example.com" ["acquirertransactionreference"] => string(2) "12" ["acquirersecret"] => string(32) "q9gy5ppgdyd5fh60kfe2j0f26peu2xww" ["requesttypedescription"] => string(4) "AUTH" ["acquirerresponsemessage"] => string(7) "PENDING" ["operatorname"] => string(11) "[email protected]" ["livestatus"] => string(1) "0" ["currencyiso3a"] => string(3) "EUR" } } }
{"requestreference":"W23-fjgvn3d9","version":"1.00","response":[{"transactionreference":"23-86-113","merchantname":"Test Merchant","paymenttypedescription":"SAFETYPAY","settleduedate":"2017-03-16","baseamount":"1050","transactionstartedtimestamp":"2017-03-16 16:25:08","errormessage":"Ok","settlestatus":"10","accounttypedescription":"ECOM","errorcode":"0","redirecturl":"https:\/\/example.com","acquirertransactionreference":"12","acquirersecret":"q9gy5ppgdyd5fh60kfe2j0f26peu2xww","requesttypedescription":"AUTH","acquirerresponsemessage":"PENDING","operatorname":"[email protected]","livestatus":"0","currencyiso3a":"EUR"}]}
<?xml version='1.0' encoding='utf-8'?> <responseblock version="3.67"> <requestreference>Xd4nk260v</requestreference> <response type="AUTH"> <merchant> <merchantname>Test Merchant</merchantname> <operatorname>[email protected]</operatorname> </merchant> <transactionreference>44-86-102</transactionreference> <timestamp>2017-03-16 17:34:16</timestamp> <acquirersecret>gfc8mx0p2fx26f1n5tpy6mtk21naap8c</acquirersecret> <operation> <accounttypedescription>ECOM</accounttypedescription> </operation> <settlement> <settleduedate>2017-03-16</settleduedate> <settlestatus>10</settlestatus> </settlement> <acquirerresponsemessage>PENDING</acquirerresponsemessage> <billing> <amount currencycode="EUR">1050</amount> <payment type="SAFETYPAY"/> </billing> <live>0</live> <other> <redirecturl>https://example.com</redirecturl> </other> <acquirertransactionreference>4</acquirertransactionreference> <error> <message>Ok</message> <code>0</code> </error> </response> <secrand>Z1W</secrand> </responseblock>
Field specification
Field | Format | Description | |
![]() |
accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) | The value returned is “ECOM”. |
![]() |
acquirerresponsemessage XPath: /acquirerresponsemessage |
Alphanumeric (255) | Used by your acquirer to indicate the outcome of the request. |
![]() |
acquirersecret XPath: /acquirersecret |
Alphanumeric (64) | Used by Trust Payments to verify the response from the acquirer. (Your system does not need to verify this) |
![]() |
acquirertransactionreference XPath: /acquirertransactionreference |
Alphanumeric including symbols (127) | Unique transaction reference assigned by SafetyPay. |
![]() |
baseamount XPath: /billing/amount |
Numeric (13) | The amount of the transaction in base units, with no commas or decimal points, so €10 is returned as 1000. |
![]() |
currencyiso3a XPath: /billing/amount/@currencycode |
Alpha (3) | The currency that the transaction was processed in (in ISO3A format).
For a list of currency codes supported by SafetyPay, refer to the list found at the top of this page. |
![]() |
errorcode XPath: /error/code |
Numeric (1-5) | The error code should be used to determine if the request was successful or not.
|
![]() |
errordata XPath: /error/data |
Alphanumeric (255) | Additional information to help troubleshoot the error. |
![]() |
errormessage XPath: /error/message |
Alphanumeric (255) | This is the corresponding message to the above code. |
![]() |
livestatus XPath: /live |
Numeric (1) |
|
![]() |
merchantname XPath: /merchant/merchantname |
Alphanumeric (255) | These are details associated with the account used to process the transaction.
To amend these fields, please contact our Support Team. |
![]() |
operatorname XPath: /merchant/operatorname |
Alphanumeric (255) | The value of this field contains the name of the user that processed the request. |
![]() |
paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | This value returned is “SAFETYPAY”. |
![]() |
redirecturl XPath: /other/redirecturl |
URL (255) | Redirect the customer’s browser to this URL to allow them to complete the payment on SafetyPay’s hosted pages. |
![]() |
requesttypedescription XPath: /@type |
Alpha (20) | The value returned is “AUTH”. |
![]() |
settleduedate XPath: /settlement/settleduedate |
Date YYYY-MM-DD | The date on which the transaction will be settled. |
![]() |
settlestatus XPath: /settlement/settlestatus |
Numeric (3) | This allows you to determine the status of the payment. Refer to the Handling the response section below for information on how to best interpret this field. |
![]() |
transactionreference XPath: /transactionreference |
Alphanumeric including hyphens (25) |
A unique reference for the transaction assigned by Trust Payments. |
![]() |
transactionstartedtimestamp XPath: /timestamp |
Date time YYYY-MM-DD hh:mm:ss | The time the transaction was processed. |
Handling the response
The settlestatus returned in the AUTH response is used to determine the status of the SafetyPay payment:

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

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

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

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

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

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


In the unlikely event that payment is still pending settlement after 7 days (settlestatus “10”), this will be scheduled for investigation and we will contact you with further information.
Before you begin testing, we recommend that you contact our Support team and request that rules are enabled on your account, which submit URL notifications to your system in the following scenarios:
- When a payment is authorised.
- When funds have been settled.
Configuring the authorisation notification
We recommend including at least the following fields in your authorisation notification:
- Acquirer Response Message (acquirerresponsemessage)
- Base Amount (baseamount) (e.g. £10.50 is “1050”)*
- Main Amount (mainamount) (e.g. £10.50 is “10.50”)*
- Billing Country (billingcountryiso2a)
- Currency (currencyiso3a)
- Error Code (errorcode)
- Live Status (livestatus)
- Order Reference (orderreference)
- Payment Type (paymenttypedescription)
- Request Type (requesttypedescription)
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
- Transaction Started Timestamp (transactionstartedtimestamp)
*Please choose your preferred format.
Configuring the settlement notification
We recommend including the following fields in your settlement notification:
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
Check the notification
You will need to check the contents of each notification received and respond accordingly by following the processes outlined in the “URL notifications” section of our Action types page. In particular, you will need to look at the updated settlestatus value:
- On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).
- On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

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

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

Requirements
- You cannot refund a payment until the AUTH has been settled (settlestatus is “100”).
- You cannot refund a greater amount than was originally settled.
The REFUND request and response for SafetyPay payments follow the same field specification as outlined in our standard REFUND documentation. Click here for further information.
PayU
The requests outlined in this document will need to be processed manually using our Webservices API.

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

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

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

- At a later time, PayU will contact Trust Payments with confirmation that funds have been settled.
- Trust Payments will submit a URL notification to the merchant’s system to confirm funds have settled.
- Merchant receives the notification and responds to inform Trust Payments the notification was received successfully.
1. Initiate the customer
When the customer chooses to pay with PayU, your system will need to perform an AUTH request and, if successful, redirect the customer’s browser to the URL returned in the response.
AUTH request
The example request below is for a PayU AUTH request:
#!/usr/bin/python import securetrading stconfig = securetrading.Config() stconfig.username = "[email protected]" stconfig.password = "Password1^" st = securetrading.Api(stconfig) auth = { "currencyiso3a": "PLN", "requesttypedescription": "AUTH", "accounttypedescription": "ECOM", "sitereference": "test_site12345", "baseamount": "1050", "paymenttypedescription": "PAYU", "successfulurlredirect": "https://yourwebsite.com", "errorurlredirect": "https://yourwebsite.com", "billingfirstname": "Joe", "billinglastname": "Bloggs", "billingcountryiso2a": "PL" } strequest = securetrading.Request() strequest.update(auth) stresponse = st.process(strequest) #stresponse contains the transaction response
<?php if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) { throw new Exception('Composer autoloader file could not be found.'); } require_once($autoload); $configData = array( 'username' => '[email protected]', 'password' => 'Password1^' ); $requestData = array( 'currencyiso3a' => 'PLN', 'requesttypedescription' => 'AUTH', 'accounttypedescription' => 'ECOM', 'sitereference' => 'test_site12345', 'baseamount' => '1050', 'paymenttypedescription' => 'PAYU', 'successfulurlredirect' => 'https://yourwebsite.com', 'errorurlredirect' => 'https://yourwebsite.com', 'billingfirstname' => 'Joe', 'billinglastname' => 'Bloggs', 'billingcountryiso2a' => 'PL' ); $api = \Securetrading\api($configData); $response = $api->process($requestData); var_dump($response->toArray()); ?>
curl --user [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{ "alias": "[email protected]", "version": "1.00", "request": [{ "currencyiso3a": "PLN", "requesttypedescription": "AUTH", "accounttypedescription": "ECOM", "sitereference": "test_site12345", "baseamount": "1050", "paymenttypedescription": "PAYU", "successfulurlredirect": "https://www.example.com/success", "errorurlredirect": "https://www.example.com/error", "billingfirstname": "Joe", "billinglastname": "Bloggs", "billingcountryiso2a": "PL" }]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"PLN","requesttypedescription":"AUTH","accounttypedescription":"ECOM","sitereference":"test_site12345","baseamount":"1050","paymenttypedescription":"PAYU","successfulurlredirect":"https:\/\/www.example.com\/success","errorurlredirect":"https:\/\/www.example.com\/error","billingfirstname":"Joe","billinglastname":"Bloggs","billingcountryiso2a":"PL"}]}
<?xml version='1.0' encoding='utf-8'?> <requestblock version="3.67"> <alias>[email protected]</alias> <request type="AUTH"> <merchant> <successfulurlredirect>https://www.example.com/success</successfulurlredirect> <errorurlredirect>https://www.example.com/error</errorurlredirect> </merchant> <billing> <name> <first>Joe</first> <last>Bloggs</last> </name> <country>CZ</country> <amount currencycode="CZK">1050</amount> <payment type="PAYU"/> </billing> <operation> <sitereference>test_site12345</sitereference> <accounttypedescription>ECOM</accounttypedescription> </operation> </request> </requestblock>
Replace <DOMAIN> with a supported domain. Click here for a full list.
Field specification
Field | Format | Description | |
![]() |
accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) | Only “ECOM” (e-commerce) is supported. |
![]() |
baseamount XPath: /billing/amount |
Numeric (13) | The amount of the transaction in base units, with no commas or decimal points, so €10 is submitted as 1000. This value must be greater than zero. (Max length may vary depending on your acquiring bank – Contact your bank for further info) |
![]() |
billingprefixname XPath: /billing/name/prefix |
Alphanumeric including symbols (25) |
The prefix of the customer’s billing name (e.g. Mr, Miss, Dr). |
![]() |
billingfirstname XPath: /billing/name/first |
Alphanumeric including symbols (127) |
The customer’s billing first name. |
![]() |
billingmiddlename XPath: /billing/name/middle |
Alphanumeric including symbols (127) |
The customer’s billing middle name(s). |
![]() |
billinglastname XPath: /billing/name/last |
Alphanumeric including symbols (127) |
The customer’s billing last name. |
![]() |
billingsuffixname XPath: /billing/name/suffix |
Alphanumeric including symbols (25) |
The suffix of the customer’s billing name (e.g. Bsc). |
![]() |
billingcountryiso2a XPath: /billing/country |
Alpha (2) | The country for the customer’s billing address. This will need to be in ISO2A format.
For a list of country codes supported by PayU, refer to the list found at the top of this page. |
![]() |
currencyiso3a XPath: /billing/amount/@currencycode |
Alpha (3) | The currency that the transaction will be processed in (in ISO3A format).
For a list of currency codes supported by PayU, refer to the list found at the top of this page. |
![]() |
errorurlredirect XPath: /merchant/errorurlredirect |
URL (2048) | The URL that the customer will be returned to following an error on the PayU-hosted pages. |
![]() |
orderreference XPath: /merchant/orderreference |
Alphanumeric including symbols (255) |
Your unique order reference that can be stored on the Trust Payments system. |
![]() |
paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | This value must be submitted as “PAYU”. |
![]() |
requesttypedescription XPath: /@type |
Alpha (20) | The value in the request must be “AUTH”. |
![]() |
sitereference XPath: /operation/sitereference |
Alphanumeric & underscore (50) |
The site reference relates to your individual account which you received on setup. If you do not know your site reference, please contact our Support team. |
![]() |
successfulurlredirect XPath: /merchant/successfulurlredirect |
URL (2048) | The URL that the customer will be returned to following a successful authorisation by PayU. |
AUTH response
{ u'requestreference': u'An3ug1kap', u'version': u'1.00', u'response': [{ u'transactionreference': u'23-86-113', u'merchantname': u'Test Merchant', u'paymenttypedescription': u'PAYU', u'settleduedate': u'2017-03-16', u'baseamount': u'1050', u'transactionstartedtimestamp': u'2017-03-16 16:25:08', u'errormessage': u'Ok', u'settlestatus': u'10', u'accounttypedescription': u'ECOM', u'errorcode': u'0', u'redirecturl': u'https://example.com', u'acquirertransactionreference': u'12', u'acquirersecret': u'q9gy5ppgdyd5fh60kfe2j0f26peu2xww', u'requesttypedescription': u'AUTH', u'acquirerresponsemessage': u'PENDING', u'operatorname': u'[email protected]', u'livestatus': u'0', u'currencyiso3a': u'PLN' }] }
array(3) { ["requestreference"] => string(9) "A0345jmuw" ["version"] => string(4) "1.00" ["response"] => array(1) { [0] => array(18) { ["transactionreference"] => string(9) "23-86-113" ["merchantname"] => string(4) "Test Merchant" ["paymenttypedescription"] => string(10) "PAYU" ["settleduedate"] => string(10) "2017-03-16" ["baseamount"] => string(4) "1050" ["transactionstartedtimestamp"] => string(19) "2017-03-16 16:25:08" ["errormessage"] => string(2) "Ok" ["settlestatus"] => string(2) "10" ["accounttypedescription"] => string(4) "ECOM" ["errorcode"] => string(1) "0" ["redirecturl"] => string(107) "https://example.com" ["acquirertransactionreference"] => string(2) "12" ["acquirersecret"] => string(32) "q9gy5ppgdyd5fh60kfe2j0f26peu2xww" ["requesttypedescription"] => string(4) "AUTH" ["acquirerresponsemessage"] => string(7) "PENDING" ["operatorname"] => string(11) "[email protected]" ["livestatus"] => string(1) "0" ["currencyiso3a"] => string(3) "PLN" } } }
{"requestreference":"W23-fjgvn3d9","version":"1.00","response":[{"transactionreference":"23-86-113","merchantname":"Test Merchant","paymenttypedescription":"PAYU","settleduedate":"2017-03-16","baseamount":"1050","transactionstartedtimestamp":"2017-03-16 16:25:08","errormessage":"Ok","settlestatus":"10","accounttypedescription":"ECOM","errorcode":"0","redirecturl":"https:\/\/example.com","acquirertransactionreference":"12","acquirersecret":"q9gy5ppgdyd5fh60kfe2j0f26peu2xww","requesttypedescription":"AUTH","acquirerresponsemessage":"PENDING","operatorname":"[email protected]","livestatus":"0","currencyiso3a":"PLN"}]}
<?xml version='1.0' encoding='utf-8'?> <responseblock version="3.67"> <requestreference>Xd4nk260v</requestreference> <response type="AUTH"> <merchant> <merchantname>Test Merchant</merchantname> <operatorname>[email protected]</operatorname> </merchant> <transactionreference>44-86-102</transactionreference> <timestamp>2017-03-16 17:34:16</timestamp> <acquirersecret>gfc8mx0p2fx26f1n5tpy6mtk21naap8c</acquirersecret> <operation> <accounttypedescription>ECOM</accounttypedescription> </operation> <settlement> <settleduedate>2017-03-16</settleduedate> <settlestatus>10</settlestatus> </settlement> <acquirerresponsemessage>PENDING</acquirerresponsemessage> <billing> <amount currencycode="CZK">1050</amount> <payment type="PAYU"/> </billing> <live>0</live> <other> <redirecturl>https://example.com</redirecturl> </other> <acquirertransactionreference>4</acquirertransactionreference> <error> <message>Ok</message> <code>0</code> </error> </response> <secrand>Z1W</secrand> </responseblock>
Field specification
Field | Format | Description | |
![]() |
accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) | The value returned is “ECOM”. |
![]() |
acquirerresponsemessage XPath: /acquirerresponsemessage |
Alphanumeric (255) | Used by your acquirer to indicate the outcome of the request. |
![]() |
acquirersecret XPath: /acquirersecret |
Alphanumeric (64) | Used by Trust Payments to verify the response from the acquirer. (Your system does not need to verify this) |
![]() |
acquirertransactionreference XPath: /acquirertransactionreference |
Alphanumeric including symbols (127) | Unique transaction reference assigned by PayU. |
![]() |
baseamount XPath: /billing/amount |
Numeric (13) | The amount of the transaction in base units, with no commas or decimal points, so €10 is returned as 1000. |
![]() |
currencyiso3a XPath: /billing/amount/@currencycode |
Alpha (3) | The currency that the transaction was processed in (in ISO3A format).
For a list of currency codes supported by PayU, refer to the list found at the top of this page. |
![]() |
errorcode XPath: /error/code |
Numeric (1-5) | The error code should be used to determine if the request was successful or not.
|
![]() |
errordata XPath: /error/data |
Alphanumeric (255) | Additional information to help troubleshoot the error. |
![]() |
errormessage XPath: /error/message |
Alphanumeric (255) | This is the corresponding message to the above code. |
![]() |
livestatus XPath: /live |
Numeric (1) |
|
![]() |
merchantname XPath: /merchant/merchantname |
Alphanumeric (255) | These are details associated with the account used to process the transaction.
To amend these fields, please contact our Support Team. |
![]() |
operatorname XPath: /merchant/operatorname |
Alphanumeric (255) | The value of this field contains the name of the user that processed the request. |
![]() |
paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | This value returned is “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:

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

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

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

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

3. Payment completion
Once the customer returns from the 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.


In the unlikely event that payment is still pending settlement after 7 days (settlestatus “10”), this will be scheduled for investigation and we will contact you with further information.
Before you begin testing, we recommend that you contact our Support team and request that rules are enabled on your account, which submit URL notifications to your system in the following scenarios:
- When a payment is authorised.
- When funds have been settled.
Configuring the authorisation notification
We recommend including at least the following fields in your authorisation notification:
- Acquirer Response Message (acquirerresponsemessage)
- Base Amount (baseamount) (e.g. £10.50 is “1050”)*
- Main Amount (mainamount) (e.g. £10.50 is “10.50”)*
- Billing Country (billingcountryiso2a)
- Currency (currencyiso3a)
- Error Code (errorcode)
- Live Status (livestatus)
- Order Reference (orderreference)
- Payment Type (paymenttypedescription)
- Request Type (requesttypedescription)
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
- Transaction Started Timestamp (transactionstartedtimestamp)
*Please choose your preferred format.
Configuring the settlement notification
We recommend including the following fields in your settlement notification:
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
Check the notification
You will need to check the contents of each notification received and respond accordingly by following the processes outlined in the “URL notifications” section of our Action types page. In particular, you will need to look at the updated settlestatus value:
- On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).
- On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

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

You will need to contact our Support team, providing your 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.

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.

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

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

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

- 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:
#!/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
{ 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.
|
![]() |
errordata XPath: /error/data |
Alphanumeric (255) | Additional information to help troubleshoot the error. |
![]() |
errormessage XPath: /error/message |
Alphanumeric (255) | This is the corresponding message to the above code. |
![]() |
livestatus XPath: /live |
Numeric (1) |
|
![]() |
merchantname XPath: /merchant/merchantname |
Alphanumeric (255) | These are details associated with the account used to process the transaction.
To amend these fields, please contact our Support Team. |
![]() |
operatorname XPath: /merchant/operatorname |
Alphanumeric (255) | The value of this field contains the name of the user that processed the request. |
![]() |
paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | This value returned is “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:

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

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

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

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

3. Payment completion
Once the customer returns from the 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.

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

In the unlikely event that payment is still pending settlement after 7 days (settlestatus “10”), this will be scheduled for investigation and we will contact you with further information.
Before you begin testing, we recommend that you contact our Support team and request that rules are enabled on your account, which submit URL notifications to your system in the following scenarios:
- When a payment is authorised.
- When funds have been settled.
Configuring the authorisation notification
We recommend including at least the following fields in your authorisation notification:
- Acquirer Response Message (acquirerresponsemessage)
- Base Amount (baseamount) (e.g. £10.50 is “1050”)*
- Main Amount (mainamount) (e.g. £10.50 is “10.50”)*
- Billing Country (billingcountryiso2a)
- Currency (currencyiso3a)
- Error Code (errorcode)
- Live Status (livestatus)
- Order Reference (orderreference)
- Payment Type (paymenttypedescription)
- Request Type (requesttypedescription)
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
- Transaction Started Timestamp (transactionstartedtimestamp)
*Please choose your preferred format.
Configuring the settlement notification
We recommend including the following fields in your settlement notification:
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
Check the notification
You will need to check the contents of each notification received and respond accordingly by following the processes outlined in the “URL notifications” section of our Action types page. In particular, you will need to look at the updated settlestatus value:
- On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).
- On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

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

You will need to contact our Support team, providing your 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.

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.

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

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

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

- At a later time, giropay will contact Trust Payments with confirmation that funds have been settled.
- Trust Payments will submit a URL notification to the merchant’s system to confirm funds have settled.
- Merchant receives the notification and responds to inform Trust Payments the notification was received successfully.
1. Initiate the customer
When the customer chooses to pay with giropay, your system will need to perform an AUTH request and, if successful, redirect the customer’s browser to the URL returned in the response.
AUTH request
The example request below is for a giropay AUTH request:
#!/usr/bin/python import securetrading stconfig = securetrading.Config() stconfig.username = "[email protected]" stconfig.password = "Password1^" st = securetrading.Api(stconfig) auth = { "currencyiso3a": "EUR", "requesttypedescriptions": ["AUTH"], "accounttypedescription": "ECOM", "sitereference": "test_site12345", "baseamount": "1050", "paymenttypedescription": "GIROPAY", "successfulurlredirect": "https://yourwebsite.com", "errorurlredirect": "https://yourwebsite.com", "billingfirstname": "Joe", "billinglastname": "Bloggs", "billingcountryiso2a": "DE", "bic": "12345678" } strequest = securetrading.Request() strequest.update(auth) stresponse = st.process(strequest) #stresponse contains the transaction response
<?php if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) { throw new Exception('Composer autoloader file could not be found.'); } require_once($autoload); $configData = array( 'username' => '[email protected]', 'password' => 'Password1^' ); $requestData = array( 'currencyiso3a' => 'EUR', 'requesttypedescriptions' => array('AUTH'), 'accounttypedescription' => 'ECOM', 'sitereference' => 'test_site12345', 'baseamount' => '1050', 'paymenttypedescription' => 'GIROPAY', 'successfulurlredirect' => 'https://yourwebsite.com', 'errorurlredirect' => 'https://yourwebsite.com', 'billingfirstname' => 'Joe', 'billinglastname' => 'Bloggs', 'billingcountryiso2a' => 'DE', 'bic' => '12345678' ); $api = \Securetrading\api($configData); $response = $api->process($requestData); var_dump($response->toArray()); ?>
curl --user [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{ "alias": "[email protected]", "version": "1.00", "request": [{ "currencyiso3a": "EUR", "requesttypedescriptions": ["AUTH"], "accounttypedescription": "ECOM", "sitereference": "test_site12345", "baseamount": "1050", "paymenttypedescription": "GIROPAY", "successfulurlredirect": "https://www.example.com/success", "errorurlredirect": "https://www.example.com/error", "billingfirstname": "Joe", "billinglastname": "Bloggs", "billingcountryiso2a": "DE", "bic": "12345678" }]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"EUR","requesttypedescriptions":["AUTH"],"accounttypedescription":"ECOM","sitereference":"test_site12345","baseamount":"1050","paymenttypedescription":"GIROPAY","successfulurlredirect":"https:\/\/www.example.com\/success","errorurlredirect":"https:\/\/www.example.com\/error","billingfirstname":"Joe","billinglastname":"Bloggs","billingcountryiso2a":"DE","bic":"12345678"}]}
<?xml version='1.0' encoding='utf-8'?> <requestblock version="3.67"> <alias>[email protected]</alias> <request type="AUTH"> <merchant> <successfulurlredirect>https://www.example.com/success</successfulurlredirect> <errorurlredirect>https://www.example.com/error</errorurlredirect> </merchant> <billing> <name> <first>Joe</first> <last>Bloggs</last> </name> <country>DE</country> <bic>12345678</bic> <amount currencycode="EUR">1050</amount> <payment type="GIROPAY"/> </billing> <operation> <sitereference>test_site12345</sitereference> <accounttypedescription>ECOM</accounttypedescription> </operation> </request> </requestblock>
Replace <DOMAIN> with a supported domain. Click here for a full list.
Field specification
Field | Format | Description | |
![]() |
accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) | Only “ECOM” (e-commerce) is supported. |
![]() |
baseamount XPath: /billing/amount |
Numeric (13) | The amount of the transaction in base units, with no commas or decimal points, so €10 is submitted as 1000. This value must be greater than zero. (Max length may vary depending on your acquiring bank – Contact your bank for further info) |
![]() |
bic XPath: /billing/payment/bic |
Alphanumeric (8 or 11) | Valid BIC (Bank Identifier Code) of customer’s bank. |
![]() |
billingprefixname XPath: /billing/name/prefix |
Alphanumeric including symbols (25) |
The prefix of the customer’s billing name (e.g. Mr, Miss, Dr). |
![]() |
billingfirstname XPath: /billing/name/first |
Alphanumeric including symbols (127) |
The customer’s billing first name. |
![]() |
billingmiddlename XPath: /billing/name/middle |
Alphanumeric including symbols (127) |
The customer’s billing middle name(s). |
![]() |
billinglastname XPath: /billing/name/last |
Alphanumeric including symbols (127) |
The customer’s billing last name. |
![]() |
billingsuffixname XPath: /billing/name/suffix |
Alphanumeric including symbols (25) |
The suffix of the customer’s billing name (e.g. Bsc). |
![]() |
billingcountryiso2a XPath: /billing/country |
Alpha (2) | The country for the customer’s billing address. This will need to be in ISO2A format.
For a list of country codes supported by giropay, refer to the list found at the top of this page. |
![]() |
currencyiso3a XPath: /billing/amount/@currencycode |
Alpha (3) | The currency that the transaction will be processed in (in ISO3A format).
For a list of currency codes supported by giropay, refer to the list found at the top of this page. |
![]() |
errorurlredirect XPath: /merchant/errorurlredirect |
URL (2048) | The URL that the customer will be returned to following an error on the giropay-hosted pages. |
![]() |
orderreference XPath: /merchant/orderreference |
Alphanumeric including symbols (255) |
Your unique order reference that can be stored on the Trust Payments system. |
![]() |
paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | This value must be submitted as “GIROPAY”. |
![]() |
requesttypedescription XPath: /@type |
Alpha (20) | The value in the request must be “AUTH”. |
![]() |
sitereference XPath: /operation/sitereference |
Alphanumeric & underscore (50) |
The site reference relates to your individual account which you received on setup. If you do not know your site reference, please contact our Support team. |
![]() |
successfulurlredirect XPath: /merchant/successfulurlredirect |
URL (2048) | The URL that the customer will be returned to following a successful authorisation by giropay. |
AUTH response
{ u'requestreference': u'An3ug1kap', u'version': u'1.00', u'response': [{ u'transactionreference': u'23-86-113', u'merchantname': u'Test Merchant', u'paymenttypedescription': u'GIROPAY', u'settleduedate': u'2017-03-16', u'baseamount': u'1050', u'transactionstartedtimestamp': u'2017-03-16 16:25:08', u'errormessage': u'Ok', u'settlestatus': u'10', u'accounttypedescription': u'ECOM', u'errorcode': u'0', u'redirecturl': u'https://example.com', u'acquirertransactionreference': u'12', u'acquirersecret': u'q9gy5ppgdyd5fh60kfe2j0f26peu2xww', u'requesttypedescription': u'AUTH', u'acquirerresponsemessage': u'PENDING', u'operatorname': u'[email protected]', u'livestatus': u'0', u'currencyiso3a': u'EUR' }] }
array(3) { ["requestreference"] => string(9) "A0345jmuw" ["version"] => string(4) "1.00" ["response"] => array(1) { [0] => array(18) { ["transactionreference"] => string(9) "23-86-113" ["merchantname"] => string(4) "Test Merchant" ["paymenttypedescription"] => string(10) "GIROPAY" ["settleduedate"] => string(10) "2017-03-16" ["baseamount"] => string(4) "1050" ["transactionstartedtimestamp"] => string(19) "2017-03-16 16:25:08" ["errormessage"] => string(2) "Ok" ["settlestatus"] => string(2) "10" ["accounttypedescription"] => string(4) "ECOM" ["errorcode"] => string(1) "0" ["redirecturl"] => string(107) "https://example.com" ["acquirertransactionreference"] => string(2) "12" ["acquirersecret"] => string(32) "q9gy5ppgdyd5fh60kfe2j0f26peu2xww" ["requesttypedescription"] => string(4) "AUTH" ["acquirerresponsemessage"] => string(7) "PENDING" ["operatorname"] => string(11) "[email protected]" ["livestatus"] => string(1) "0" ["currencyiso3a"] => string(3) "EUR" } } }
{"requestreference":"W23-fjgvn3d9","version":"1.00","response":[{"transactionreference":"23-86-113","merchantname":"Test Merchant","paymenttypedescription":"GIROPAY","settleduedate":"2017-03-16","baseamount":"1050","transactionstartedtimestamp":"2017-03-16 16:25:08","errormessage":"Ok","settlestatus":"10","accounttypedescription":"ECOM","errorcode":"0","redirecturl":"https:\/\/example.com","acquirertransactionreference":"12","acquirersecret":"q9gy5ppgdyd5fh60kfe2j0f26peu2xww","requesttypedescription":"AUTH","acquirerresponsemessage":"PENDING","operatorname":"[email protected]","livestatus":"0","currencyiso3a":"EUR"}]}
<?xml version='1.0' encoding='utf-8'?> <responseblock version="3.67"> <requestreference>Xd4nk260v</requestreference> <response type="AUTH"> <merchant> <merchantname>Test Merchant</merchantname> <operatorname>[email protected]</operatorname> </merchant> <transactionreference>44-86-102</transactionreference> <timestamp>2017-03-16 17:34:16</timestamp> <acquirersecret>gfc8mx0p2fx26f1n5tpy6mtk21naap8c</acquirersecret> <operation> <accounttypedescription>ECOM</accounttypedescription> </operation> <settlement> <settleduedate>2017-03-16</settleduedate> <settlestatus>10</settlestatus> </settlement> <acquirerresponsemessage>PENDING</acquirerresponsemessage> <billing> <amount currencycode="EUR">1050</amount> <payment type="GIROPAY"/> </billing> <live>0</live> <other> <redirecturl>https://example.com</redirecturl> </other> <acquirertransactionreference>4</acquirertransactionreference> <error> <message>Ok</message> <code>0</code> </error> </response> <secrand>Z1W</secrand> </responseblock>
Field specification
Field | Format | Description | |
![]() |
accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) | The value returned is “ECOM”. |
![]() |
acquirerresponsemessage XPath: /acquirerresponsemessage |
Alphanumeric (255) | Used by your acquirer to indicate the outcome of the request. |
![]() |
acquirersecret XPath: /acquirersecret |
Alphanumeric (64) | Used by Trust Payments to verify the response from the acquirer. (Your system does not need to verify this) |
![]() |
acquirertransactionreference XPath: /acquirertransactionreference |
Alphanumeric including symbols (127) | Unique transaction reference assigned by giropay. |
![]() |
baseamount XPath: /billing/amount |
Numeric (13) | The amount of the transaction in base units, with no commas or decimal points, so €10 is returned as 1000. |
![]() |
currencyiso3a XPath: /billing/amount/@currencycode |
Alpha (3) | The currency that the transaction was processed in (in ISO3A format).
For a list of currency codes supported by giropay, refer to the list found at the top of this page. |
![]() |
errorcode XPath: /error/code |
Numeric (1-5) | The error code should be used to determine if the request was successful or not.
|
![]() |
errordata XPath: /error/data |
Alphanumeric (255) | Additional information to help troubleshoot the error. |
![]() |
errormessage XPath: /error/message |
Alphanumeric (255) | This is the corresponding message to the above code. |
![]() |
livestatus XPath: /live |
Numeric (1) |
|
![]() |
merchantname XPath: /merchant/merchantname |
Alphanumeric (255) | These are details associated with the account used to process the transaction.
To amend these fields, please contact our Support Team. |
![]() |
operatorname XPath: /merchant/operatorname |
Alphanumeric (255) | The value of this field contains the name of the user that processed the request. |
![]() |
paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | This value returned is “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:

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

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

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

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

3. Payment completion
Once the customer returns from the 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.


In the unlikely event that payment is still pending settlement after 7 days (settlestatus “10”), this will be scheduled for investigation and we will contact you with further information.
Before you begin testing, we recommend that you contact our Support team and request that rules are enabled on your account, which submit URL notifications to your system in the following scenarios:
- When a payment is authorised.
- When funds have been settled.
Configuring the authorisation notification
We recommend including at least the following fields in your authorisation notification:
- Acquirer Response Message (acquirerresponsemessage)
- Base Amount (baseamount) (e.g. £10.50 is “1050”)*
- Main Amount (mainamount) (e.g. £10.50 is “10.50”)*
- Billing Country (billingcountryiso2a)
- Currency (currencyiso3a)
- Error Code (errorcode)
- Live Status (livestatus)
- Order Reference (orderreference)
- Payment Type (paymenttypedescription)
- Request Type (requesttypedescription)
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
- Transaction Started Timestamp (transactionstartedtimestamp)
*Please choose your preferred format.
Configuring the settlement notification
We recommend including the following fields in your settlement notification:
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
Check the notification
You will need to check the contents of each notification received and respond accordingly by following the processes outlined in the “URL notifications” section of our Action types page. In particular, you will need to look at the updated settlestatus value:
- On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).
- On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

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

You will need to contact our Support team, providing your 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.

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.

Features
Supported customer countries![]() |
![]() |
![]() |
![]() |
![]() |
Supported.![]() |
![]() |
![]() After 90 days, the customer must seek refund directly with P24. |
![]() |
![]() |
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

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

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

- 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:
#!/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
{ 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.
|
![]() |
errordata XPath: /error/data |
Alphanumeric (255) | Additional information to help troubleshoot the error. |
![]() |
errormessage XPath: /error/message |
Alphanumeric (255) | This is the corresponding message to the above code. |
![]() |
livestatus XPath: /live |
Numeric (1) |
|
![]() |
merchantname XPath: /merchant/merchantname |
Alphanumeric (255) | These are details associated with the account used to process the transaction.
To amend these fields, please contact our Support Team. |
![]() |
operatorname XPath: /merchant/operatorname |
Alphanumeric (255) | The value of this field contains the name of the user that processed the request. |
![]() |
paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | This value returned is “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:

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

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

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

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

3. Payment completion
Once the customer returns from the 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.


In the unlikely event that payment is still pending settlement after 7 days (settlestatus “10”), this will be scheduled for investigation and we will contact you with further information.
Before you begin testing, we recommend that you contact our Support team and request that rules are enabled on your account, which submit URL notifications to your system in the following scenarios:
- When a payment is authorised.
- When funds have been settled.
Configuring the authorisation notification
We recommend including at least the following fields in your authorisation notification:
- Acquirer Response Message (acquirerresponsemessage)
- Base Amount (baseamount) (e.g. £10.50 is “1050”)*
- Main Amount (mainamount) (e.g. £10.50 is “10.50”)*
- Billing Country (billingcountryiso2a)
- Currency (currencyiso3a)
- Error Code (errorcode)
- Live Status (livestatus)
- Order Reference (orderreference)
- Payment Type (paymenttypedescription)
- Request Type (requesttypedescription)
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
- Transaction Started Timestamp (transactionstartedtimestamp)
*Please choose your preferred format.
Configuring the settlement notification
We recommend including the following fields in your settlement notification:
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
Check the notification
You will need to check the contents of each notification received and respond accordingly by following the processes outlined in the “URL notifications” section of our Action types page. In particular, you will need to look at the updated settlestatus value:
- On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).
- On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

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

You will need to contact our Support team, providing your 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.

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.

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

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

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

- 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:
#!/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
{ 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.
|
![]() |
errordata XPath: /error/data |
Alphanumeric (255) | Additional information to help troubleshoot the error. |
![]() |
errormessage XPath: /error/message |
Alphanumeric (255) | This is the corresponding message to the above code. |
![]() |
livestatus XPath: /live |
Numeric (1) |
|
![]() |
merchantname XPath: /merchant/merchantname |
Alphanumeric (255) | These are details associated with the account used to process the transaction.
To amend these fields, please contact our Support Team. |
![]() |
operatorname XPath: /merchant/operatorname |
Alphanumeric (255) | The value of this field contains the name of the user that processed the request. |
![]() |
paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | This value returned is “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:

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

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

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

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

3. Payment completion
Once the customer returns from the 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.


In the unlikely event that payment is still pending settlement after 7 days (settlestatus “10”), this will be scheduled for investigation and we will contact you with further information.
Before you begin testing, we recommend that you contact our Support team and request that rules are enabled on your account, which submit URL notifications to your system in the following scenarios:
- When a payment is authorised.
- When funds have been settled.
Configuring the authorisation notification
We recommend including at least the following fields in your authorisation notification:
- Acquirer Response Message (acquirerresponsemessage)
- Base Amount (baseamount) (e.g. £10.50 is “1050”)*
- Main Amount (mainamount) (e.g. £10.50 is “10.50”)*
- Billing Country (billingcountryiso2a)
- Currency (currencyiso3a)
- Error Code (errorcode)
- Live Status (livestatus)
- Order Reference (orderreference)
- Payment Type (paymenttypedescription)
- Request Type (requesttypedescription)
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
- Transaction Started Timestamp (transactionstartedtimestamp)
*Please choose your preferred format.
Configuring the settlement notification
We recommend including the following fields in your settlement notification:
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
Check the notification
You will need to check the contents of each notification received and respond accordingly by following the processes outlined in the “URL notifications” section of our Action types page. In particular, you will need to look at the updated settlestatus value:
- On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).
- On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

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

You will need to contact our Support team, providing your 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 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.

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.

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

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

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

- 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:
#!/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
{ 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.
|
![]() |
errordata XPath: /error/data |
Alphanumeric (255) | Additional information to help troubleshoot the error. |
![]() |
errormessage XPath: /error/message |
Alphanumeric (255) | This is the corresponding message to the above code. |
![]() |
livestatus XPath: /live |
Numeric (1) |
|
![]() |
merchantname XPath: /merchant/merchantname |
Alphanumeric (255) | These are details associated with the account used to process the transaction.
To amend these fields, please contact our Support Team. |
![]() |
operatorname XPath: /merchant/operatorname |
Alphanumeric (255) | The value of this field contains the name of the user that processed the request. |
![]() |
paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | This value returned is “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:

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

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

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

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

3. Payment completion
Once the customer returns from the 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.


In the unlikely event that payment is still pending settlement after 7 days (settlestatus “10”), this will be scheduled for investigation and we will contact you with further information.
Before you begin testing, we recommend that you contact our Support team and request that rules are enabled on your account, which submit URL notifications to your system in the following scenarios:
- When a payment is authorised.
- When funds have been settled.
Configuring the authorisation notification
We recommend including at least the following fields in your authorisation notification:
- Acquirer Response Message (acquirerresponsemessage)
- Base Amount (baseamount) (e.g. £10.50 is “1050”)*
- Main Amount (mainamount) (e.g. £10.50 is “10.50”)*
- Billing Country (billingcountryiso2a)
- Currency (currencyiso3a)
- Error Code (errorcode)
- Live Status (livestatus)
- Order Reference (orderreference)
- Payment Type (paymenttypedescription)
- Request Type (requesttypedescription)
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
- Transaction Started Timestamp (transactionstartedtimestamp)
*Please choose your preferred format.
Configuring the settlement notification
We recommend including the following fields in your settlement notification:
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
Check the notification
You will need to check the contents of each notification received and respond accordingly by following the processes outlined in the “URL notifications” section of our Action types page. In particular, you will need to look at the updated settlestatus value:
- On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).
- On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

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

You will need to contact our Support team, providing your 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.

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.
eps-Überweisung
The requests outlined in this document will need to be processed manually using our Webservices API.

Features
![]() |
![]() |
![]() |
![]() |
![]() |
Supported.![]() |
![]() |
![]() |
![]() |
![]() |
Configuration
To enable eps on your account, please get in touch with your account manager.
A test sandbox account will be provided, which you will need when testing your implementation.
Process overview

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

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

- At a later time, eps 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 eps, 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 eps AUTH request:
#!/usr/bin/python import securetrading stconfig = securetrading.Config() stconfig.username = "[email protected]" stconfig.password = "Password1^" st = securetrading.Api(stconfig) auth = { "currencyiso3a": "EUR", "requesttypedescription": "AUTH", "accounttypedescription": "ECOM", "sitereference": "test_site12345", "baseamount": "1050", "paymenttypedescription": "EPS", "successfulurlredirect": "https://yourwebsite.com", "errorurlredirect": "https://yourwebsite.com", "billingfirstname": "Joe", "billinglastname": "Bloggs", "billingcountryiso2a": "AT" } 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' => 'EPS', 'successfulurlredirect' => 'https://yourwebsite.com', 'errorurlredirect' => 'https://yourwebsite.com', 'billingfirstname' => 'Joe', 'billinglastname' => 'Bloggs', 'billingcountryiso2a' => 'AT' ); $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": "EPS", "successfulurlredirect": "https://www.example.com/success", "errorurlredirect": "https://www.example.com/error", "billingfirstname": "Joe", "billinglastname": "Bloggs", "billingcountryiso2a": "AT" }]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"EUR","requesttypedescription":"AUTH","accounttypedescription":"ECOM","sitereference":"test_site12345","baseamount":"1050","paymenttypedescription":"EPS","successfulurlredirect":"https:\/\/www.example.com\/success","errorurlredirect":"https:\/\/www.example.com\/error","billingfirstname":"Joe","billinglastname":"Bloggs","billingcountryiso2a":"AT"}]}
<?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>AT</country> <amount currencycode="EUR">1050</amount> <payment type="EPS"/> </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 eps, 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 eps, 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 eps-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 “EPS”. |
![]() |
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 eps. |
AUTH response
{ u'requestreference': u'An3ug1kap', u'version': u'1.00', u'response': [{ u'transactionreference': u'23-86-113', u'merchantname': u'Test Merchant', u'paymenttypedescription': u'EPS', 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) "EPS" ["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":"EPS","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="EPS"/> </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 eps. |
![]() |
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 eps, refer to the list found at the top of this page. |
![]() |
errorcode XPath: /error/code |
Numeric (1-5) | The error code should be used to determine if the request was successful or not.
|
![]() |
errordata XPath: /error/data |
Alphanumeric (255) | Additional information to help troubleshoot the error. |
![]() |
errormessage XPath: /error/message |
Alphanumeric (255) | This is the corresponding message to the above code. |
![]() |
livestatus XPath: /live |
Numeric (1) |
|
![]() |
merchantname XPath: /merchant/merchantname |
Alphanumeric (255) | These are details associated with the account used to process the transaction.
To amend these fields, please contact our Support Team. |
![]() |
operatorname XPath: /merchant/operatorname |
Alphanumeric (255) | The value of this field contains the name of the user that processed the request. |
![]() |
paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | This value returned is “EPS”. |
![]() |
redirecturl XPath: /other/redirecturl |
URL (255) | Redirect the customer’s browser to this URL to allow them to complete the payment on eps-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 eps payment:

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

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

The customer successfully completed the required steps on the eps-hosted pages.
Recommended actions: Display confirmation that the payment was successful.

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

3. Payment completion
Once the customer returns from the eps 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 eps.


In the unlikely event that payment is still pending settlement after 7 days (settlestatus “10”), this will be scheduled for investigation and we will contact you with further information.
Before you begin testing, we recommend that you contact our Support team and request that rules are enabled on your account, which submit URL notifications to your system in the following scenarios:
- When a payment is authorised.
- When funds have been settled.
Configuring the authorisation notification
We recommend including at least the following fields in your authorisation notification:
- Acquirer Response Message (acquirerresponsemessage)
- Base Amount (baseamount) (e.g. £10.50 is “1050”)*
- Main Amount (mainamount) (e.g. £10.50 is “10.50”)*
- Billing Country (billingcountryiso2a)
- Currency (currencyiso3a)
- Error Code (errorcode)
- Live Status (livestatus)
- Order Reference (orderreference)
- Payment Type (paymenttypedescription)
- Request Type (requesttypedescription)
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
- Transaction Started Timestamp (transactionstartedtimestamp)
*Please choose your preferred format.
Configuring the settlement notification
We recommend including the following fields in your settlement notification:
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
Check the notification
You will need to check the contents of each notification received and respond accordingly by following the processes outlined in the “URL notifications” section of our Action types page. In particular, you will need to look at the updated settlestatus value:
- On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).
- On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

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

You will need to contact our Support team, providing your eps test account details. We will then configure your test site reference to connect directly to the eps testing environment.
When performing test transactions, the redirect URL returned in the AUTH response will redirect your browser to the eps 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 eps, it is possible to pay the customer back by submitting a REFUND request.

Requirements
- You cannot refund a payment until the AUTH has been settled (settlestatus is “100”).
- You cannot refund a greater amount than was originally settled.
The REFUND request and response for eps payments follow the same field specification as outlined in our standard REFUND documentation. Click here for further information.
Bancontact
The requests outlined in this document will need to be processed manually using our Webservices API.

Features
![]() |
![]() |
![]() |
![]() |
![]() |
Supported.![]() |
![]() |
![]() |
![]() |
![]() |
Configuration
To enable Bancontact on your account, please get in touch with your account manager.
A test sandbox account will be provided, which you will need when testing your implementation.
Process overview

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

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

- At a later time, Bancontact 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 Bancontact, 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 Bancontact AUTH request:
#!/usr/bin/python import securetrading stconfig = securetrading.Config() stconfig.username = "[email protected]" stconfig.password = "Password1^" st = securetrading.Api(stconfig) auth = { "currencyiso3a": "EUR", "requesttypedescription": "AUTH", "accounttypedescription": "ECOM", "sitereference": "test_site12345", "baseamount": "1050", "paymenttypedescription": "BANCONTACT", "successfulurlredirect": "https://yourwebsite.com", "errorurlredirect": "https://yourwebsite.com", "billingfirstname": "Joe", "billinglastname": "Bloggs", "billingcountryiso2a": "BE" } 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' => 'BANCONTACT', 'successfulurlredirect' => 'https://yourwebsite.com', 'errorurlredirect' => 'https://yourwebsite.com', 'billingfirstname' => 'Joe', 'billinglastname' => 'Bloggs', 'billingcountryiso2a' => 'BE' ); $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": "BANCONTACT", "successfulurlredirect": "https://www.example.com/success", "errorurlredirect": "https://www.example.com/error", "billingfirstname": "Joe", "billinglastname": "Bloggs", "billingcountryiso2a": "BE" }]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"EUR","requesttypedescription":"AUTH","accounttypedescription":"ECOM","sitereference":"test_site12345","baseamount":"1050","paymenttypedescription":"BANCONTACT","successfulurlredirect":"https:\/\/www.example.com\/success","errorurlredirect":"https:\/\/www.example.com\/error","billingfirstname":"Joe","billinglastname":"Bloggs","billingcountryiso2a":"BE"}]}
<?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>BE</country> <amount currencycode="EUR">1050</amount> <payment type="BANCONTACT"/> </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 Bancontact, 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 Bancontact, 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 Bancontact-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 “BANCONTACT”. |
![]() |
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 Bancontact. |
AUTH response
{ u'requestreference': u'An3ug1kap', u'version': u'1.00', u'response': [{ u'transactionreference': u'23-86-113', u'merchantname': u'Test Merchant', u'paymenttypedescription': u'BANCONTACT', 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) "BANCONTACT" ["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":"BANCONTACT","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="BANCONTACT"/> </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 Bancontact. |
![]() |
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 Bancontact, refer to the list found at the top of this page. |
![]() |
errorcode XPath: /error/code |
Numeric (1-5) | The error code should be used to determine if the request was successful or not.
|
![]() |
errordata XPath: /error/data |
Alphanumeric (255) | Additional information to help troubleshoot the error. |
![]() |
errormessage XPath: /error/message |
Alphanumeric (255) | This is the corresponding message to the above code. |
![]() |
livestatus XPath: /live |
Numeric (1) |
|
![]() |
merchantname XPath: /merchant/merchantname |
Alphanumeric (255) | These are details associated with the account used to process the transaction.
To amend these fields, please contact our Support Team. |
![]() |
operatorname XPath: /merchant/operatorname |
Alphanumeric (255) | The value of this field contains the name of the user that processed the request. |
![]() |
paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | This value returned is “BANCONTACT”. |
![]() |
redirecturl XPath: /other/redirecturl |
URL (255) | Redirect the customer’s browser to this URL to allow them to complete the payment on Bancontact’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 Bancontact payment:

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

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

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

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

3. Payment completion
Once the customer returns from the Bancontact 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 Bancontact.


In the unlikely event that payment is still pending settlement after 7 days (settlestatus “10”), this will be scheduled for investigation and we will contact you with further information.
Before you begin testing, we recommend that you contact our Support team and request that rules are enabled on your account, which submit URL notifications to your system in the following scenarios:
- When a payment is authorised.
- When funds have been settled.
Configuring the authorisation notification
We recommend including at least the following fields in your authorisation notification:
- Acquirer Response Message (acquirerresponsemessage)
- Base Amount (baseamount) (e.g. £10.50 is “1050”)*
- Main Amount (mainamount) (e.g. £10.50 is “10.50”)*
- Billing Country (billingcountryiso2a)
- Currency (currencyiso3a)
- Error Code (errorcode)
- Live Status (livestatus)
- Order Reference (orderreference)
- Payment Type (paymenttypedescription)
- Request Type (requesttypedescription)
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
- Transaction Started Timestamp (transactionstartedtimestamp)
*Please choose your preferred format.
Configuring the settlement notification
We recommend including the following fields in your settlement notification:
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
Check the notification
You will need to check the contents of each notification received and respond accordingly by following the processes outlined in the “URL notifications” section of our Action types page. In particular, you will need to look at the updated settlestatus value:
- On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (suspended and cancelled, respectively).
- On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

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

You will need to contact our Support team, providing your Bancontact test account details. We will then configure your test site reference to connect directly to the Bancontact testing environment.
When performing test transactions, the redirect URL returned in the AUTH response will redirect your browser to the Bancontact 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 Bancontact, it is possible to pay the customer back by submitting a REFUND request.

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