Secure Card Data. Specification. Version SIX Payment Services

Transcription

1 Secure Card Data Specification Version SIX Payment Services

2 Table of Contents 1 Introduction Data Security and PCI DSS Summary Requirements Supported Payment Means Format Information Saferpay Secure Card Data Overview Process Description Registration Link Parameters Registration Form Parameters Own parameters in the registration form Registration Response Parameters Update of registered Data Update request Update response Combination with other Saferpay Modules Authorization Interface and Secure Card Data Payment Page and Secure Card Data Merchant Plug-In and Secure Card Data Batch Processing and Secure Card Data Backoffice und Secure Card Data Saferpay Test Account Examples Important Notice Creating the registration link C# with the.net LIB Commandline calls with the Java LIB Usage of the https Interface Registration Form Evaluation of the Registration Response C# mit der.net LIB Commandline calls with the Java LIB Usage of the https Interface Contact Saferpay Integration Team Saferpay Support Team Saferpay Secure Card Data page 2

3 1 Introduction Saferpay Secure Card Data, in the following also called SCD, is a service to store sensitive payment means information in Saferpay s certified data center. By using SCD the payment means data is kept separated from the merchant application and does not get in contact with the merchants system. Secure Card Data is convenient for shop systems, call center solutions, merchandise management- ERP- and CRM-systems. The present document describes the integration of Secure Card Data in existing systems. 1.1 Data Security and PCI DSS The credit card organizations have created the security program PCI DSS (Payment Card Industry Data Security Standard) to prevent fraud and misuse of credit cards. If a system processes, transports or stores credit card numbers, it is subject to these special PCI DSS regulations. These requirements can involve considerable additional costs for the merchant. Besides the implementation of the organizational and technical requirements, an accredited certification centre must be assigned at regular intervals to certify the systems compliance with the PCI DSS regulations. By shifting the processing and storage of the credit card numbers to Saferpay the PCI regulations do no longer apply to the merchant. Using Saferpay Secure Card Data the merchant system does not get in contact with the credit card numbers and instead uses uncritical replacement values. In the database of the Secure Card Data, the expiration date of the card is stored in addition to the credit card number, the storage of the card s validity in the merchant system is therefore optional and not mandatory. 1.2 Summary Each credit card number respectively banking account information is in a first step transmitted to the SCD-database. The merchant application for this purpose generates an own form for the input of the payment means data. After entering the data the form content is sent directly to Saferpay where the card number and the expiry date respectively the banking account information is stored in the SCDdatabase and associated to a reference value pointing to the stored values. After that the reference number as well as all the data submitted with the form, excepted the card number or the banking account information, is returned to the merchant application by browser redirect. From then on the merchant system can use the reference number for immediate and future authorization requests. 1.3 Requirements Saferpay SCD can be addressed via the Saferpay Client Library (LIB) for Java or.net as well as via the Saferpay https Interface (HI). Saferpay SCD is a service that has to be separately configured and activated for the merchant. A corresponding Saferpay contract and service agreement is assumed. SCD can be used with the following modules: Saferpay Payment Page (PP) Saferpay Authorization Interface (AI) Saferpay Batch Processing (BP) Saferpay Merchant Plug-In (MPI) Saferpay Backoffice (BO) Saferpay Secure Card Data page 3

4 1.4 Supported Payment Means The Saferpay Secure Card Data currently allows the processing of transactions for the following payment means: Visa MasterCard Maestro international V PAY American Express Diners Club J.C.B. Union Card Laser Card ELV electronic direct debit (Germany only) 1.5 Format Information The following abbreviations for format information are used in this document: a Letters (a - z, A - Z) n numeric characters (0-9) an alphanumeric characters (a - z, A - Z, 0-9) s Special characters (- : ; / \ < >. =) ans alphanumeric and special characters Saferpay Secure Card Data page 4

5 2 Saferpay Secure Card Data 2.1 Overview The following chart shows the process flow of a successful insert in the Secure Card Data database Process Description The customer keeps his credit card data or his banking account information ready to transmit it to the merchant. The merchant application generates the registration link with the parameter CARDREFID. CARDREFID must be a unique value or the value new. If new is transmitted the value of the reference number will be generated by saferpay. The merchant application opens a form with the registration link as destination address. The customer or call center agent enters the payment means data. By clicking on the Submit button the form data is send to saferpay via the registration link. The credit card number and expiry date respectively the banking account information is stored in the Saferpay Secure Card Data Database and associated to the CARDREFID. Saferpay returns the registration response to the merchant application via browser redirect. Saferpay Secure Card Data page 5

6 8 9 The merchant application checks the received registration response for possible manipulation with VerifyPayConfirm. The result of the registration is displayed to the customer or callcenter agent. 2.3 Registration Link Parameters In order to register the payment means data a registration link is needed. The following table lists the parameters available for the generation of the registration link with CreatePayInit. If not specified as Optional the parameters are mandatory. Parameter Format Description ACCOUNTID ns[..15] The Saferpay account number of the merchant for this registration. e.g for the Saferpay Test Account. SUCCESSLINK ans[..1024] URL to which the customer is to be forwarded to via browser redirect in case of successful registration. Saferpay appends the registration response (InsertCardResponse) by GET to this URL FAILLINK ans[..1024] URL to which the customer is to be forwarded to via browser redirect in case of failed registration. Saferpay appends the registration response (InsertCardResponse) including the failure details by GET to this URL. CARDREFID ans[..40] Replacement value for the credit card number and expiry date respectively bank account information (only german direct debit). The replacement value can be generated by the E-Commerce application or Saferpay (new). Value: Unique replacement value or new * LIFETIME n[..4] Optional Number of days that a registered card is kept in the database. The time of the last use is the reference point for calculating the expiration date. If not specified the standard value is 1000 days. After Lifetime expiration the stored information is deleted from the database. LANGID a[2] Optional Language code according to ISO Language in which the error messages are returned to the merchant system. Possible values are en (default), de, fr and it. REDIRECTMESSAGE ans[..30] Optional This text message is displayed to the cardholder before the browser redirect. If the automatic redirect does not work, the SUCCESSLINK respectively FAILLINK can be called by clicking on this message. *Note: In order to enable the use of CARDREFID= new a numeric start value for the account has to be set by Saferpay. For this concern please contact integration@saferpay.com. Saferpay Secure Card Data page 6

7 2.4 Registration Form Parameters The payment means data has to be submitted via a web form. The web form must contain the following parameters and fields: Parameter Format Beschreibung form method a[4] In order to comply to the PCI regulations the use of the post method is mandatory for the form data transmission. form action ans[..1024] Must contain the registration URL. input type a[6] Has to be "submit" to send the form data. sfpcardnumber n[..19] Fieldname for the card number. sfpcardexpirymonth n[..2] Fieldname for the expiry month date of the credit card. Allowed values are: 1 to 12 or 01 to 12. sfpcardexpiryyear n[..4] Fieldname for the expiry year date of the credit card. Allowed values are: 2 or 4 digit year dates. sfpcardblz n[8] fieldname for the bank code number. The bank code is always 8 digits long. sfpcardkonto n[..10] fieldname for the account number. The bank account number can be up to 10 digits long Own parameters in the registration form Besides the mandatory parameters needed by Secure Card Data the form may also contain own parameters which are submitted to Saferpay. These values will be returned to the merchant application without change attached as GET-parameters to the SUCCESSLINK respectively FAILLINK. Buffering these information on the merchant system is therefore not necessary. Even if not needed for the SCD registration it is recommended to gather the Card Verification Code (Security Code on the backside of the card) within the registration form since for all initial payments this information it mandatory for the later authorization request. Attention: Please note that the credit card verification number may only be stored temporarily within the context of the authorization request. A permanent storage is, even for PCI DSS certified authorities, not allowed. The CVC is not needed for recurring payments. Saferpay Secure Card Data page 7

8 2.5 Registration Response Parameters The registration response is returned as InsertCardResponse message. The following table lists the possible response parameters. Parameter Format Beschreibung MSGTYPE a[..30] Always contains the value InsertCardResponse. KEYID ans[..40] Identifier of the key used to generate the signature. RESULT n..[..4] Contains the response code of the registration response: 0 Request processed successfully Internal error (see DESCRIPTION) Request could not be processed successfully Cardtype not available on this terminal Parameter with invalid content or format CARDREFID not found (only with authorization) Missing parameter in registration request CARDREFID already exists in database No permission for SCD use. SCDRESULT n..[..4] Identical to RESULT. DESCRIPTION ans[..50] Contains a short description of the error. SCDDESCRIPTION ans[..50] Identical to DESCRIPTION. ACCOUNTID ns[..15] The Saferpay account number of the merchant for this registration, e.g.: " " for the Saferpay Testaccount. CARDREFID ans[..40] Replacement value for the credit card number and expiry date respectively bank account information. CARDMASK ans[19] Contains the masked card number. CARDBIN n[6] 6-digit bank identification number (BIN), e.g.: identifying the issuing bank. Only available for credit cards, Availability depends on license and processor. CARDTYPE n[5] card type ID, numerical value: German Direct debit American Express MasterCard J.C.B Visa Saferpay Test Card CARDBRAND ans[..50] Brand name of the card, e.g. Visa or MasterCard. CCCOUNTRY a[2] Optional* 2-digit country code of the card origin. Is only returned if the Saferpay Risk Management service is active and if the country of origin can be determined. Example: DE = Germany, CH = Switzerland, AT = Austria LIFETIME n[..4] Number of days that the registered data will stay stored in the database. EXPIRYMONTH n[2] The month of card validity. Format: MM EXPIRYYEAR n[2] The year of card validity. Format: YY *Only available if Saferpay Risk Management is activated Saferpay Secure Card Data page 8

9 2.6 Update of registered Data The Expiry Date as well as the value of Lifetime of already registered payment means can be updated via the merchant application. The card number or the account information itself can not be changed. To update the Expiry Date or the Lifetime of a registered payment mean a request must be sent with the UpdateCard function. The parameters EXP and LIFETIME are both optional but at least one of them must be stated within the request Update request The following table lists the available parameters for the UpdateCard message. Parameter Format Beschreibung MSGTYPE a[..30] Always contains the value UpdateCard. ACCOUNTID ns[..15] The Saferpay account number of the merchant for this registration, e.g.: " " for the Saferpay Test Account. CARDREFID ans[..40] Replacement value for the credit card number and expiry date respectively bank account information. EXP n[4] Optional, if LIFETIME is stated Expiry Date as stated on the card. The format is MMYY, e.g. "1215" for 12/2015. LIFETIME n[..4] Optional, if EXP is stated Number of days that the registered data is to be kept in the database Update response Saferpay returns a message as UpdateCardResponse Parameter Format Beschreibung MSGTYPE a[..30] Always contains the value "UpdateCardResponse". MESSAGE ans[..30] Contains a textual update response. ACCOUNTID ns[..15] The Saferpay account number of the merchant for this registration. e.g.: " " for the Saferpay Testaccount. CARDREFID ans[..40] Replacement value for the credit card number and expiry date respectively bank account information (only German Direct Debit). EXPIRYMONTH n[2] The month of card validity. Format: MM EXPIRYYEAR n[2] The year of card validity. Format: YY LIFETIME n[..4] Number of days that the registered data is to be kept in the database. RESULT n..[..4] Contains the response code of the update response. Saferpay Secure Card Data page 9

10 3 Combination with other Saferpay Modules As soon as a payment means has been registered and safely stored within the Secure Card Data database it can be accessed by all Saferpay services via the reference value CARDREFID. A detailed description of the possible uses described below can be found in the specification or manual of the concerned Saferpay modules. 3.1 Authorization Interface and Secure Card Data Within the authorization request instead of submitting the card number or banking account information as plain text via the parameters PAN or TRACK2 the reference value is submitted with the parameter CARDREFID. The submission of the expiry date with EXP is then optional. If EXP is used anyhow the value transmitted with EXP is taken instead of the expiry date stored within the SCD. 3.2 Payment Page and Secure Card Data Using the Saferpay Payment Page card data as well as banking account information can be stored in the SCD database quasi on the fly. After every successful payment the CARDREFID is returned to the web-shop within the authorization response and is then available to the merchant application for subsequent payments. 3.3 Merchant Plug-In and Secure Card Data During the VerifyEnrollmentRequest the reference value with CARDREFID is transmitted instead of the card number with PAN. The submission of the expiry date with EXP is then optional. If EXP is used anyhow the value transmitted with EXP is taken instead of the expiry date stored within the SCD. 3.4 Batch Processing and Secure Card Data Instead of submitting the card number or bank account information as plain text the reference value of an already registered payment mean can be used. The reference value therefore has to be preceded by the text CARDREFID:. 3.5 Backoffice und Secure Card Data Once activated for the Saferpay Account the Secure Card Data service is also available via the Saferpay Backoffice under My Saferpay allowing the manual registration of Card data and banking account information as well as the search for already registered reference values. Saferpay Secure Card Data page 10

11 4 Saferpay Test Account During Integration phase the use of the Saferpay test account is recommended. ACCOUNTID Login e Password XAjc3Kna Card Number Description Saferpay Testcard enrolled. Saferpay Testcard for 3D-Secure processing Saferpay Testcard not enrolled. Normal Saferpay Testcard without 3D-Secure processing Saferpay Testcard unable to enrolled. Saferpay Testcard for SSL processing only. The test account is used by multiple developers. Therefore you ll possibly find transactions and payments on the test account that have been initiated and processed by others. The test account only supports Saferpay Test Cards. Other card types are not available. The Saferpay Test Cards do not have fixed card verification numbers (CVC /CVV2) or expiry dates. Both can be freely chosen. The CVC must be a numeric 2- or 4 digt value and the expiry must be a valid date in the future. A part from this the payment with the Saferpay Test Cards is identical to transactions with real cards on life accounts. Saferpay Secure Card Data page 11

12 5 Examples 5.1 Important Notice Please note that own values should always be transmitted html encoded (or as html entity or as Unicode) in order to ensure that possible special characters are correctly processed. 5.2 Creating the registration link C# with the.net LIB MessageFactory mf = new MessageFactory(); mf.open(""); // Saferpay configuration path, e.g. "c:\\programs\\saferpay\\client" mo_payinit = mf.createpayinit(); string m_accountid = " "; string m_refid = "ABCDEF "; string m_faillink = " string m_successlink = " mo_payinit.setattribute("accountid", m_accountid); mo_payinit.setattribute("cardrefid", m_refid); mo_payinit.setattribute("successlink", m_successlink); mo_payinit.setattribute("faillink", m_faillink); string regurl = mo_payinit.getposturl(); string data = mo_payinit.getpostdata(); string signature = mo_payinit.getpostsignature(); Registration form: <html><body> <form method="post" action="<% = regurl %>"> <input type="hidden" name="data" value="<%= data %>"> <input type="hidden" name="signature" value="<%= signature %>" > Karteninhabername <input type="text" name="cardholder" size="20"><br> Kartennummer <input type="text" name="sfpcardnumber" size="16"><br> Gültig bis <input type="text" name="sfpcardexpirymonth" size="2"> <input type="text" name="sfpcardexpiryyear" size="2"><br> Kartenprüfnummer <input type="text" name="cvc" size="4"><br> <input type="submit" name="submit" value="absenden"> </form> </body></html> Saferpay Secure Card Data page 12

13 5.2.2 Commandline calls with the Java LIB java -jar Saferpay.jar -payinit -p C:\Programs\Saferpay\Client -a ACCOUNTID a CARDREFID "ABCDEF " -a FAILLINK " -a SUCCESSLINK " Created registration URL (regurl): tp%3a%2f%2fwww.testshop.de%2fregsuccess.php%22+expiration%3d% %3a10%3a50%22+faill INK%3D%22http%3A%2F%2Fwww.testshop.de%2Fregfail.php%22+MSGTYPE%3D%22PayInit%22+KEYID%3D% fa355eef4b7e fd31b8c7a%22+CARDREFID%3D%22ABCDEF %22+ACCOUNTID%3D% %22+DELIVERY%3D%22yes%22+TOKEN%3D%22091adcf e0af1cc7ebf230e346%22%2F%3E&SIGNATU RE=68FF171E3F74B630BFE0AE33EA05A8486BCFEE BEA4BA4919F796A6733C16548FCFF81AC37CE9E 8D769793F73FDD3B36F19BBAC147C377D0BEF0 Registration form: <html><body> <form method="post" action="<% = regurl %>"> Karteninhabername <input type="text" name="cardholder" size="20"><br> Kartennummer <input type="text" name="sfpcardnumber" size="16"><br> Gültig bis <input type="text" name="sfpcardexpirymonth" size="2"> <input type="text" name="sfpcardexpiryyear" size="2"><br> Kartenprüfnummer <input type="text" name="cvc" size="4"><br> <input type="submit" name="submit" value="absenden"> </form> </body></html> Saferpay Secure Card Data page 13

14 5.2.3 Usage of the https Interface 59&CARDREFID=ABCDEF &FAILLINK=" Created registration URL (regurl): tp%3a%2f%2fwww.testshop.de%2fregsuccess.php%22+expiration%3d% %3a10%3a50%22+faill INK%3D%22http%3A%2F%2Fwww.testshop.de%2Fregfail.php%22+MSGTYPE%3D%22PayInit%22+KEYID%3D% fa355eef4b7e fd31b8c7a%22+CARDREFID%3D%22ABCDEF %22+ACCOUNTID%3D% %22+DELIVERY%3D%22yes%22+TOKEN%3D%22091adcf e0af1cc7ebf230e346%22%2F%3E&SIGNATU RE=68FF171E3F74B630BFE0AE33EA05A8486BCFEE BEA4BA4919F796A6733C16548FCFF81AC37CE9E 8D769793F73FDD3B36F19BBAC147C377D0BEF0 Registration form: <html><body> <form method="post" action="<% = regurl %>"> Karteninhabername <input type="text" name="cardholder" size="20"><br> Kartennummer <input type="text" name="sfpcardnumber" size="16"><br> Gültig bis <input type="text" name="sfpcardexpirymonth" size="2"> <input type="text" name="sfpcardexpiryyear" size="2"><br> Kartenprüfnummer <input type="text" name="cvc" size="4"><br> <input type="submit" name="submit" value="absenden"> </form> </body></html> 5.3 Evaluation of the Registration Response C# mit der.net LIB string data = Request.QueryString.Get("DATA"); string signature = Request.QueryString.Get("SIGNATURE"); MessageFactory mf = new MessageFactory(); mf.open(""); mo_regres = mf.verifypayconfirm(data, signature); string m_result = mo_regres.getattribute(result); string m_accountid = mo_regres.getattribute(accountid); string m_refid = mo_regres.getattribute(cardrefid); string m_cardmask = mo_regres.getattribute(cardmask); string m_month = mo_regres.getattribute(expirymonth); string m_year = mo_regres.getattribute(expiryyear); string m_brand = mo_regres.getattribute(cardbrand); string m_type = mo_regres.getattribute(cardtype); string m_lifetime = mo_regres.getattribute(lifetime); string m_holder = Request("CardHolder"); string m_cvc = Request("CVC"); Saferpay Secure Card Data page 14

15 5.3.2 Commandline calls with the Java LIB Return to the SUCCESSLINK after successful registration: RESULT%3d"0"+SCDRESULT%3d"0"+SCDDESCRIPTION%3d"Request+successfully+processed."+DESCRIPTION%3 d"request+successfully+processed."+cardrefid%3d"abcdef "+lifetime%3d"1000"+accountid%3d " "+CARDTYPE%3d"99072"+CARDMASK%3d"xxxx+xxxx+xxxx+0004"+CARDBIN%3d"945112"+CARDB RAND%3d"Saferpay+Test+Card"+EXPIRYMONTH%3d"05"+EXPIRYYEAR%3d"16"+%2f>&SIGNATURE=3ca06ae174adf 2dad9e5b8a27487b680c22e77cafdf5d85fbc675823fb9e9fc096e0a27621e1f956db1e5e a1813e10b726e 75b3f1e148b a4b9&CardHolder=Karl+Mustermann&CVC=123 Received DATA: <IDP MSGTYPE="InsertCardResponse" KEYID="1 0" RESULT="0" SCDRESULT="0" SCDDESCRIPTION="Request successfully processed." DESCRIPTION="Request successfully processed." CARDREFID="ABCDEF " LIFETIME="1000" ACCOUNTID=" " CARDTYPE="99072" CARDMASK="xxxx xxxx xxxx 0004" CARDBIN="945112" CARDBRAND="Saferpay Test Card" EXPIRYMONTH="05" EXPIRYYEAR="16" /> Received SIGNATURE: 3ca06ae174adf2dad9e5b8a27487b680c22e77cafdf5d85fbc675823fb9e9fc096e0a27621e1f956db1e5e a1813e10b726e75b3f1e148b a4b9 VerifyPayConfirm: java -jar saferpay.jar -payconfirm -p C:\Programs\Saferpay\keys\ d "<IDP+MSGTYPE%3d"Ins ertcardresponse"+keyid%3d"1-0"+result%3d"0"+scdresult%3d"0"+scddescription%3d"request+success fully+processed."+description%3d"request+successfully+processed."+cardrefid%3d"abcdef " +LIFETIME%3d"1000"+ACCOUNTID%3d" "+CARDTYPE%3d"99072"+CARDMASK%3d"xxxx+xxxx+xxxx +0004"+CARDBIN%3d"945112"+CARDBRAND%3d"Saferpay+Test+Card"+EXPIRYMONTH%3d"05"+EXPIRYYEAR%3d"1 6"+%2f>" -s 3ca06ae174adf2dad9e5b8a27487b680c22e77cafdf5d85fbc675823fb9e9fc096e0a27621e1f956d b1e5e a1813e10b726e75b3f1e148b a4b Usage of the https Interface +SCDDESCRIPTION%3d"Request+successfully+processed."+DESCRIPTION%3d"Request+successfully+proce ssed."+cardrefid%3d"abcdef "+lifetime%3d"1000"+accountid%3d" "+cardtype%3d "99072"+CARDMASK%3d"xxxx+xxxx+xxxx+0004"+CARDBIN%3d"945112"+CARDBRAND%3d"Saferpay+Test+Card"+ EXPIRYMONTH%3d"05"+EXPIRYYEAR%3d"16"+%2f>"&SIGNATURE=3ca06ae174adf2dad9e5b8a27487b680c22e77ca fdf5d85fbc675823fb9e9fc096e0a27621e1f956db1e5e a1813e10b726e75b3f1e148b a4b9 Saferpay Secure Card Data page 15

16 6 Contact 6.1 Saferpay Integration Team Do you have questions about this document or problems with the integration of Saferpay or do you need assistance? Then please contact our integration team: Saferpay Switzerland SIX Payment Services AG Hardturmstrasse Zürich Saferpay Europe SIX Payment Services (Germany) GmbH Langenhorner Chaussee Hamburg Saferpay Support Team Do you have questions about error messages or do you encounter problems with your running system? Then please contact our support team: Saferpay Switzerland SIX Payment Services AG Hardturmstrasse Zürich Saferpay Europe SIX Payment Services (Germany) GmbH Langenhorner Chaussee Hamburg The Saferpay team wishes you every success with your Saferpay e-payment solution! Saferpay Secure Card Data page 16