Secure Card Data

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.

• A Saferpay Business contract
• A License for Secure Card Data, which is usually included in Saferpay Business
• An active terminal with active contracts for the desired brands

• Visa
• MasterCard
• Maestro international
• V PAY
• American Express
• MyOne
• Diners Club
• Bonus Card
• Discover
• JCB
• PostFinance card (Please read the information over here!)
• SEPA ELV (Not via the Transaction Interface!)
• Bancontact
• Credit Cards over Masterpass
• Twint (Please read the information over here!)

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.

{ 
"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]"
 }
}

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="
  }
}

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"
 }
}

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!

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.

In order to open up the hosted Card Entry Form, you first need to execute the Alias Insert Request.

• ReturnUrls: For security, Saferpay returns no data to return addresses of the shop. 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.

• 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]"
    },

• 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.

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.

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 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. The check-function is only available with the standalone registration, since the other options do said authorization!
2. The check-function does not check the solvency of the account. Only an authorization does!
3. The check-function is only available for VISA, Mastercard and American Express, over SIX Payment Services/Worldline, B+S Payone and Elavon Acquiring contracts/processing!

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.

{
  "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]"
  }
}

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"
    ]
}

Click here for a live demo!

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).

Please proceed with the information, mentioned over here!

Similar to the Payment Page, the Secure PayGate API also has the ability to save a card, during a transaction. Simply add the RegisterAlias container to your request, as described in the request specification:

{
  "Payment": {
    "Amount": {
      "Value": "404",
      "CurrencyCode": "CHF"
    },
    "OrderId": "094c2a7ce1374f7ca184591f123b154d",
    "Options": {
      "PreAuth": true
    }
  },
  "ExpirationDate": "2020-04-23",
  "Payer": {
    "LanguageCode": "de",
    "BillingAddress": {
      "FirstName": "John",
      "LastName": "Doe",
      "Company": "Worldline",
      "Gender": "MALE",
      "Street": "Mustergasse 123",
      "Zip": "8008",
      "City": "Zurich",
      "CountryCode": "CH",
      "Email": "payer@provider.com"
    }
  },
  "BillingAddressForm": {
    "Display": true
  },
  "RegisterAlias": {
    "IdGenerator": "RANDOM"
  }
}

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.

   Important: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!

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 (See Secure Card Data). This is also known as Card on File (CoF).
• If not, then you can use AuthorizeDirect to authorize the card directly. Do not forget to also Capture/Finalize the transaction.