Sofort is a real-time bank transfer method that operates in several European countries. When selecting Sofort, customers will be prompted to select their bank and then to sign in to their online banking account. After reviewing the pre-filled payment details, they can agree to the payment, before being redirected back to your website. Once completed, you will receive confirmation via a URL notification.
Supported customer countries | AT, BE, CH, DE, ES, GB, IT, NL, PL |
Supported currencies | EUR, GBP |
Refunds |
Full and partial refunds permitted for up to 365 days. |
Chargebacks |
Payments are not subject to chargebacks. |
Zero-authorisation |
Not supported. |
Recurring payments |
Not 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
-
Initiate the customer
- Customer agrees to a payment using Sofort on the merchant’s website.
- Merchant submits AUTH request to initiate the session, including the successfulurlredirect and errorurlredirect.
- Merchant receives AUTH response, including redirecturl.
-
Redirect to Sofort
- Merchant redirects the customer’s browser to the redirecturl.
- Customer follows instructions on Sofort's hosted pages to authorise the payment.
- If successful, the browser is redirected to the successfulurlredirect, a page hosted by the merchant that displays confirmation of payment.
- If there has been a problem with the payment, the browser is redirected to the errorurlredirect, a page hosted by the merchant that displays an error to the customer.
-
Payment completion
- At a later time, Sofort will contact Trust Payments with confirmation that funds have been settled.
- Trust Payments will submit a URL notification to the merchant’s system to confirm funds have settled.
- Merchant receives the notification and responds to inform Trust Payments the notification was received successfully.
1. Initiate the customer
When the customer chooses to pay with Sofort, your system will need to perform an AUTH request and, if successful, redirect the customer’s browser to the URL returned in the response.
AUTH request
The example request below is for a Sofort AUTH request:
#!/usr/bin/python
import securetrading
stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
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' => 'webservices@example.com',
'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 webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "webservices@example.com",
"version": "1.00",
"request": [{
"currencyiso3a": "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",
"bankid": "12345"
}]
}'
{
"alias":"webservices@example.com",
"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",
"bankid": "12345"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</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) | |
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. | |
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. | |
billingprefixname XPath: /billing/name/prefix |
Alphanumeric including symbols (25) |
The prefix of the customer’s billing name (e.g. Mr, Miss, Dr). At least one of the billing name fields is required. |
|
billingfirstname XPath: /billing/name/first |
Alphanumeric including symbols (127) |
The customer’s billing first name. At least one of the billing name fields is required. |
|
billingmiddlename XPath: /billing/name/middle |
Alphanumeric including symbols (127) |
The customer’s billing middle name(s). At least one of the billing name fields is required. |
|
billinglastname XPath: /billing/name/last |
Alphanumeric including symbols (127) |
The customer’s billing last name. At least one of the billing name fields is required. |
|
billingsuffixname XPath: /billing/name/suffix |
Alphanumeric including symbols (25) |
The suffix of the customer’s billing name (e.g. Bsc). At least one of the billing name fields is required. |
|
orderreference XPath: /merchant/orderreference |
Alphanumeric including symbols (25)
Recommended length 25 characters or less (exact length dependent on acquiring bank). Failure to adhere to this requirement may result in the text being truncated in the transaction. |
Your unique order reference that can be stored on the Trust Payments system. |
AUTH response
{
u'requestreference': u'An3ug1kap',
u'version': u'1.00',
u'responses': [{
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'webservices@example.com',
u'livestatus': u'0',
u'currencyiso3a': u'EUR'
}]
}
array(3) {
["requestreference"] => string(9) "A0345jmuw"
["version"] => string(4) "1.00"
["responses"] => 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) "webservices@example.com"
["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":"webservices@example.com",
"livestatus":"0",
"currencyiso3a":"EUR"
}]
}
<responseblock version="3.67">
<requestreference>Xd4nk260v</requestreference>
<response type="AUTH">
<merchant>
<merchantname>Test Merchant</merchantname>
<operatorname>webservices@example.com</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”. | |
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.
|
|
errormessage XPath: /error/message |
Alphanumeric (255) | This is the corresponding message to the above code. | |
livestatus XPath: /live |
Numeric (1) |
|
|
operatorname XPath: /merchant/operatorname |
Alphanumeric (255) | The value of this field contains the name of the user that processed the request. | |
paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | This value returned is “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. | |
acquirerresponsemessage XPath: /acquirerresponsemessage |
Alphanumeric (255) |
Used by your acquirer to indicate the outcome of the request. This will vary depending on your acquiring bank. Please contact your bank for further information. |
|
errordata XPath: /error/data |
Alphanumeric (255) |
Additional information to help troubleshoot the error. Only returned if there has been an error. |
|
merchantname XPath: /merchant/merchantname |
Alphanumeric (255) |
These are details associated with the account used to process the transaction. To amend these fields, please contact our Support Team. Depends on your account configuration. |
Handling the response
The settlestatus returned in the AUTH response is used to determine the status of the Sofort payment:
If the settlestatus is “10”, the payment is pending settlement
- The funds have not yet been settled into your bank account.
- The next step is to redirect the customer’s browser to the redirecturl to complete the payment.
Funds will not be settled into your account until the customer is redirected to Sofort's pages, in order to complete the payment. Read on for further information.
- When there is an update to the settle status of the AUTH, you will receive a URL notification to inform you that the settlestatus has been updated to either “3” or “100”.
- Further information on the notifications can be found below.
If the settlestatus is “3”, the payment has been cancelled
- The payment has been declined, or has encountered an error.
- To learn more about why the payment was unsuccessful, you will need to look at the errorcode. e.g. “70000” indicates that the payment was declined. Click here for a full list of error codes.
In addition to the above, we also recommend performing additional checks following payment.
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.
Do not display the redirecturl within an iframe. This will prevent the content from being rendered correctly, and can ultimately prevent the payment from being completed successfully.
At a later time, the customer will be redirected back to either the successfulurlredirect or the errorurlredirect provided in the AUTH request.
If the customer is redirected to the successfulurlredirect:
The customer successfully completed the required steps on Sofort's pages.
Recommended actions: Display confirmation that the payment was successful.
If the customer is redirected to the errorurlredirect:
The customer encountered a problem that has prevented them from completing the payment.
Recommended actions: Inform the customer that there was a problem with the payment, displaying sufficient transaction details for the customer to query the payment attempt.
When testing, you will be displayed the sandbox as provided by Sofort. To complete a test transaction, you will need to follow the instructions displayed on screen. Please contact your account manager for test credentials to enter while on the sandbox.
3. Payment completion
Once the customer returns from the Sofort hosted page to either the successfulurlredirect or errorurlredirect hosted on your site, you will need to display either a confirmation or error message respectively.
Please check for any URL redirect rules that may be enabled in the MyST Rule manager on your site reference(s), as these may conflict and take precedence over the successfulurlredirect and errorurlredirect fields submitted in the AUTH request.
Once a payment has been authorised, funds will be settled at a later time, as determined by Sofort.
The settlement process for Sofort differs from the standard process followed with card-based payment methods.
The settlement notification may not be sent immediately after processing the AUTH
In the unlikely event that payment is still pending settlement after 7 days (settlestatus “10”), this will be scheduled for investigation and we will contact you with further information.
Before you begin testing, we recommend that you contact our Support Team and request that rules are enabled on your account, which submit URL notifications to your system in the following scenarios:
- When a payment is authorised.
- When funds have been settled.
Configuring the authorisation notification
We recommend including at least the following fields in your authorisation notification:
- Acquirer Response Message (acquirerresponsemessage)
- Base Amount (baseamount) (e.g. £10.50 is “1050”)*
- Main Amount (mainamount) (e.g. £10.50 is “10.50”)*
- Billing Country (billingcountryiso2a)
- Currency (currencyiso3a)
- Error Code (errorcode)
- Live Status (livestatus)
- Order Reference (orderreference)
- Payment Type (paymenttypedescription)
- Request Type (requesttypedescription)
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
- Transaction Started Timestamp (transactionstartedtimestamp)
*Please choose your preferred format.
Configuring the settlement notification
We recommend including the following fields in your settlement notification:
- Settle Status (settlestatus)
- Site Reference (sitereference)
- Transaction Reference (transactionreference)
Check the notification
You will need to check the contents of each notification received and respond accordingly by following the processes outlined in our URL notifications documentation. In particular, you will need to look at the 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.
Cancelled transactions (settlestatus “3”) may be settled at a later time. In situations where the customer has completed the steps required to fulfil the payment, the settlestatus is updated to “100” to indicate the funds have been transferred to your account.
If you have contacted the Support Team to configure settlement notifications (as described above), you will be notified when this occurs.
Testing
You will need to test your solution before you can begin processing live payments. Test transactions are processed through your test Site Reference.
Requirements
You will need to contact our Support Team, providing your 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.
Refunds
After processing a payment with Sofort, it is possible to pay the customer back by submitting a REFUND request.
Refunds for Sofort are settled immediately (settlestatus “100”).
Requirements
- You cannot refund a payment until the AUTH has been settled (settlestatus is “100”).
- You cannot refund a greater amount than was originally settled.
The REFUND request and response for Sofort payments follow the same field specification as outlined in our standard REFUND documentation. Click here for further information.