Saferpay Documentation
English
Ask or search…
K

Secure Card Data - Tokenization

Before you start integrating this any of these flows, make sure, you have read the following Chapters:
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

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!
{
"RequestHeader": {
"SpecVersion": "[CURRENT-SPEC-VERSION]",
"CustomerId": "[your customer id]",
"RequestId": "[unique request id]",
"RetryIndicator": 0
},
"TerminalId": "[your terminal id]",
"Payment": {
"Amount": {
"Value": "100",
"CurrencyCode": "CHF"
}
},
"RegisterAlias": {
"IdGenerator": "RANDOM"
},
"Payer": {
"LanguageCode": "en"
},
"ReturnUrls": {
"Success": "[your shop payment success url]",
"Fail": "[your shop payment fail url]"
},
"Styling": {
"CssUrl": "[your shop css url]"
}
}
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"!).
{
"ResponseHeader": {
"SpecVersion": "[CURRENT-SPEC-VERSION]",
"RequestId": "[your request id]"
},
"Transaction": {
"Type": "PAYMENT",
"Status": "AUTHORIZED",
"Id": "MUOGAWA9pKr6rAv5dUKIbAjrCGYA",
"Date": "2017-06-18T09:19:27.078Z",
"Amount": {
"Value": "100",
"CurrencyCode": "CHF"
},
"AcquirerName": "AcquirerName",
"AcquirerReference": "Reference"
},
"RegistrationResult": {
"Success": true,
"Alias": {
"Id": "alias35nfd9mkzfw0x57iwx",
"Lifetime": 1000
}
},
"PaymentMeans": {
"Brand": {
"PaymentMethod": "SAFERPAYTEST",
"Name": "SaferpayTestCard"
},
"DisplayText": "9123 45xx xxxx 1234",
"Card": {
"MaskedNumber": "912345xxxxxx1234",
"ExpYear": 2021,
"ExpMonth": 9,
"HolderName": "Max Mustermann",
"CountryCode": "CH"
}
},
"Payer": {
"IpAddress": "1.2.3.4",
"IpLocation": "CH"
},
"ThreeDs": {
"Authenticated": true,
"LiabilityShift": true,
"Xid": "ARkvCgk5Y1t/BDFFXkUPGX9DUgs=",
"VerificationValue": "AAABBIIFmAAAAAAAAAAAAAAAAAA="
}
}

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.
{
"RequestHeader": {
"SpecVersion": "[CURRENT-SPEC-VERSION]",
"CustomerId": "[your customer id]",
"RequestId": "[unique request id]",
"RetryIndicator": 0
},
"Token": "sdu5ymxx210y2dz1ggig2ey0o",
"RegisterAlias": {
"IdGenerator": "RANDOM"
}
}
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"!).
{
"ResponseHeader": {
"SpecVersion": "[CURRENT-SPEC-VERSION]",
"RequestId": "[your request id]"
},
"Transaction": {
"Type": "PAYMENT",
"Status": "AUTHORIZED",
"Id": "MUOGAWA9pKr6rAv5dUKIbAjrCGYA",
"Date": "2017-06-18T09:19:27.078Z",
"Amount": {
"Value": "100",
"CurrencyCode": "CHF"
},
"AcquirerName": "AcquirerName",
"AcquirerReference": "Reference"
},
"RegistrationResult": {
"Success": true,
"Alias": {
"Id": "alias35nfd9mkzfw0x57iwx",
"Lifetime": 1000
}
},
"PaymentMeans": {
"Brand": {
"PaymentMethod": "SAFERPAYTEST",
"Name": "SaferpayTestCard"
},
"DisplayText": "9123 45xx xxxx 1234",
"Card": {
"MaskedNumber": "912345xxxxxx1234",
"ExpYear": 2021,
"ExpMonth": 9,
"HolderName": "Max Mustermann",
"CountryCode": "CH"
}
},
"Payer": {
"IpAddress": "1.2.3.4",
"IpLocation": "CH"
},
"ThreeDs": {
"Authenticated": true,
"LiabilityShift": true,
"Xid": "ARkvCgk5Y1t/BDFFXkUPGX9DUgs=",
"VerificationValue": "AAABBIIFmAAAAAAAAAAAAAAAAAA="
}
}
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

  1. 1.
    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.
  2. 2.
    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.
  3. 3.
    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.
  4. 4.
    Redirect back to shop: The payer is redirected back to your shop. his is also the point, where Saferpay calls the NotificationUrl.
  5. 5.
    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.
  6. 6.
    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.
"PaymentMeans": {
"SaferpayFields": {
"Token": "[YOUR TOKEN]"
},

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.

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:
  1. 1.
    The check-function is only available with the standalone registration, since the other options do said authorization!
  2. 2.
    The check-function does not check the solvency of the account. Only an authorization does!
  3. 3.
    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!
    1. 1.
      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!
{
"RequestHeader": {
"SpecVersion": "[CURRENT-SPEC-VERSION]",
"CustomerId": "[your customer id]",
"RequestId": "[your request id]",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"OsInfo": "Windows Server 2013"
}
},
"RegisterAlias": {
"IdGenerator": "RANDOM_UNIQUE"
},
"Type": "CARD",
"LanguageCode": "en",
"ReturnUrls": {
"Success": "[your shop payment success url]",
"Fail": "[your shop payment fail url]"
},
"Check": {
"Type": "ONLINE",
"TerminalId": "[your terminal id]"
}
}

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.
{
"ResponseHeader": {
"SpecVersion": "[CURRENT-SPEC-VERSION]",
"RequestId": "55"
},
"Alias": {
"Id": "alias35nfd9mkzfw0x57iwx",
"Lifetime": 1000
},
"PaymentMeans": {
"Brand": {
"PaymentMethod": "VISA",
"Name": "VISA Saferpay Test"
},
"DisplayText": "9123 45xx xxxx 1234",
"Card": {
"MaskedNumber": "912345xxxxxx1234",
"ExpYear": 2015,
"ExpMonth": 9,
"HolderName": "Max Mustermann",
"CountryCode": "CH"
}
},
"CheckResult":{
"Result": "OK_AUTHENTICATED",
"Message": "Online card check was successful.",
"Authentication":{
"Result": "OK",
"Message": "Card holder authentication with 3DSv2 successful.",
"Xid": "1ef5b3db-3b97-47df-8272-320d0bd18ab5"
}
}
}
If the chek failed, the registration too will fail and you'll get an error-response:
{
"ResponseHeader": {
"SpecVersion": "[CURRENT-SPEC-VERSION]",
"RequestId": "55"
},
"Behavior": "ABORT",
"ErrorName": "CARD_CHECK_FAILED",
"ErrorMessage": "Online card check failed",
"ErrorDetail": [
"online card check failed"
]
}

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?
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!