====== 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'' webhook configured in your terminal. 3. If the authentication is successful, add the ''MPIREF'' 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 | ''%URLMPI'' | ^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^ | TERMINALID | Y | ^{string ''[ 1 .. 50 ] characters''} \\ The terminal number assigned by %CompanyName. | | CARDNUMBER | Y | ^{string ''[ 12 .. 19 ] characters''} \\ The payment card number. | | CARDHOLDERNAME | Y | ^{string ''[ 1 .. 50 ] characters''} \\ The cardholder's name as it appears on the card. | | EMAIL | N | ^{string ''[ 1 .. 128 ] characters''} \\ The cardholder email address.| | CARDEXPIRY | Y | ^{string ''MMYY''} \\ Expiry date of the card. | | CARDTYPE | Y | Card type used for the transaction.\\ For more details on this, visit **[[selfcare:api_specification:special_fields_and_parameters#the_card_types|Special Fields and Parameters - Card Types]]**. | | AMOUNT | Y | ^{number ''> 0''} \\ The total amount to be authorized. | | 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. | | CVV | N | ^{string ''[ 3 .. 4 ] characters''} \\ The card's security code. | | DATETIME | Y | ^{string ''DD-MM-YYYY:HH:MM:SS:SSS''} \\ Request date and time. | | CARDHOLDER_CHALLENGE | N | ^{string ''REQUIRED'', ''OPTIONAL''} \\ Inform whether the cardholder challenge is required or not. | | HASH \\ ^{See notes: [[3d_secure#ND001 - Hash generation|ND001]]} | Y | ^{string ''[ 1 .. 128 ] characters''} \\ A HASH code formed by part of the request fields. | ==== Request notes ==== ==ND001 - Hash generation== See how to generate a hash string at **[[selfcare:api_specification:special_fields_and_parameters|Special Fields and Parameters]]**. For this specific feature, you should the following format: TERMINALID:ORDERID:CARDNUMBER:CARDEXPIRY:CARDTYPE:AMOUNT:DATETIME:SECRET \\ ==ND002 - Data Encoding for Requests== All data sent to us should be correctly encoded using ''UTF-8'' as the character encoding. ==== Request sample ==== The HTML example below shows how to build a form to request Strong Customer Authentication (SCA) from %CompanyName.

Terminal ID Terminal Secret Order ID Currency Amount DateTime Cardholder Name Email Card Number Expiry Date CVV CardType Hash

\\ ===== 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. | | MPIREF | ^{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). | | DATETIME | ^{string ''DD-MM-YYYY:HH:MM:SS:SSS''} \\ Response date and time. | | HASH \\ ^{See notes: [[3d_secure#ND001 - Hash validation|ND001]]} | ^{string ''[ 1 .. 128 ] characters''} \\ A HASH code formed by part of the response fields. || ==== Response notes ==== ==ND001 - Hash validation== A hash string is also included in the response, so that you can implement a verification logic to make sure it was sent by %CompanyName. See how to decode and validate a hash string at **[[selfcare:api_specification:special_fields_and_parameters|Special Fields and Parameters]]**. For this specific feature, you should expect the following format: RESULT:MPIREF:ORDERID:DATETIME:SECRET ==== Response sample ==== A ''GET'' request will be sent to your webhook containing the response fields in the form of query parameters: https://MPI_WEBHOOK_URL?RESULT=A&STATUS=A&ECI=06&MPIREF=d01656cf0ec3e62e3754&ORDERID=25&DATETIME=06-10-2020%3A13%3A19%3A10%3A239&HASH=3ea402c12f7a8cb0afac31cf0429a167 ===== Payment Request with 3D Secure ===== Now that you successfully acquired the ''MPIREF'' 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 | ''%URLRestAPIPayments'' | { "channel": "WEB", "terminal": "4479001", "order": { "orderId": "25", "currency": "EUR", "totalAmount": "6.45" }, "customerAccount": { "payloadType": "KEYED", "cardholderName": "Joe Bloggs", "cardDetails": { "cardNumber": "5480161234567897", "expiryDate": "1222", "cvv": "999" } }, "threeDSecure": { "serviceProvider": "GATEWAY", "mpiReference": "d01656cf0ec3e62e3754" } }