Cartão Protegido (Protected Card)
Transcrição
Cartão Protegido (Protected Card)
Cartão Protegido (Protected Card) Integration Manual Version 2.1 9/10/2013 Cartão Protegido (Protected Card) Integration Manual TABLE OF CONTENTS HISTORY OF CHANGES.....................................................................................................................................3 ABOUT THE PLATFORM .....................................................................................................................................4 ABOUT THE PRODUCT ......................................................................................................................................4 ABOUT THIS MANUAL.......................................................................................................................................4 1. CARTÃO PROTEGIDO (PROTECTED CARD)...................................................................................................5 2. PARAMETER JUSTCLICKALIAS....................................................................................................................6 2.1. RIGHT WAY OF ASSOCIATION ...............................................................................................................6 2.2. FORM NOT ACCEPTED OF ASSOCIATION .................................................................................................6 3. AUTHORIZATION PROCESS VIA CARTÃO PROTEGIDO (PROTECTED CARD) PLATFORM......................................7 4. AUTHORIZATION PROCESS VIA PAGADOR ..................................................................................................8 4.1. AUTHORIZATION WITH THE OPTION TO SAVE CARD DETAILS ...................................................................8 4.2. AUTHORIZATION VIA PREVIOUSLY SAVED CARD .....................................................................................8 4.3. AUTHORIZATION VIA POST ...................................................................................................................9 5. SECURITY CODE (CVV) .............................................................................................................................9 6. TIPS FOR IMPLEMENTATION .................................................................................................................... 10 6.1. IMPLEMENTING JUSTCLICKSHOP ......................................................................................................... 10 6.1.1. 6.2. 7. BEST PRACTICES ........................................................................................................................... 10 IMPLEMENTING RECURRING CHARGE ................................................................................................... 10 CARTÃO PROTEGIDO (PROTECTED CARD) METHODS ................................................................................. 11 7.1. SAVING A CREDIT CARD ..................................................................................................................... 11 7.2. CREDIT CARD NUMBER RETRIEVAL WITH MASKED RETURN .................................................................... 12 7.3. RETRIEVING CREDIT CARD INFORMATION ............................................................................................ 13 7.4. RETRIEVING A JUSTCLICKKEY ............................................................................................................. 15 7.5. INVALIDATING A CREDIT CARD ........................................................................................................... 16 8. ERROR MAP........................................................................................................................................... 18 9. PAYMENT METHODS ACCEPTED IN THE AUTHORIZATION VIA PAGADOR ....................................................... 19 Phone: (21)2111-4700 / (11) 3320-9050 http://suporte.braspag.com.br Page 2 of 19 Cartão Protegido (Protected Card) Integration Manual HISTORY OF CHANGES Cartão Protegido (Protected Card) – Integration Manual Version Date Description 1.5 6/05/2012 Change Layout 2.0 8/24/2012 Parameter: JustClickAlias Indexing of Tables Insertion of new codes in Map Errors 2.1 9/10/2013 Removal of the error 723 on the Error Map Phone: (21)2111-4700 / (11) 3320-9050 http://suporte.braspag.com.br Page 3 of 19 Cartão Protegido (Protected Card) Integration Manual ABOUT THE PLATFORM CARTÃO PROTEGIDO (PROTECTED CARD) is a safe credit card information storage platform. The data stored at the Protected Card Platform follows PCI standards that ensure the integrity of the card information stored. The CARTÃO PROTEGIDO (PROTECTED CARD) integrates with gateway PAGADOR (BRASPAG), facilitating the submission and processing of credit card transactions via token. ABOUT THE PRODUCT While product, CARTÃO PROTEGIDO (PROTECTED CARD), as a solution to the problem of secure data storage of credit card can be used for various purposes such as: • 1 Click Shop: “1 Click Shop” allows an online payment (via credit card) be made skipping the step of filling in the payment details or even the whole process of the shopping cart, since card data were previously reported by the buyer in past purchases and will be replicated in future purchases through its authorization. • Recurrent Billing: Establishments that already have an internal solution for managing recurrences can use the platform just to the sensitive part: storing data and credit card processing via PAGADOR, charges in Acquirers by using only the token. (Não é obrigatório que a transação seja processada via Pagador) • Retry sending transaction (sale): For establishments that store data sale to pass in a second time, and to re-try sending a credit card transaction for a Purchaser or to any internal procedure before authorizing the sale (inventory validation, analysis of fraud), the platform perfectly serves this purpose. The establishment needs to understand and manipulate just one token, remaining adherent to the security rules of the industry of credit cards. • Or for any other purpose, which is necessary to store data from a credit card safely, even temporarily. The "One Click Shop" enables online payments via credit card skipping the step of filling out payment details or even the whole shopping basket process, since all card details have previously been informed by the purchaser on past purchases and will be automatically replicated in new purchases upon the purchaser's authorization. ABOUT THIS MANUAL This manual aims to guide the Merchant's developer on the integration with the CARTÃO PROTEGIDO (PROTECTED CARD) platform, describing existing functions and methods to be used, listing information to be sent and received, and providing examples. To get the production URL, please ask our implementation team through our support tool. Phone: (21)2111-4700 / (11) 3320-9050 http://suporte.braspag.com.br Page 4 of 19 Cartão Protegido (Protected Card) Integration Manual 1. CARTÃO PROTEGIDO (PROTECTED CARD) Please see the graphics for the sales process flows in the sections below. There are 3 ways to integrate the product: 1. Directly via CARTÃO PROTEGIDO (PROTECTED CARD) 2. Via PAGADOR platform - through Web services. 3. Via PAGADOR platform - through Data Posts. platform The following data is required to store a credit card in the platform: Customer's CPF (Taxpayer ID), Customer's Name, Cardholder's Name, Card Number, and Expiration Date. The security code is not stored (please refer to the Security Code The CARTÃO PROTEGIDO (PROTECTED CARD) platform safely stores credit card data, with 100% PCI Compliance. section). Since the transaction authorization is carried via PAGADOR, all other functions for transaction confirmation Second Post (confirmation post), and Third Post (probe) - continue to work the same way. For enhanced security, only previously registered IPs of the Merchant will be allowed to query credit card numbers or authorize transactions using the CARTÃO PROTEGIDO (PROTECTED CARD) key (JustClickKey). Phone: (21)2111-4700 / (11) 3320-9050 http://suporte.braspag.com.br Page 5 of 19 Cartão Protegido (Protected Card) Integration Manual 2. PARAMETER JustClickAlias This parameter is intended to facilitate the storage, by the customer, of information related to a Secured Card The customer may at the time of the rescue card, create an alias (name) will identify the card in Platform CARTÃO PROTEGIDO (PROTECTED CARD). Another advantage is the fact that this alias can be associated with a new JustClickKey, which facilitates the exchange of a card when, for example, its validity expires. Para isso, o lojista deveria indicar que o JustClickKey está desabilitado. Dessa forma, o Alias associado a ele ficaria liberado para ser utilizado com um novo JustClickKey. 2.1. Right Way of Association An Alias can be associated with a new token, since before being disassociated from the old Token as shown in the example below: Merchant Id JustClickKey (Token) Alias Enabled SHOP A Token 1 XPTO 0 SHOP A Token 2 XPTO 0 SHOP A Token 3 XPTO 1 Note: Disassociation occurs after the execution of the method InvalidateCreditCard (Item 8.5). 2.2. Form not accepted of Association An Alias can be associated with a new token, since before being disassociated Token old, in the example below is shown a way that would not allow this association because the Alias will only be released to a new association that is disconnected from a particular Token: Merchant Id JustClickKey (Token) Alias Enabled SHOP A Token 1 XPTO 1 SHOP A Token 2 XPTO 1 SHOP A Token 3 XPTO 1 Phone: (21)2111-4700 / (11) 3320-9050 http://suporte.braspag.com.br Page 6 of 19 Cartão Protegido (Protected Card) Integration Manual 3. AUTHORIZATION PROCESS VIA CARTÃO PROTEGIDO (PROTECTED CARD) PLATFORM Below is the process of request for saving customer card details during a sale transaction, followed by another process in which the same customer makes a purchase via CARTÃO PROTEGIDO (PROTECTED CARD). After having the customer's permission to save his/her card details, the merchant should: 1. 2. 3. 4. Submit the purchase authorization request via Gateway. Standard process already adopted today Receive the authorization result Submit the card details for storage in the CARTÃO PROTEGIDO (PROTECTED CARD) platform Receive and store the “JustClickKey”, which is the key representing the pair “credit card-customer” for future “One Click Shops”. When the customer returns to the site for a new purchase and logs in, the site can offer the “One Click Shop” option and the flow will be: 1. 2. To invoke the transaction authorization directly from the CARTÃO PROTEGIDO (PROTECTED CARD) platform, passing the customer's “JustClickKey” and, optionally, the CVV (please refer to the Security Code section) Receive the authorization result Phone: (21)2111-4700 / (11) 3320-9050 http://suporte.braspag.com.br Page 7 of 19 Cartão Protegido (Protected Card) Integration Manual 4. AUTHORIZATION PROCESS VIA PAGADOR Below are the processes of request for saving a customer card during a sale transaction and a purchase via CARTÃO PROTEGIDO (PROTECTED CARD) platform, both using the PAGADOR/CARTÃO PROTEGIDO (PROTECTED CARD) integration 4.1. AUTHORIZATION WITH THE OPTION TO SAVE CARD DETAILS 1. 2. 3. 4. Submit the purchase authorization request via PAGADOR with the SaveCreditCard parameter; PAGADOR submits the credit card details to the CARTÃO PROTEGIDO (PROTECTED CARD) platform for storage; CARTÃO PROTEGIDO (PROTECTED CARD) platform submits the card details storage response to PAGADOR; As a result, PAGADOR submits the authorization and storage response to the customer; 4.2. AUTHORIZATION VIA PREVIOUSLY SAVED CARD 1. 2. 3. 4. Submit the purchase authorization request via PAGADOR with the CredicardToken parameter; PAGADOR submits the credit card details to the CARTÃO PROTEGIDO (PROTECTED CARD) platform for retrieval of previously saved card details; CARTÃO PROTEGIDO (PROTECTED CARD) platform submits the card details response to PAGADOR; As a result, PAGADOR submits the authorization response to the customer; Note that all communication is held by the merchant via PAGADOR platform. For all information on the Web services methods and parameters, as well as the methods of the integration via Post, please request the respective manuals of the PAGADOR platform. Phone: (21)2111-4700 / (11) 3320-9050 http://suporte.braspag.com.br Page 8 of 19 Cartão Protegido (Protected Card) Integration Manual 4.3. AUTHORIZATION VIA POST Below is the process of authorization via Post. Showing a transaction where the customer has the key generated by the CARTÃO PROTEGIDO (PROTECTED CARD) platform, and another transaction where this key is still to be generated and sent to the customer (CredicardToken). * The “CreditCardToken” parameter returned by the PAGADOR platform is the “JustClickKey” of the CARTÃO PROTEGIDO (PROTECTED CARD) platform. 5. SECURITY CODE (CVV) The security code is required to enable the authorization of a remote purchase to be accepted by the bank issuing the card. It is another security mechanism in the antifraud process that seeks to confirm that the person who is using a card is unmistakably the cardholder. Therefore, the card industry regulations (PCI) allow the storage of the card's number and expiration date, but never the security code. This code should always be requested at the time of purchase, for validation. As BRASPAG is a PCI-compliant company, it does not store the security code, which will have to be requested by the merchant upon sales confirmation via CARTÃO PROTEGIDO (PROTECTED CARD). However, the issuing banks and credit card operators can eliminate the obligation of security code to affiliations of merchants that have a business model based on recurrence, such as Service Subscriptions. For such merchants, the authorization of transactions without the security code is allowed. This recurrence condition is granted exclusively by the Operators, not depending on BRASPAG. Phone: (21)2111-4700 / (11) 3320-9050 http://suporte.braspag.com.br Page 9 of 19 Cartão Protegido (Protected Card) Integration Manual 6. TIPS FOR IMPLEMENTATION 6.1. IMPLEMENTING JUSTCLICKSHOP To make a sale through one click, it is necessary that the property already has an authorization provided by the customer to store the data of your credit card. Thus, in the next shop he can choose to pay with a credit card previously saved. Granted authorization for storage, just that the establishment send card data to the platform PROTECTED CARD, receiving in response a key that represents the double "credit-card customer." For each distinct card that the customer authorizes the storage, provide a key CARTÃO PROTEGIDO (PROTECTED CARD) also distinct. In the next sales to this customer, the establishment will offer "buy with one click" as payment. This can be done via a button "buy with one click" on the product / service selected, or more as a means of payment in the process of finalizing the shopping cart. To process a sale via "buy with one click", just that it is passed to the platform CARD PROTECTED previously provided the key that identifies the "credit card-customer" and, depending on which service PROTECTED CARD establishment chooses to use, the platform will: • • Return the card data to establish authorize the transaction; Authorize the transaction in Direct Operator via PAY (this being the most suitable for ensuring greater data security). 6.1.1. • • • • • BEST PRACTICES Save the credit card number masked to indicate the customer which cards are enable at the site for “One Click Shop”; Optionally, save the expiration date to actively communicate the customer that the card stored has expired and suggest replacement; Only save the card in the CARTÃO PROTEGIDO (PROTECTED CARD) platform when it was successfully authorized in the last purchase of the customer; Safety of login and password of the site users – too weak passwords are easily guessed and the fraudster can make a purchase even without the card (if the site do not request for the CVV); Control session variables to prevent the user (customer's login) from remaining logged into the site thus being subject to unauthorized access and “One Click Shops” using the open session (e.g., users connected in cybercafés). 6.2. IMPLEMENTING RECURRING CHARGE For each order to be charged with credit card recurrence, the merchant must save the credit card details in the CARTÃO PROTEGIDO (PROTECTED CARD) platform and receive the key (JustClickKey) representing that “ordercard” pair. On the recurrence charge date, simply invoke the card authorization method and pass it the payment data and, instead of the card info (number + expiration date), the corresponding key (JustClickKey). If you need to replace the card for a specific order, simply save the new card info in the CARTÃO PROTEGIDO (PROTECTED CARD) platform, and the new key generated will be associated to the order in the merchant's platform. No need to cancel/delete the old card in the platform. If there is a need to associate an existing Alias to a new JustClickKey, just disable the old JustClickKey to leave the Alias associated with it, cleared for a new association. If the business chooses not process the transaction authorization by integrating PAGADOR / CARTÃO PROTEGIDO (PROTECTED CARD), it is essential that at any moment the card number is written (persisted in the bank or in the browser section) so that information security is maintained. Phone: (21)2111-4700 / (11) 3320-9050 http://suporte.braspag.com.br Page 10 of 19 Cartão Protegido (Protected Card) Integration Manual 7. CARTÃO PROTEGIDO (PROTECTED CARD) METHODS Below are the processes of web methods of the CARTÃO PROTEGIDO (PROTECTED CARD) platform used to execute the procedures described in the previous sections via web service. 7.1. SAVING a credit card The SaveCreditCard method gets a SaveCreditCardRequest object, and should be invoked to save credit card details and get an identification key (token) representing the “credit card-customer” pair for future authorizations via “One Click Shop”. Do not enter duplicated RequestId for this operation, since this info will be required to retrieve the JustClickKey when using the GetJustClickKey() method. Table 1 - SaveCreditCardRequest Parameters Type Description Required? MerchantKey Guid Key of the JustClick merchant Yes CustomerIdentification string Purchaser's CPF (Taxpayer ID) No CustomerName string Purchaser's name Yes CardHolder string Name of the credit card holder Yes CardNumber string Credit card number Yes CardExpiration string Credit card expiration date. Format: mm/yyyy Yes JustClickAlias string Alias (Nickname) of the credit card RequestId Guid Submitted request ID Version string Method version. Model: 1.0 No Yes No Table 2 - SaveCreditCardResponse Parameters Type JustClickKey Guid Token (Identification Key) representing the credit card Yes CorrelationId Guid ID of the response received, which is the “RequestId” sent through the request object Sm Phone: (21)2111-4700 / (11) 3320-9050 http://suporte.braspag.com.br Description Required? Page 11 of 19 Cartão Protegido (Protected Card) Integration Manual Success bool ErrorReportCollection List <ErrorReport> Success flag for the operation flow (true or false). FALSE indicates the request was not successfully completed, and thus all other return parameters should be ignored Error/Validation list generated in the operation flow. Please refer to “Error Map” section No No 7.2. Credit card number RETRIEVAL with masked return The GetMaskedCreditCard method gets the GetMaskedCreditCardRequest object, and should be invoked to query card details under PCI Compliance, i.e., the GetMaskedCreditCardResponse method returns only the card's masked number, along with the remaining non-sensitive information. Getting a Masked Credit Card - GetMaskedCreditCard() method GetMaskedCreditCardRequest MERCHANT CARTÃO PROTEGIDO GetMaskedCreditCardResponse Table 3 - GetMaskedCreditCardRequest Parameters Type Description Required? MerchantKey Guid Key of the JustClick merchant Yes JustClickKey Guid Token representing the credit card Yes JustClickAlias string Alias (Nickname) of the credit card No RequestId Guid Submitted request ID No Version string Method version. Model: 1.0 No Table 4 - GetMaskedCreditCardResponse Parameters Type CardHolder string Credit card holder Yes CardExpiration string Credit card expiration date. Format: mm/yyyy Yes MaskedCardNumber string Credit card masked number Yes CorrelationId Guid ID of the response received, which is the “RequestId” sent through the request object No Success bool Success flag for the operation flow (true or false). FALSE indicates the request was not successfully completed, and thus all other return parameters should be ignored No Phone: (21)2111-4700 / (11) 3320-9050 http://suporte.braspag.com.br Description Required? Page 12 of 19 Cartão Protegido (Protected Card) Integration Manual ErrorReportCollection List <ErrorReport> Error/Validation list generated in the operation flow. Please refer to “Error Map” section No 7.3. RETRIEVING credit card information The GetCreditCard method gets the GetCreditCardRequest object, and should be invoked to query credit card details, including the card open number. In general, this method is used only to authorize the transaction through a gateway other than PAGADOR or directly in the card operator. This method should be used carefully since it handles sensitive data. Getting a Credit Card - GetCreditCard() method GetCreditCardResponse MERCHANT CARTÃO PROTEGIDO GetCreditCardRequest Table 5 - GetCreditCardRequest Parameters Type Description Required? MerchantKey Guid Key of the JustClick merchant Yes JustClickKey Guid Token representing the credit card Yes RequestId Guid Submitted request ID No Version string Method version. Model: 1.0 No Table 6 - GetCreditCardResponse Parameters Type CardHolder string Credit card holder Yes CardNumber string Credit card open number Yes CardExpiration string Credit card expiration date. Format: mm/yyyy Yes MaskedCardNumber string Credit card masked number Yes CorrelationId Guid ID of the response received, which is the “RequestId” sent through the request object No Success bool Success flag for the operation flow (true or false). FALSE indicates the request was not successfully completed, and thus all other return parameters should be ignored No Phone: (21)2111-4700 / (11) 3320-9050 http://suporte.braspag.com.br Description Required? Page 13 of 19 Cartão Protegido (Protected Card) Integration Manual ErrorReportCollection List <ErrorReport> Phone: (21)2111-4700 / (11) 3320-9050 http://suporte.braspag.com.br Error/Validation list generated in the operation flow. Please refer to “Error Map” section Page 14 of 19 No Cartão Protegido (Protected Card) Integration Manual 7.4. RETRIEVING a JustClickKey The GetJustClickKey method receives the GetJustClickKeyRequest object, and should be invoked to query a JustClickKey. In general, this method is used only when the merchant looses the JustClickKey for a user. For security reasons, if the merchant uses this method 5 (five) times in a row passing an invalid ‘SaveCreditCardRequestId’, the method will be blocked until the merchant contact Braspag's support team to release. Table 7 - GetJustClickKeyRequest Parameters Type Description Required? MerchantKey Guid Key of the JustClick merchant Yes SaveCreditCardRequestId Guid ID of the request to the SaveCreditCard method (“RequestId” parameter) that resulted in the storage of the credit card in the CARTÃO PROTEGIDO (PROTECTED CARD) platform. Yes RequestId Guid Submitted request ID No Version string Method version. Model: 1.0 No Table 8 - JustClickShopResponse Parameters Type Description JustClickKey Guid Token representing the credit card CorrelationId Guid ID of the response received, which is the “RequestId” sent through the request object No Success bool Success flag for the operation flow (true or false). FALSE indicates the request was not successfully completed, and thus all other return parameters should be ignored No ErrorReportCollection List <ErrorReport> Error/Validation list generated in the operation flow. Please refer to “Error Map” section No Phone: (21)2111-4700 / (11) 3320-9050 http://suporte.braspag.com.br Required? Yes Page 15 of 19 Cartão Protegido (Protected Card) Integration Manual 7.5. Invalidating a Credit Card The method InvalidateCreditCard receives the object InvalidateCreditCardRequest, and must be called for invalidating a credit card. An invalid card can not be used in an authorization of the PAGADOR Table 9 - InvalidateCreditCardRequest Parameters Type Description Required? MerchantKey Guid Key of the JustClick merchant Yes JustClickKey Guid Token representing the credit card Yes JustClickAlias string Alias (Nickname) of the credit card No RequestId Guid Submitted request ID No Version string Method version. Model: 1.0 No Table 10 - InvalidateCreditCardResponse Parâmetros Tipo CorrelationId Guid ID of the response received, which is the “RequestId” sent through the request object No Success bool Success flag for the operation flow (true or false). FALSE indicates the request was not successfully completed, and thus all other return parameters should be ignored No ErrorReportCollection List <ErrorReport> Error/Validation list generated in the operation flow. Please refer to “Error Map” section No Phone: (21)2111-4700 / (11) 3320-9050 http://suporte.braspag.com.br Descrição Obrigatório? Page 16 of 19 Cartão Protegido (Protected Card) Integration Manual Important details in the use of the methods: “RequestID”/ “CorrelationID”: In the submission of a Request object, any one guid must be submitted in the “RequestID” parameter to work as an identification key for that Request. After processing the Request, the Response object shall be mounted with the corresponding result, and the “CorrelationID” parameter shall contain the same guid sent in the Request (“RequestID”). Therefore, it is possible to identify which Request the Response object originates from; “Success”: Every Response object has a “Success” parameter that indicates whether or not the requisition was successfully processed by the application. If the “Success” parameter returns FALSE, it means there was an error receiving and/or processing the request, i.e., the method could not perform its function successfully. Thus, this should be the first parameter to be checked in the request return. If it returned FALSE, all further processing should be aborted and the error analyzed and addressed. “ErrorReportCollection”: Every Response object has an “ErrorReportCollection” parameter that contains the error(s) occurred in the processing, i.e., when the “Success” parameter returns FALSE. The processing error can be due to an incorrect parameter, or the absence of an expected parameter. Phone: (21)2111-4700 / (11) 3320-9050 http://suporte.braspag.com.br Page 17 of 19 Cartão Protegido (Protected Card) Integration Manual 8. ERROR MAP Below is a list of potential errors returned by the methods in the “ErrorReportCollection” field Code Message 701 Merchant key cannot be null 702 Merchant key is not valid 703 JustClick key cannot be null 704 JustClick key is not valid 705 Customer name cannot be null 706 Card holder cannot be null 707 Card number cannot be null 708 Card number is not valid 709 Card expiration cannot be null 710 Card expiration is not valid (Format: MM/yyyy) 720 Merchant JustClick not found 724 Credit card not exists for merchant 731 Invalid IP address 732 SaveCreditCardRequestId cannot be null 733 SaveCreditCardRequestId not found for this Merchant 734 Numbers of attempts to Recovery JustClickKey exceeded 735 Save Credit Card Request Id Already Exists 747 Empty Request 749 JustClickAlias Already Exists 750 Extra Data Name Is Not Valid 751 JustClickAlias Is Not Filled 752 Data Collection Can Not Be Empty 753 JustClickAlias Is Mandatory 799 Undefined error Phone: (21)2111-4700 / (11) 3320-9050 http://suporte.braspag.com.br Page 18 of 19 Cartão Protegido (Protected Card) Integration Manual 9. PAYMENT METHODS ACCEPTED IN THE AUTHORIZATION VIA PAGADOR In the use of the CARTÃO PROTEGIDO (PROTECTED CARD) authorization method, all existing credit card payment method is accepted in the integration of PAGADOR via Web service, and the merchant needs only to have affiliation for such. Payment methods that necessarily work via Post, such as Cielo Visa Electron or Mastercard Komerci, cannot be used when the integration is directly via CARTÃO PROTEGIDO (PROTECTED CARD) platform. Phone: (21)2111-4700 / (11) 3320-9050 http://suporte.braspag.com.br Page 19 of 19