Payment Page
Before you start integrating this any of these flows, make sure, you have read the following Chapters:
The Saferpay Payment Page Interface is intended for a simplified and universal integration of the payment process by using the PaymentPage payment form. 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.
Please consider our license-chapter, to determine, if tall the desired features are available for you.
(click to enlarge)
- 1.
- Initializes the Payment and generates the RedirectUrl for the Payment Page.
- 2.Redirect to the RedirectUrl
- 3.Return to ReturnUrl. The ReturnUrl is defined in step 1.
- 4.
- Gathers all the information about the payment, like the overall outcome, LiabilityShift through 3D Secure and more, using the Token, gathered in step 1.
- 5.Depending on the outcome of step 4 you may
- 6.Transaction is finished!
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.
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).
Selecting the correct currency is very important. A currency mismatch can lead to payment methods not being displayed, even if you use pre-selection. The Payment Page will always try to make a payment possible through other means (if available), leading to the following behaior:
- If multiple or no
PaymentMethodvalues have been submitted, Saferpay will only display the methods, that can be processed with said currency, if available. This is also the case, if none of the values can pe processed (Be it due to unavailability, or non-sensicality, e.g. misspelling). - 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 with a "NO_CONTRACT" error message.
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.
If a certain transaction needs SCA (please refer to the PSD2 chapter), you can force SCA, by setting Authentication.ThreeDsChallenge to "FORCE".
Via the ReturnUrl, 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 ReturnUrl. When a ReturnUrl is called, Saferpay returns the appended parameter, thus enabling identification of the customer/transaction. The ReturnUrl is ALWAYS called through the clients Browser.
We strongly advice against using a session cookie for identifying the customer upon redirect to this URL!
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 ReturnUrl, in order to identify the returning customer!
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 circumvent cases, where the redirect to the ReturnUrl 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!
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.
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.
The Card Verification Value (CVC) is mandatory, when using the PaymentPage, except for card brand Maestro, which offers cards with and without CVC.
This value is mandatory, when displayed, however you may hide the input field. See the CardForm container with the PaymentPage Initialize request.
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.
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.
Inside the PaymentPage Initialize Response, the following parameters are important.
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!
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!
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)!
Once the transaction is complete, the card holder is taken back to the shop, to the ReturnUrl. 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, where the outcome of the payment itself will be determined.
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!
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:
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.
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.
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!
If the payment has been rejected, the Payment Page Assert will throw an http status != 200 and a JSON error-message, containing more information about the rejection.
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!
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.
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:
The address is then returned with the Payment Page Assert response, inside the
Payer.Billing|DeliveryAddress container.Depending on the use-case and|or payment method, the following things are important to consider, when building an express-checkout with Saferpay:
- 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 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 insidePaymentMeans.PayPalcontainer, as this can differ from the e-mail, that is saved within the address!
Last modified 1mo ago