# 3D Secure Guide 3-D Secure is a protocol designated to redurce fradulant transactions and protect merchants from losing the funds for those transactions. The name refers to the "three domains" which interact using the protocol: the merchant/acquirer domain, the issuer domain, and the interoperability domain. Our API is designed to allow platforms to offer a full payment solution as part of their product.Using the API you can allow sellers accept 3DSecure authorizations for credit card payments. ## Introduction - 3D Secure 3-D Secure is a protocol designated to redurce fradulant transactions and protect merchants from losing the funds for those transactions. The name refers to the "three domains" which interact using the protocol: the merchant/acquirer domain, the issuer domain, and the interoperability domain. Our API is designed to allow platforms to offer a full payment solution as part of their product. Using the API you can allow sellers accept 3DSecure authorizations for credit card payments. Requirements | Key | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------- | | PayMe-Public-Key | Merchant's public key, must be sent in the HEADER of /api/sales/{payme_sale_id}/3ds requests | | PayMe-Merchant-Ke | Merchant's unique ID (seller_payme_id), must be sent in the HEADER of api/sales/{payme_sale_id}/3ds/{hash} requests | | Active 3DSecure module | The seller must have an active 3DSecure module in his PayMe account | | Credit card details | Mapped to payment input | | Cardholder details | Mapped to customer input | ## 3DSecure General Flow The flow is built with a few steps to allow multiple integration types. It is important to be familiar with the whole flow to be able to understand the customer experience. ## Generating a Regular SaleGenerating the sale with our Ganerate-Sale API endpoint. Please notice that the flow ends in a redirect that will return the 3DSecure result hash. This URL will be configured in the sale_return_url, the same way we set in regular payments. More info at step Retrieve 3DSecure Hash. ## Initialize 3DSecure Request Right after we genereiting the sale, we are initializing a secured payment attempt. A successful response contains a redirect_url attribute that you should redirect the customer to. An error can caused when the 3DSecure provider cannot handle the credit card. This function should be sent from you frontend, thus required a public key authenication. ## Open the 3DSecure Page - Card Issuer Interacation When the user get redirected, we are generating a custom authorization page according to the card issuer. The issuer may authenticate the attempt in verious ways, like: - SMS code verification - A secret code - Activate from private application ## Retrieve 3DSecure Hash As the buyer complete the authorization, he got redirect back from the card issuer page, and we want to get again to the flow (as the previous redirects was asyncronous), so we can continue the flow by showing message according to the result status, and use the result to compelete the payment page using the 3DSecure Parameters. We are going to do this by with a hash, that we are goint to resolve in the next step There are 2 way to achieve this step: ## JavaScript Window\.postMessage In case we open the redirect in an iframe, we can create a postMessage Listener in our parent page that will handle the result. The Listener will get a JSON serialized object, with 2 attributes: type: "3DSecure Hash" and hash: "S0ME-R4ND0M-H4SH" The Listener also may close the payment page if you want. For example: ```js // Called sometime after postMessage is called function receiveMessage(event) { // Do we trust the sender of this message? if (event.origin !== "https://preprod.paymeservice.com") return; data = JSON.parse(event.data) if (data.type !== "3DSecure Hash") { return; } // TODO: Great! now its time to think again... request "api/sales/{guid}/3ds/" + data.hash // TODO: Failed? show error message. success? try pay with 3 parameters console.log("myPaymentPage", event); pay3DS(resolve3DS(data.hash)); } window.addEventListener("message", receiveMessage, false); ``` ## GET parameter in the sale_redirect_url The 3dsecure hash will be returned at the 3ds GET parameter, with all other sale return parameters (can be found at success redirects)In cases that PayMe gets no sale_return_url or parent.callback3DSecure function, we will pop up an alert message that something was missing. ## Resolve Secured Hash Got the 3DSecure hash? Great, now we want to check if the attempt was successful, or has it failed and we should start the flow again with Initialize 3DSecure Request. You implement this step by the Resolve Secured Hash API. This API should be called from your backend as we are using a private key! A successful HTTP code for this function means the hash was not damaged. To check if the attempt was successful or not, we should check the status_code paramter.A successful message will contain the payme_sale_id and three parameters which will identify this transaction as 3DSecure. These values are the ECI, the CAVV and the XID. Now we can proceed with the payment itself. ## Pay! Now we have the three parameters of the 3DSecure authorization, which in most cases will be sent to the Acquirer/Gateway as-is, without any modifications. ## Special ECI Handling These are the available ECI values: | ECI Value | Card Schema | Definition | | --------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 00 | MasterCard | Authentication is unsuccessful or not attempted. The credit card is either a non-3D card or card issuing bank does not handle it as a 3D transaction. | | 01 | MasterCard | 3D card authentication is unsuccessful. Either cardholder or card issuing bank is not 3D enrolled/ready. | | 02 | MasterCard | 3D card authentication is successful. Both cardholder and card issuing bank are 3D enabled. | | 05 | Visa, American Express, JCB | 3D card authentication is successful. Both cardholder and card issuing bank are 3D enabled. | | 06 | Visa, American Express, JCB | 3D card authentication is unsuccessful. Either cardholder or card issuing bank is not 3D enrolled/ready. | | 07 | Visa, American Express, JCB | Authentication is unsuccessful or not attempted. The credit card is either a non-3D card or card issuing bank does not handle it as a 3D transaction. Some Acquirers/Gateways have different translation for the ECI parameter values, we recommend contacting your Acquirer/Gateway for more details. | CreditGuard is one of such gateways, which requires translating the ECI values in case of MasterCard brands, you can find the mapping below: | PayMe value | CreditGuard value | | ----------- | ------------------- | | 00 | 7 | | 01 | 6 | | 02 | 5 | | Other | Keep original value | ## Create a sale with dynamic 3DS This option will require the seller the signup to the 3DS service before he will be able to process transactions with 3DS. When the seller is approved, as part generate-sale command, you will need add the following to the generate-sale request: ```json "services": [ { "name": "3DSecure", "settings": { "active": false } } ] ```