Payment Page

Test Login Productive Login Blog More...
Search…
Payment Page
Before you start integrating this any of these flows, make sure, you have read the following Chapters:
​Introduction​
​Data Security and PCI DSS​
​3D Secure​
​Payment Methods for your desired payment method
​Capture and Daily Closing​
​PSD2​
​Licenses and Interfaces​
The Saferpay Payment Page Interface is intended for a simplified and universal integration of the payment process by using the PaymentPage payment form. The Saferpay Payment Page can be used both with a Saferpay eCommerce license and with a Saferpay business license. All Saferpay supported payment methods can be processes with the Payment Page Interface; credit cards and third-party payment methods like PayPal, iDEAL, SOFORT/Klarna and more. Once integrated, more payment methods can be added at any time without major adjustments.
The PaymentPage can be either used to offer the payer the option to select a desired payment method or can be defined to jump directly to one specific payment method with a preselection option. Please read chapter Iframe Integration and CSS for examples of the different payment forms. It can also be used in combination with the Secure Card Data to store/tokonize payment data during the payment process.
General overview
(click to enlarge)
1.​Payment Page Initialize​
Initializes the Payment and generates the RedirectUrl for the Payment Page.
2.Redirect to the RedirectUrl
3.Return to ReturnUrl depending on the outcome of the transaction. The ReturnUrls are defined in step 1.
4.​Payment Page Assert​
Gathers all the information about the payment, like LiabilityShift through 3D Secure and more, using the Token, gathered in step 1.
5.Depending on the outcome of step 4 you may
​Capture/Finalize the Transaction​
​Cancel/Abort the Transaction​
6.Transaction is finished!
1 - PaymentPage Initialize Request
The process begins with the PaymentPage Initialize request. With this request, you forward all data necessary for the payment to Saferpay. These include the customer number (CustomerId), the terminal number (Terminal Id), the currency (CurrencyCode), the amount (Value), the internal reference no. of the merchant system (OrderId), and the return addresses (ReturnUrls) to which the customer will return after leaving the PaymentPage.
Information on the Use and Significance of the available Parameters
Payment Method (Pre-)Selection
Do you want to limit the displayed payment method, or skip the selection-screen alltogether? If so, follow this information further down.
Strong Consumer Authentication (SCA)
If a certain transaction needs SCA (please refer to the PSD2 chapter), you can force SCA, by setting Authentication.ThreeDsChallenge to "FORCE".
ReturnUrls
Via the ReturnUrls, the customer is returned to the shop after the transaction. For security reasons, Saferpay returns no data to return addresses. The identification of the payment or the returning customers is up to the merchant. We recommend using your own parameters. These can be attached via HTTP GET to the ReturnUrls. When a ReturnUrl is called, Saferpay returns the appended parameter, thus enabling identification of the customer/transaction. The ReturnUrls are ALWAYS called through the clients Browser.
We strongly advice against using a session cookie for identifying the customer upon redirect to these URLs!
Sessions can be lost during the redirect process, especially, if Saferpay has to redirect to external sites (e.g. PayPal, Sofort etc.).
Also certain browsers -specifically known is Safari- can prove a problem here, due to them discarding 3rd party cookies, especially inside iFrames. Browser behavior can also change with an update, introducing problems, without you being prepared.
Saferpay advices you to use GET-parameters, attached to the ReturnUrls, in order to identify the returning customer! 
If you intent on using Dynamic Currency Conversion (DCC), it is highly recommended to set the Abort Url, even though optional!
Notification.SuccessNotifyUrl & Notification.FailNotifyUrl
These URLs are meant to notify the merchant server via a server-to-server callback, should the transaction be a success, or failure. The notification URLs are meant to circumvent cases, where the redirect to one of the ReturnUrls has failed, due to the payer losing connection, or closing the browser preemptively, so the merchant server may continue with the next steps.
The notification happens via http-GET and does not carry any data (like the token), except parameters, that have been added to the URL by the merchant-system. It is intended, that the token (see initialize response) is saved by the merchat system and then linked to these parameters -e.g. a sessionId-, so the merchant system can identify the correct token and perform the authorization this way. Otherwise the notification callback would be an empty request.
It should be noted, that, in a best case scenario, the notification takes place in addition to the respective ReturnUrl, due to its redundant nature. Make sure, that your system can handle both calls, so it doesn't interpret them as two separate processes. Moreover, Saferpay expects the merchant server to answer the call with a HTTP status code 200(OK). 
If no (e.g. a Timeout after 10 seconds), or a different status code (e.g. http 500) is received, Saferpay will re-attempt the notification up to five times more, for a total of six times, to ensure, that the previous error is not caused by a temporal problem. 
The timespan between each try is increased, after each failure, to a maximum of 1 day. That ensures, that also a longer lasting issue can be circumvented.
The usage of the Notification URLs is strongly recommended! Only leave it out, if your system cannot recieve external requests!
The notification also does not return any data to the merchants application, except your own parameters (See ReturnUrls above!) via GET!
Any type of authentication (e.g. basic authentication, or certificates) towards your system, is currently not supported!
 If you need the outgoing IP-addresses and/or ports, you can find them here.
Payment.OrderId
This optinal parameter is important to keep track of all your transactions in later processes. This ID will be forwarded, so it will show up inside the Saferpay Backoffice (As the Reference number!) and on your reconciliation-files. This will help associate all the transactions for your accounting-department.
Gathering of the payers address
If you want, you can also capture your customers address either through Saferpay, or, if possible, through the payment method itsel. Click here for more information.
Card Verification Value
The Card Verification Value (CVC) is mandatory, when using the PaymentPage, except for card brand Maestro, which offers cards with and without CVC.
Card Holder
This value is mandatory, when displayed, however you may hide the input field. See the CardForm container with the PaymentPage Initialize request.
RegisterAlias
Via the RegisterAlias container, card details from a payment can be stored safely and in conformity with PCI. See the Secure Card Data chapter for more information.
A card will be registered only after a successful authorisation. Although the Payment Page Interface can be used to register (store) payment data, it is NOT possible to use it for future payments. Registered card data can only be used with the Transaction Interface.
Language
The language can be changed, by setting the Payer.LanguageCode parameter with the PaymentPage Initialize request. A list of all supported languages and their code, can be found with the request specification.
Note, that the Payment Page will also try to detect the language automatically, using the payers browser-client, so there may be no need for you to set this parameter.
However, if you set it, it will overrule the auto-detection.
PaymentPage Initialize Response
Inside the PaymentPage Initialize Response, the following parameters are important.
Token
The Token refers to the values temporarily stored regarding the Saferpay transaction and is mandatory during subsequent processing of the transaction (for more information, see e.g. PaymentPage Assert). The Token should be coupled to the http-GET parameters that were previously attached to the ReturnUrls and NotifyUrl for identification and then stored inside a database, for further actions to come!
RedirectUrl
The RedirectURL provides the address via which the buyer is redirected to the PaymentPage. This can be done automatically via calling up the Iframe or by embedding the URL in an HTML link that must be clicked on by the buyer.
The RedirectUrl can only be called one time, due to security restraints. Please make sure, that the RedirectUrl cannot be called twice. The second call will automatically trigger the FailUrl or AbortUrl, if the latter is defined!
2 - Redirect and Transaction
Redirect the buyer to the RedirectUrl from the PaymentPage Initialize response, using your desired method. The transaction will be fully processed by the PaymentPage. The Payment Page handles all steps automatically, including 3D Secure and DCC. No additional steps are necessary on the merchant website.
Saferpay does not recommend the usage of a Client-Side Session (Cookie), for customer identification, due to restrains emposed by browser manufacturers! Those can cause the Session getting lost, during the payment process, thus causing the shop to not being able to identify the returning user. We recommend using GET-parameters, as described above (See parameter-description for Initialize)!
3 - Return to the Shop
Once the transaction is complete, the card holder – depending on the outcome – is taken back to the shop, to one of the ReturnUrls. Here, the GET parameters can be read and the Token can be assigned to the transaction. With the Token, the payment can be continued to the next step.
4 - PaymentPage Assert
With the PaymentPage Assert, the results of a transaction are requested. The returned data may be stored on the merchant side.
The Assert does NOT do the transaction itself. The PaymentPage will do that automatically for you. The Assert only calls for the result! So, if you call the Assert, the transaction already happened!
The Payment Page Assert can be called up to 36 hours, after the Payment Page Initialize!
Based on the data obtained, it is to be decided whether or not a transaction is to be further processed. The following data is interesting in this regard:
Transaction.Id
The transaction identifier returned in the container Transaction with Id is a unique identifier for a transaction. The value is obligatory for further processing steps (Transaction Capture or Transaction Cancel) and should therefore be saved.
ThreeDs
This container provides information about whether or notliability shift through 3D Secure is available or not. It is up to merchant whether or not he wants to accept transactions without liability shift. Evaluation of the parameter provides the opportunity for merchants to incorporate appropriate rules here.
Accepting transaction without LiabilityShift happens at the merchants own risk.
Transaction.Status
As already described here, this status states whether or not a transaction has to be finalized via Capture. If this status is not CAPTURED, the capture must be executed in order to finalise the transaction.
You can also call the Payment Page Assert, if the Fail-or AbortUrl has been called. It will then return a JSON-Object, containing information about the failed transaction, like the reason (If available!) and error-code from the processor itself! Note, that the http-status will be != 200, indicating a failed transaction!
Under certain circumstances a PaymentPage Session can be valid for about 1 hour -other sessions, like external redirections to 3D Secure and 3rd party providers can add up to this!-, but a normal session does not take longer, than 20 minutes!
5 - Capture or Cancel
Subsequently, the transaction will be finalised via Capture or aborted via Cancel.For this, the transaction identifier Id is required. Please refer to the notes in the payment methods chapter, to check, if and when a Capture is necessary, and whether a Cancel can still be executed. Alternatively, you can also check the Transaction.Status parameter, within the PaymentPage Assert Response. If the status is AUTHORIZED a Capture needs to be performed. If the status is CAPTURED you do not need to finalize the payment.
Once these steps are complete, the transaction is completed.
Keep in mind that you cannot cancel a transaction, once it is captured! At that point, a refund has to be executed, if available -please check the respective payment methods chapter-! So please make sure, that you really want to finalize the transaction and initiate the money transfer, to avoid confusion with your customers!
Try it out!
​Click here for a live demo!​
Express Checkout
Ordering as a guest and express checkouts are very common these days, as they offer a way to quickly order goods, without the need of registering yet another account for another shop. Therefore, certain payment methods offer possibilities to gather the address saved on their end and pass it through to the merchant.
Saferpay offers options to implement such checkouts, so the payer can go through it, without much interaction.
Controlling the Address Source
The important parameter for such cases is Billing|DeliveryAddressForm.AddressSource, within the Payment Page Initialize request. As the name suggests, it controls the source of the payers address and it has three values:
NONE: None is the default and simply results in no address being returned.
SAFERPAY: The address is captured on Saferpay side. This option will display the corresponding address form on the Saferpay Payment Page.
If you want to, you can also (partially) send the address, by submitting the respective address within the Payer.Billing|DeliveryAddress container. Saferpay will then display the submitted data inside the respective form.
You can also make some fields in the address form mandatory, by submitting the corresponding values inside the Billing|DeliveryAddressForm.MandatoryFields array, thus ensuring, that these values will be filled and returned.
PREFER_PAYMENTMETHOD: This option will return the address stored by the payment method, if available. If the payment method doesn't support this feature, the Payment Page will fall back to the SAFERPAY-option and display an address form on the payment page itself.
Currently supported Payment Methods:
​PayPal​
The address is then returned with the Payment Page Assert response, inside the Payer.Billing|DeliveryAddress container.
(Pre-)Selection of the payment method
Depending on the use-case and payment method, it may also be desireable to also control the used payment method(s) and the Payment Page does offer a way to control the displayed payment method(s), by submitting their control-values within the PaymentMethods array, through the  Payment Page Initialize request.
The Payment Page will behave in three basic ways, depending on the number of values submitted and also the currency:
If multiple supported values are submitted, the payment page will display all selected payment methods, if available and hide those, that are not selected.
If only one value is submitted, Saferpay will skip the payment selection and continue with the next step, by either displaying the card-entry, or address form (as described above). In case of 3rd party payment methods, that require a redirect (e.g.) PayPal, Saferpay will immediately perform said redirect, skipping the Payment Page alltogether, if the display of the address-form is skipped (see above).
If one, or more values are submitted, that aren't activated, or if the desired currency for one is not available, the Payment Page will react a follows:
If multiple values have been submitted, Saferpay will only display the methods, that can be processed with said currency.
If one value was submitted, Saferpay will ignore the value and display all available alternatives, if possible.
If all this fails and not a single alternative can be found, the  Payment Page Initialize request will fail.
It is therefore important, that you check the availability of said payment method and currency. You can do so inside the Saferpay Backoffice under Settings => Terminals.
Final things to consider
Depending on the use-case and|or payment method, the following things are important to consider, when building an express-checkout with Saferpay:
General
As of now, Saferpay does not support the alteration of the payment amount after the address has been returned. This may be important in cases, where the Delivery Address dictates the final amount (e.g. due to shipping costs). The amount must be set before the user is redirected to Saferpay!
Even though the name may suggest it, the Transaction AdjustAmount request does not work in this instance!
PayPal
PayPal defines the word "Express Checkout" a bit differently. Specifically, they offer a function to alter the amount, after the address has been gathered. As said above, this is currently not supported!
Saferpay does return the PayPal account e-mail and Id, however it is not returned with the Payer.Billing|DeliveryAddress, but instead inside PaymentMeans.PayPal container, as this can differ from the e-mail, that is saved within the address!
Integration Guide - Previous
Licences and ways of integration
Payment Page checklist
Last modified 2mo ago
Copy link
On this page
General overview
1 - PaymentPage Initialize Request
Information on the Use and Significance of the available Parameters
PaymentPage Initialize Response
2 - Redirect and Transaction
3 - Return to the Shop
4 - PaymentPage Assert
5 - Capture or Cancel
Try it out!
Express Checkout
Controlling the Address Source
(Pre-)Selection of the payment method
Final things to consider