Cartão Protegido (Protected Card)

Transcrição

Integration Manual
Version 2.1
9/10/2013
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
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
Page 3 of 19
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
Page 4 of 19
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
Page 5 of 19
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
Page 6 of 19
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
Page 7 of 19
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
Page 8 of 19
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
Page 9 of 19
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
Page 10 of 19
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
Description
Required?
Page 11 of 19
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
Yes
JustClickKey
Guid
Token representing the credit card
Yes
JustClickAlias
string
No
RequestId
Guid
No
Version
string
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
Description
Required?
Page 12 of 19
Integration Manual
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
Yes
JustClickKey
Guid
Yes
RequestId
Guid
No
Version
string
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
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
Description
Required?
Page 13 of 19
Integration Manual
List <ErrorReport>
Phone: (21)2111-4700 / (11) 3320-9050
Page 14 of 19
No
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
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
No
Version
string
No
Table 8 - JustClickShopResponse
Parameters
Type
Description
JustClickKey
Guid
CorrelationId
Guid
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
List <ErrorReport>
No
Phone: (21)2111-4700 / (11) 3320-9050
Required?
Yes
Page 15 of 19
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
Yes
JustClickKey
Guid
Yes
JustClickAlias
string
No
RequestId
Guid
No
Version
string
No
Table 10 - InvalidateCreditCardResponse
Parâmetros
Tipo
CorrelationId
Guid
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
List
<ErrorReport>
No
Phone: (21)2111-4700 / (11) 3320-9050
Descrição
Obrigatório?
Page 16 of 19
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
Page 17 of 19
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
Page 18 of 19
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
Page 19 of 19

Cartão Protegido (Protected Card)

Transcrição

Documentos relacionados

BUZIOS BRAZIL RESERVATION

QUALITY SUITES METROPOLIS

hotel reservation form

Hotel booking form - 6th Annual Africa Sugar 2016

inscrição advance saver registration form brazil gri 2012

BNU財運卡申請表 BNU Debit Card Application Form Formulário de

Scent Chart®

Crib - VocApp

To mark our new routes to Lisbon, Monarch has

I was surprised to discover Dictionary Review Peter A. Gergay