Secure Card Data - Tokenization
Before you start integrating this any of these flows, make sure, you have read the following Chapters:
Payment Methods for your desired payment method
Saferpay Secure Card Data, or SCD for short, is a service for saving sensitive payment data in the certified Saferpay data center. By using SCD, the payment data is separated from the merchant's application and thus no longer comes into contact with it. Secure Card Data is suitable for shop systems, call center solutions, inventory management, ERP and CRM systems in which stored payment data is required for future/deferred or recurring/instalments payments.
It provides the Hosted Register Form (HRF) to simply store/tokenize payment data regardless of any actual payment been made. For example, if a customer wants to add different payment options to his account so that he/she can decide which one to use during the actual payment process. Please read chapter Iframe Integration and CSS for examples of the different payment forms.
Secure Card Data is, what most people know as card data "Tokenization".
However, since the word "Token" can mean a lot of different things, even in the context of Saferpay, we will continue to refer to this procedure as "Secure Card Data" and the card token will be referred to as "(Card) Alias", in order to avoid confusion.
Requirements
A License for Secure Card Data, which is usually included in Saferpay Business
An active terminal with active contracts for the desired brands
Supported Payment Methods
Visa
MasterCard
Maestro international
V PAY
American Express
Diners Club
Discover
JCB
PostFinance card (Please read the information over here!)
SEPA ELV (Not via the Transaction Interface!)
Bancontact
Twint (Please read the information over here!)
Please note, that the saved card details, all belong to one and only one CustomerId and thus Saferpay account! They can not be shared between accounts! If you have multiple Saferpay accounts/CustomerIds, you must register each card multiple times, for each account/CustomerId!
Secure Card Data and the Payment Page
The Payment Page can be used to save a credit card, after a successful authorization! In order to request an Alias with the PaymentPage Assert, you first need to set the RegisterAlias container within the PaymentPage Initialize request.
The Payment Page CAN NOT be used to authorize/use the obtained card-alias! It can only register cards! Please refer to the last part of this chapter, How to use the obtained data, on how to actually use it!
The IdGenerator has multiple options to choose from. All of them will be explained later in this chapter!
Once a successful transaction has been made through the PaymentPage, you will get the result of the registration with the PaymentPage Assert(See "RegistrationResult"!).
Secure Card Data and the Transaction Interface
The Transaction Interface can also be used to obtain a Secure Card Data alias also after a successful authorization! The submitted Data is the same, as with the PaymentPage Initialize request, but with the Transaction Interface you MUST NOT USE the RegisterAlias container within Transaction Initialize. Here the registration actually is made with the Transaction Authorize request (Remember: A registration is only made, if the Authorization is successful!), thus you have to submit the necessary data here.
The IdGenerator has multiple options to choose from. All of them will be explained later in this chapter!
Once a successful transaction has been made, you will get the result of the registration with the Transaction Authorize response (See "RegistrationResult"!).
The obtained alias can then be used for subsequent payments, which will be explained later in this chapter.
Standalone Secure Card Data registration
All methods so far described, how a Secure Card Data alias can be obtained within the authorization process. If you just want to register the card, but not authorize it, you need to use the Secure Alias Store.
The process itself is very similar to the one using the Transaction Interface. The Secure Alias Store has its own hosted card registration form, which can also be integrated within an iFrame and styled via CSS and it can also be combined with the Saferpay Fields, if you want a more stylish and flexible option. However, it will not execute a transaction, just simply save a card, so you may use it for later.
Don't like the style of the Hosted Form? Try our CSS-Styling feature!
General overview
Registration Initialization: The payer arrives at the checkout and the shop initializes the registration of the card details.
The shop calls Alias Insert, which initializes the registration and generates the RedirectUrl and Token.
Capturing of the card details/Redirect: Open the RedirectUrl inside an HTML-iFrame, or a Lightbox. Depending on whether you have provided the card details (Through an Alias or a Saferpay Fields Token), the following may happen:
The Redirecturl opens a card form, to capture the card data.
The form is skipped, so the next step may be executed.
3D Secure and Online Check: Depending on whether, or not the check function is used, Saferpay will perform a so called Card Verification Check and also -in case of ONLINE_STRONG- 3D Secure. If the check function is not used, this entire step is skipped.
Redirect back to shop: The payer is redirected back to your shop. his is also the point, where Saferpay calls the
NotificationUrl.Gathering of the registration result: the shop gathers the regiostration result.
Alias Assertinsert gathers the registration result and also the result of the card-check, as well as the 3D Secure authentication outcome, if applied -see step 3-, using the token, gathered in step #1.
Validation: The shop validates the response gathered in step #5 and displays the overall outcome to the payer.
Saferpay recommends to at least perform an ONLINE check, as not performing one can lead to penalty-fees imposed by the card-schemes.
An ONLINE_STRONG check however is highly recommended, in order to reduce the fraud risk, especially, if the gathered card alias is used for recurring payments.
IMPORTANT: If you are in scope of PSD2 , then you must perform an ONLINE_STRONG check. If not the issuing bank will possibly refuse the account verification for missing authentication.
Here are a few hints and tips about the options that are available for the merchant:
ReturnUrl.Url
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!
Notification.NotifyUrl
This URL is meant to notify the merchant server via a server-to-server callback, should the registration be a success, or failure. The notification URL circumvents 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 URL 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 ReturnUrl 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.
Saferpay Fields
When using the Saferpay Fields, you will be provided with a Saferpay Fields token. This token then has to be submitted through alias/insert, within the PaymentMeans.SaferpayFields container in order to save the card. If used, the RedirectUrl directly links to the next step e.g. 3D Secure, thus skipping the Hosted Card Register Form. Think of it as a different method to capture the card data for initialization.
Alias Insert Response
Token
The Token is mandatory for further steps within the payment process and must therefore be cached. Preferably, it should be linked to the parameters attached to the ReturnUrls. It can thus be easily reassigned.
RedirectUrl
Unlike with the Payment Page, this URL is not used for a redirect. Instead, it is embedded in an HTML Iframe. Within this, a form hosted by Saferpay is displayed. This form is also called the Hosted Entry Form. It can be used to capture sensitive card details in a PCI-compliant manner. You can find out more about the Iframe integration in this chapter.
Return to the Shop
Once the registration is completed, the card holder – depending on the outcome – is taken back to one of the ReturnUrls of the shop. Here, the GET parameters can be read and the Token can be assigned to the registration.
Handling multiple redirects
Under certain circumstances, it may happen, that the redirect to the shop happens more, than once. This can be due to the payer trying to go back, by clicking on the back-button in their browser, or accessing their history etc.
These events cannot be handled by Saferpay, as the user sometimes has already left our sites and can have serious impact on your shop, if you do not handle them correctly.
For instance, it could trigger the transaction processing twice, which could lead to errors. These errors could then lead to the shop assuming, that the transaction has failed, even though it did not.
Once you have received a definite response from the Alias Assert Insert, you must mark the transaction as "Processed" on your end, so that the shop does not process the transaction twice.
Handling Notifications
This is also the point, when Saferpay calls the NotificationUrl.
Handling the notification correctly is very important, though it does present some challenges.
Ideally, both -the notification and the redirect- happen roughly at the same time, though note, that they are asynchronous, meaning, that one can happen before, or after the other, depending on the connection. So relying on them being called in a specific order is not recommended.
There are multiple ways of tackling this, though we highly recommend to not use one over the other. They are both intended to work in tandem to and suppliment each other. In any case, both should be able to trigger the next processing steps.
The following things may be done to handle this correctly:
Let both trigger the next steps. With the Payment Page, the transaction already happened, so if you call the Assert with both, they'll both report the same basic result; success, or failure. However, the details may cause some issues, for example if the redirect already triggered the assert. Thusly, you have to make sure, that your shop can handle two events for the same registration and that they do not interfere with each other in any negative way.
Write both calls into a queue on your end, so you can process them after each other, instead of in parallel. This way, you can make sure, that the process only runs once on your end. Make sure, that you mark your process as completed at the end of the first event, so that if the second call comes up in the queue, the system sees, that this transaction has already been processed successfully and then skips this item.
Obtaining the alias
With the Token, the can be obtained, by submitting it through the Alias AssertInsert request. The response will give you the alias itself and further information about the card itself, like the masked card number, or the holder name.
The check-Function
The Check function is used, to check, if an entered card connects to a valid account, or not, before the authorization itself. However, you need to consider the following restrictions:
The check-function is only available with the standalone registration, since the other options do said authorization!
The check-function does not check the solvency of the account. Only an authorization does!
The check-function is only available for VISA, Mastercard, over SIX Payment Services/Worldline, as well as Visa & Mastercard for B+S Payone and Elavon Acquiring contracts/processing!
American Express may also be available, but is limited for certain processors. Please ask your account manager for further information on whether the card-check is available for American Express, or not.
Request
In order, to let a card get checked, you need to set the Check-container within the initial registration-request. You need to make sure, to provide a valid terminal Id, with activated acquiring-contracts for VISA, MasterCard and/or American Express.
The Type parameter has two values:
ONLINE will only do a basic account-verification, checking the validity of the bank account!
ONLINE_STRONG is very important for PSD2 MITs. This option will do an account verification and also execute Strong Consumer Authentication (SCA), via a 3D Secure challenge!
Response
If the check was successful, you will get a successful registration-response with the Assert Insert. Should you have done a Check, or a Check with SCA (see above), you may also recieve a result message on the check and the outcome of the SCA.
If the chek failed, the registration too will fail and you'll get an error-response:
Try it out!
Using your own HTML-Form
Saferpay also offers the possibility to use a custom HTML-form for merchants with the required PCI certification. Aside that, it uses the basic Standalone registration flow (see above).
As mentioned before: DO NOT PROCEED, if you do not have the necessary PCI certification (SAQ-A EP) in order to use your own form! SIX Payment Services/Worldline will not take any kind of responsibility in case of a noncompliance! We highly urge you, to use the Saferpay Hosted Fields instead!
Please proceed with the information, mentioned over here!
The Id-Generator
The ID-generator is used to choose what kind of alias you want to recieve. Right now, there are three options to choose from:
1 - MANUAL: Manual should be used, if you want to define an alias yourself. This is helpful, if the alias has to be in a specific format, like all numeric, or 16 characters long etc. You then have to supply the Id you want to use within the Id parameter.
Make sure, that all your aliases are unique! Saferpay will only authorize the first card to come up inside the database, if there are multiple records with the same alias!
2 - RANDOM: This value will generate a random alpha numerical hash, as your alias-id, for you! No need to supply an id yourself!
3 - RANDOM_UNIQUE: Similar to RANDOM, it will create a random alpha numerical hash for you. The difference is, that it will check, if the card number (PAN) provided has already saved inside your alias store. If so, Saferpay will return the already existing alias, making sure, that no PAN can be saved twice or more!
How to use the obtained data
The obtained alias can be used in two basic ways, which boil down to one important question:
Do you want to do a 3D Secure transaction?
If yes, then you have to use the Transaction Interface. This is also known as Card on File (CoF).
If not, then you can use AuthorizeDirect to authorize the card directly and basically do Recurring Payments, using an alias. Remember, that you also have to Capture the transaction, when executed.
For merchants inside the European Economic Area (EEA), the latter option also requires compliance for PSD2! Please follow this guide carefully, as non-compliance will lead to a severely increased rate of rejections/declines!
Bancontact and Maestro only support the former!
Every alias is bound to the CustomerId you provide with the registration-request. All Terminals bound to that id can use the aliases, but not other CustomerIds! There is no way to share the aliases between different CustomerIds!
If an Alias is created during a transaction (See Payment Page and Transaction Interface above!), the used Payment Method is saved and will be used for further transactions. For example, if a Bancontact/Maestro dual-branded card is used and the card-holder selects Bancontact, Saferpay will use the card as a Bancontact card, even if Maestro is activated on that terminal.
Furthermore, if the alias is then used on a terminalId, that does not have Bancontact activated, the transaction won't be possible, even if Maestro is activated! The alias must be processed via the brand, the user first payed with!
Last updated
