====== 3D Secure and Strong Customer Authentication (SCA) ====== ~~TOC~~ Strong Customer Authentication (SCA) came into force in 2019 as part of the PSD2 regulation in Europe. In order to meet SCA requirements, you'll be required to authenticate your customers via 3D Secure to make online payments. Merchants who do not meet the requirements are at risk of having transactions rejected. Take a closer look at our **[[https://resources.worldnetpayments.com/blog/psd2-faq|F.A.Q]]** for more information on how PDS2 impacts merchants and customers. The 3D Secure verification process requires the cardholder to pass an identity check. If you're using one of our shopping carts or our hosted pages solution, there's nothing to worry about as we'll handle everything for you. However, if you have a direct integration into one of our APIs, the implementation of an initial authentication step using our MPI services will be required. The process is described in the flowchart below. 1. A ''POST'' request is sent to the MPI service provided by %CompanyName which handles the user authentication. 2. After authentication, the server will send the results in the form of a redirect to the ''MPI Receipt URL'' configured in your terminal. 3. If the authentication is successful, add the ''mpiReference'' code received from the response into the ''threeDSecure'' section of the payment request. ===== Creating MPI Request ===== To simplify 3D Secure for API integrations, %CompanyName provides a simple MPI redirect. \\ ==== Request ==== ^ **TYPE** ^ **SANDBOX URL** ^ | MPI Request | ''%PAYROC_URLMPI'' | ^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^ | processingTerminalId | Y | ^{string ''[ 4 .. 50 ] characters''} \\ Unique identifier that gateway assigned to the terminal. | | singleUseToken | Y | ^{string ''[ 128 ] characters''} \\ Unique token that the gateway assigned to the payment details. | | email | Y | ^{string ''[ 1 .. 128 ] characters''} \\ The cardholder email address.| | amount | Y | ^{number ''> 0''} \\ The total amount to be authorized including surcharge. The value is in the currency’s lowest denomination, for example, cents.| | currency | Y | ^{string ''3-char ISO 4217 code''} \\ The currency code of the transaction. | | orderId | Y | ^{string ''[ 1 .. 24 ] characters''} \\ A unique identifier for the order assigned by the merchant. | | cardholderChallenge | N | ^{string ''REQUIRED'', ''OPTIONAL''} \\ Inform whether the cardholder challenge is required or not. | ==== Request notes ==== ==ND001 - Data Encoding for Requests== All data sent to us should be correctly encoded using ''UTF-8'' as the character encoding. ==== Request sample ==== %PAYROC_URLMPI?processingTerminalId=4479001&amount=100¤cy=EUR&orderId=25&email=joe%40adomain.com&singleUseToken=1a8731f50b02e287ac0529fbce352317c089d4adc1178c1867d65114078791d3c3e13962cbab6b574769dfe9ad5397a5aa67a529ceb0b7be17751f076bbe0e4d \\ ===== Handling MPI Response ===== Once the 3D Secure check is complete, the following parameters will be forwarded to the **MPI Receipt URL** configured in your terminal ==== Response ==== The response body fields will be: ^ **FIELD** ^ **DESCRIPTION** ^ | result | ^string \\ ''A'': Approved.\\ ''D'': Declined. | | mpiReference | ^{string ''20 characters''} \\ MPI reference. If present, this value should be included in the payment request. | | orderId | ^{string ''[ 1 .. 24 ] characters''} \\ Echoed back from the request. | | status | ^string \\ ''A'': An attempt at authentication was performed.\\ ''N'': Authentication attempt not performed.\\ ''U'': Unable to authenticate.\\ ''Y'': Authentication attempted and succeeded. | | eci | ^{string ''2 characters''} \\ ''05'': Full 3D Secure authentication.\\ ''06'': Issuer and/or cardholder are not enrolled for 3D Secure.\\ ''07'': 3D Secure authentication attempt failed - numerous possible reasons (Visa only). | ==== Response sample ==== A ''GET'' request will be sent to your receipt endpoint containing the response fields in the form of query parameters: https://MPI_RECEIPT_URL?result=A&status=A&eci=06&mpiReference=d01656cf0ec3e62e3754&orderId=25 ===== Payment Request with 3D Secure ===== Now that you successfully acquired the ''mpiReference'' code, you just need to include it in your payment request within the ''threeDSecure'' section. Check out the sample below: ^ **TYPE** ^ **SANDBOX URL** ^ | Payment Request | ''%URLRestUAPIPayments'' | { "channel": "WEB", "processingTerminalId": "4479001", "order": { "orderId": "25", "currency": "EUR", "totalAmount": "100" }, "paymentMethod": { "type": "singleUseToken", "token": "1a8731f50b02e287ac0529fbce352317c089d4adc1178c1867d65114078791d3c3e13962cbab6b574769dfe9ad5397a5aa67a529ceb0b7be17751f076bbe0e4d" }, "threeDSecure": { "serviceProvider": "gateway", "mpiReference": "d01656cf0ec3e62e3754" } }