Segpay 3DSecure Implementation Guide

This guide shows you how to add 3D Secure (3DS) payment protection using Segpay’s Merchant Plug-In (MPI), an added layer of security for online card payments. The Segpay MPI manages the secure authentication process, including browser interactions and cardholder prompts, simplifying integration for merchants. By following these instructions, you can enhance payment security without managing complex authentication processes yourself.

The JavaScript code provided in this guide will handle the necessary steps to protect your business and customers from fraud.

Simplified Process

Follow the steps below to integrate this process into your payment page.

Step 1: Generate a JWT

Generate a JSON Web Token (JWT) on your server to securely communicate with the Segpay MPI. JWTs, based on the RFC-7519 standard, allow for secure data exchange.

The required JWT for Segpay MPI uses HS256 encryption. Refer to the official JWT website to find libraries for your programming language.

When adding the JWT payload to your payment page, it must include the following:

Copy

JSON

{
'MerchantCode': '<Segpay Provided Merchant Identifier>',
'OrderDetails': {
    'OrderNumber': '<unique order number>'
 }
}

MerchantCode: An identifier provided by Segpay and used as the JWT issuer when encrypting and signing the JSON web token.
OrderNumber A unique merchant-defined identifier (up to 50 alphanumeric characters). This prevents malicious reuse of tokens.

Step 2: Insert Segpay Javascript Library

Insert the Segpay MPI Javascript library into your payment page:

Copy

HTML

<script src="https://secure3d.segpay.com/js/v3/Secure3D.js" >

Step 3: Initialize Segpay Javascript Library

After including the library, initialize it using the MerchantCode and server-generated JWT. Perform this initialization before the cardholder interacts with the page, preferably during the document.ready event.

Example:

Copy

JavaScript

var Secure = new Secure3D();
Secure.logging(true);
Secure.setup( ‘<merchant code>’, ‘<jwt>’ );
Secure.enableBinDetection('CardNumberFieldID');  # where CardNumber is the ID of the field accepting the Credit Card Number

JWT Notes

An example of generating a JWT in php:

Copy

PHP

use Lcobucci\JWT\Builder;
use Lcobucci\JWT\Signer\Hmac\Sha256;

$jwt = (new Builder())->setIssuer($merchantcode)
->setIssuedAt($currentTime) // Configures the time that the token was issued (iat claim)
->setExpiration($currentTime + $expireTime) // Configures the expiration time of the token (exp claim). Suggest at least 15 minutes, no more than 2 hours
->set('Payload', $order) // Configures a new claim, called "Payload", containing the OrderDetails
->set('ObjectifyPayload', true) // Required to be true
->sign(new Sha256(), $secureKey) // Sign with API Key
->getToken();

The secureKey value is provided by Segpay Support Team along with the MerchantCode.

Step 4: Subscribe to Events

Add JavaScript event handlers to capture the authentication flow results. This should be done after initializing the library but before the card holder’s payment submission. See Appendix A for details on the object passed into this function.

Example:

Copy

JavaScript

Secure.on('payments.validated', function(data,jwt,callback) {
// Event fired to signify the authentication flow is complete
// variable data contains authentication results
// continue with submitting payment info to merchant backend
});
Secure.on('payments.noAction', function(data) {
// Event fired to signify the card does not require further authentication
// variable data contains authentication results
// continue with submitting payment info to merchant backend
});

Step 5: Perform Authentication

Authenticate the cardholder using the Segpay MPI before submitting payment information to the Segpay Gateway. This authentication typically happens when a user clicks a button or submits a form. To authenticate, create an order object (Appendix B) containing the payment information and call Secure.do3D with that object.

Example:

Copy

JavaScript

var order ={
   "Consumer":{
      "Email1":"email@test.com",              // EITHER Email1 OR BillingAddress.Phone REQUIRED
      "BillingAddress":{
         "Phone": "8005551212",               // EITHER Email1 OR BillingAddress.Phone REQUIRED
         "FullName":"John Smith",             // EITHER FullName
         "FirstName":"John",                  // OR FirstName & LastName REQUIRED
         "LastName":"Smith",
         "Address1":"123 Main St",            // REQUIRED
         "City":"Anytown",                    // REQUIRED
         "State":"MI",                                                
         "PostalCode":"40183",                // REQUIRED
         "CountryCode":"US"                                        
      },
      "Account":{
         "AccountNumber":“4111111111111111”,  // REQUIRED 
         "ExpirationMonth":12,                // REQUIRED
         "ExpirationYear":2019,               // REQUIRED
         "CardCode":123,                      // REQUIRED
         "NameOnAccount":"JOHN SMITH"
      }
   },
   "OrderDetails":{
      "Amount":"39.99",                    // REQUIRED
      "CurrencyCode":"840"                 // REQUIRED, 3-digit ISO-4217 value
   }
 };

Secure.do3D( order );

Step 6: Authorization

After authentication (payments.validated or payments.noAction event), submit the payment information to the Segpay Gateway for authorization of the transaction. Please see the Gateway Integration Guide for more information on the authorization gateway.

3D-Secure-Specific Parameters

Parameter	Description
ThreeDService	Indicates the source of the data to be provided. Should be set to “CARDINAL” as the Segpay gateway has standardized on the data as provided by the Cardinal MPI.
ThreeDSecure	Contains the “data” object from the payments.validated event in javascript. Value is JSON object that is then Base64 encoded.
SecureGrandFathered	Send a value of 1 to indicate this transaction is merchant-initiated and should be considered grandathered in (original transaction occurred before PSD regulations went into effect). Send a value of 0 or no value to indicate it is not grandathered.
SecureTransactionID	Used for merchant-initiated transactions to indicate the previous transaction where Secure 3D authentication was performed. Send the Segpay TransactionID from a previous transaction.

Example authorization request:

Copy

XML

<?xml version="1.0" encoding="UTF-8"?>
<data>
   <auth AccountID="12345D" AccountPassword="password123" />
   <authrequest RequestID="1" AccountID="12345" CardNumber="4000000000001000" CVV="123" ExpDate="2022-12-01" Email="test@test.com" Address1="123 Main St " City="Anytown" State="IL" Zip="40155" Country="840" ProductCode="12345-100000-101" MerchantCode="DEMO20003" Amount="1.00" Currency="USD" SecureTransactionID="1485261716" SecureGrandFathered="0" ThreeDService="CARDINAL" ThreeDSecure="eyJWYWxpZGF0ZWQiOiIiLCJBY3Rpb25Db2RlIjoiTE9PS1VQIiwiQUNTVXJsIjo iIiwiUGF5bG9hZCI6IiIsIlRyYW5zYWN0aW9uSWQiOiJTNnV4OFJsMEpwUlR0WG5qQ0o5MCIsIlJl YXNvbkNvZGUiOiIiLCJSZWFzb25EZXNjIjoiIiwiQ2FyZGhvbGRlckluZm8iOiIiLCJBQ1NSZW5kZ XJpbmdUeXBlIjoiIiwiQXV0aGVudGljYXRpb25UeXBlIjoiIiwiQ2hhbGxlbmdlUmVxdWlyZWQiOi IiLCJTdGF0dXNSZWFzb24iOiIiLCJFcnJvckRlc2NyaXB0aW9uIjoiIiwiRXJyb3JOdW1iZXIiOiI wIiwiT3JkZXJJZCI6IjgwMTA4NzA0NzY5NDYxMzkiLCJUcmFuc2FjdGlvblR5cGUiOiIiLCJDYXJk QnJhbmQiOiJNQVNURVJDQVJEIiwiQ2FyZEJpbiI6IjUyMDAwMCIsIlJhd0FDU1VybCI6IiIsIlN0Z XBVcFVybCI6IiIsIkNhdnZBbGdvcml0aG0iOiIiLCJNZXJjaGFudFJlZmVyZW5jZU51bWJlciI6Ii IsIkRlY291cGxlZEluZGljYXRvciI6IiIsIlRoaXJkUGFydHlUb2tlbiI6IiIsIlRva2VuIjoiIiw iV2hpdGVMaXN0U3RhdHVzIjoiIiwiV2hpdGVMaXN0U3RhdHVzU291cmNlIjoiIiwiTmV0d29ya1Nj b3JlIjoiIiwiQXV0aG9yaXphdGlvblBheWxvYWQiOiIiLCJQYXltZW50Ijp7IkV4dGVuZGVkRGF0Y SI6eyJFbnJvbGxlZCI6IlkiLCJDQVZWIjoiWTJGeVpHbHVZV3hqYjIxdFpYSmpaV0YxZEdnPSIsIkVDSUZsYWciOiIwMiIsIlRocmVlRFNWZXJzaW9uIjoiMi4yLjAiLCJQQVJlc1N0YXR1cyI6IlkiLCJ TaWduYXR1cmVWZXJpZmljYXRpb24iOiJZIiwiWElEIjoiIiwiVUNBRkluZGljYXRvciI6IiIsIkFD U1RyYW5zYWN0aW9uSWQiOiJjMWYyMTY2My1iYTcxLTQ4YTUtYTIwMy1mYWE2Yjg4ZTY5NTgiLCJUa HJlZURTU2VydmVyVHJhbnNhY3Rpb25JZCI6IjA0Mjk2MTZjLTY0OTYtNGEyMS04NWE1LTg2OGRkMm I3NjViZCIsIkRTVHJhbnNhY3Rpb25JZCI6IjM5ZDIyZjM4LTQyMDgtNDBiZC04ODJlLWUyMTkxOTB iNGJmZSJ9fX0=" />
</data>

PSD2 and Strong Customer Authentication (SCA)

PSD2 (Revised Payment Services Directive) is an EU regulation governing electronic and non-cash payments. It requires Strong Customer Authentication (SCA) to enhance online payment security and reduce fraud.

SCA applies when both the business and cardholder's bank are in the European Economic Area (EEA), though certain transactions may be exempt or out of scope.

Value	Description
LowValue	Transactions under €30 are exempt from Strong Customer Authentication (SCA). However, SCA becomes required if either the total unauthenticated transactions exceed €100 or if a card is used for five consecutive transactions without SCA.
RiskAnalysis	A payment's low-risk status depends on the average fraud levels of both the card issuer and acquirer processing the transaction: + 0.13% to exempt transactions below €100 + 0.06% to exempt transactions below €250 + 0.01% to exempt transactions below €500
Recurring	Recurring transactions with a fixed amount are exempt beginning with the 1 st rebill. Only the initial transaction requires SCA.
TrustedBeneficiary	Customers can assign businesses to a whitelist of trusted beneficiaries. Whitelisted merchants are exempt from SCA.
MIT	When customers are not present during checkout, payments made with saved cards may qualify as merchant-initiated transactions. To enable this, you must authenticate the card during the first payment and obtain customer agreement for future charges. Merchant-initiated transactions—both fixed and variable amounts—are exempt from Strong Customer Authentication (SCA).
AnonymousCard	A transaction processed using an anonymous card can only be identified by the issuing bank, not by the customer.
CorporateCard	When a legal entity (such as a business) rather than an individual consumer initiates the transaction and processes it through a secure, dedicated payment protocol.

Disabling Automatic Exemptions

To disable automatic exemptions from both the Segpay gateway and acquiring/issuing banks, use these parameters:

SCAExemptionOverride - Setting this to "Y" disables all automatic exemptions. Instead, the system will only use the value specified in SCAExemption.
SCAExemption – See Table below for values and definitions:

Use the following optional SCA Exemption parameters in your authorization request:

Copy

XML

SCAExemptionOverride=”Y”
SCAExemption=”LowValue”

Issuer Mandated Authentication

Sometimes during authorization, an issuer may require strong authentication—even if it wasn't required during the initial 3D Secure authentication/lookup phase. In these cases, the Segpay gateway returns a 3009 - Strong Authentication Required response code. When this happens, the merchant needs to initiate an alternative 3D Secure flow that forces authentication, as detailed below:

Copy

var order ={
   "Consumer":{
      "Email1":"email@test.com",              // REQUIRED
      "BillingAddress":{
         "FullName":"John Smith",             // EITHER FullName
         "FirstName":"John",                  // OR FirstName & LastName REQUIRED
         "LastName":"Smith",
         "Address1":"123 Main St",            // REQUIRED
         "City":"Anytown",                    // REQUIRED
         "State":"MI",                                                
         "PostalCode":"40183",                // REQUIRED
         "CountryCode":"US"                                        
      },
      "Account":{
         "AccountNumber":“4111111111111111”,  // REQUIRED 
         "ExpirationMonth":12,                // REQUIRED
         "ExpirationYear":2019,               // REQUIRED
         "CardCode":123,                      // REQUIRED
         "NameOnAccount":"JOHN SMITH"
      }
   },
   "OrderDetails":{
      "Amount":"39.99",                    // REQUIRED
      "CurrencyCode":"840"                 // REQUIRED, 3-digit ISO-4217 value
   }
 };
  
// Normal flow:
// Secure.do3D( order );
  
// Authentication mandated flow:
Secure.forceAuthentication( order );

Advanced Features

If merchants want more control over the authentication process, additional steps can be taken to check for any required authentication steps before they are executed in the cardholder's browser.

To do this, an additional parameter may be provided to the Secure.do3D method providing a callback function to run upon completion of the lookup step in the authentication process.This interpret lookup function allows merchants to perform any desired additional steps. To resume the authentication flow, simply call Secure.continue.

For example, to perform authentication only for cards enrolled in Secure 3D 2.0 or higher:

Copy

JavaScript

Secure.do3D(order, function(lookupresponse) {
    if (lookupresponse.ThreeDVersion >= 2) {
        Secure.continue();
    }
};);

Appendices

Appendix A: Order Object (Full Example)

Copy

JavaScript

{
    "Authorization": {
        "AuthorizeAccount": false
    },
    "Cart": [{
        "Name": "",
        "SKU": "",
        "Quantity": "",
        "Description": ""
    }],
    "Consumer": {
        "Email1": "",
        "Email2": "",
        "ShippingAddress": {
            "FullName": "",
            "FirstName": "",
            "MiddleName": "",
            "LastName": "",
            "Address1": "",
            "Address2": "",
            "Address3": "",
            "City": "",
            "State": "",
            "PostalCode": "",
            "CountryCode": "",
            "Phone1": "",
            "Phone2": ""
        },
        "BillingAddress": {
            "FullName": "",
            "FirstName": "",
            "MiddleName": "",
            "LastName": "",
            "Address1": "",
            "Address2": "",
            "Address3": "",
            "City": "",
            "State": "",
            "PostalCode": "",
            "CountryCode": "",
            "Phone1": "",
            "Phone2": ""
        },
        "Account": {
            "AccountNumber": 0,
            "ExpirationMonth": 0,
            "ExpirationYear": 0,
            "CardCode": 0,
            "NameOnAccount": ""
        }
    },
    "Options": {
        "EnableCCA": ""
    },
    "OrderDetails": {
        "OrderNumber": "",
        "Amount": "",
        "CurrencyCode": "",
        "OrderDescription": "",
        "OrderChannel": "",
        "TransactionId": ""
    },
    "Token": {
        "Token": "",
        "CardCode": 0,
        "ExpirationMonth": 0,
        "ExpirationYear": 0
    }
}

Appendix B: Event Data Object Specifications

Field	Type	Description
ActionCode	AN(30)	The resulting state of the transaction. Possible values: SUCCESS - The transaction resulted in successful authentication. NOACTION - The API calls were completed and there are no further actionable items to complete. This can indicate that the card holder is not enrolled in 3-D Secure. FAILURE - The transaction resulted in an error, typically due to the user failing to authenticate ERROR - A service level error was encountered. These are generally reserved for connectivity or API authentication issues, for example, if your JWT was incorrectly signed, or the MPI services are currently unreachable.
Authorization	Authorization Object	An object related to tokenization.
Authorization Processor
ProcessorOrderId	AN(50)	The OrderId returned back from the Processor.
ProcessorTransactionId	AN(50)	The Transaction Identifier returned back from the Processor.
ReasonCode	AN(255)	Third party error number. A non-zero value represents the error encountered while attempting the process the message request.
ReasonDescription	(AN255)	The third party description for the associated ReasonCode.
Consumer
Email1	AN(255)	Consumer's primary E-mail Address.
Email2	AN(255)	Consumer's alternate E- mail Address.
ShippingAddress	Address Object	Consumer's Shipping Address.
BillingAddress	Address Object	Consumer's Billing Address.
Account	Account Object	Consumer's Account Information.
ErrorNumber	AN(255)	Application error number. A non-zero value represents the error encountered while attempting the process the message request.
ErrorDescription	AN(255)	Application error description for the associated error number.
Payment
BillingAddress	Address	Consumers billing address. This field may not be present in every payment brand.
ExtendedData	Payment Extension Object	(See Payment Extension Object section below.)
ProcessorTransactionId	AN(255)	The Transaction Identifier returned back from the Processor.
OrderId	AN(255)	Centinel generated order identifier. Used to link multiple actions (authorize, capture, refund, etc) on a single order to a single identifier. Mod-10 compliant and unique BIN range to CardinalCommerce services.
OrderNumber	AN(255)	Order Number or transaction identifier from the Merchant website.
ShippingAddress	Address	Consumers shipping address. This field may not be present in every payment brand.
Type	AN(50)	The payment type of this transaction. Possible Values: + CCA + Paypal + Wallet + VisaCheckout + ApplePay + DiscoverWallet
ReasonDescription	AN(255)	Third party error description for the associated ReasonCode.
Validated	boolean	This value represents whether transaction was successfully or not.
Token	Token Object	The token details associated with this transaction

Payment Extension Object

Field	Type	Description
Enrolled	AN(1)	Status of Authentication ligibility. Possible Values: Y = Yes- Bank is participating in 3D Secure protocol and will return the ACSUrl N = No - Bank is not participating in 3D Secure protocol U = Unavailable - The DS or ACS is not available for authentication at the time of the request B = Bypass- Merchant authentication rule is triggered to bypass authentication in this use case NOTE: If the Enrolled value is NOT Y, then the Consumer is NOT eligible for Authentication.
CAVV	AN(40)	CAVV = Cardholder Authentication Verification Value AVV = Authentication Verification Value UCAF = Universal Cardholder Authentication Field This value should be appended to the authorization message signifying that the transaction has been successfully authenticated. This value will be encoded according to the merchant’s configuration in either Base64 encoding or Hex encoding. A Base64 encoding merchant configuration will produce values of 28 or 32 characters. A Hex encoding merchant configuration will produce values of 40 or 48 characters. The value when decoded will either be 20 bytes for CAVV or 20 or 24 bytes if the value is AAV (MasterCard UCAF).
ECIFlag	AN(40)	Electronic Commerce Indicator (ECI). The ECI value is part of the 2 data elements that indicate the transaction was processed electronically. This should be passed on the authorization transaction to the gateway/processor. See Brand ECI definitions section below
PAResStatus	AN(1)	Transaction status result identifier. Possible Values: + Y – Successful Authentication + N – Failed Authentication + U – Unable to Complete Authentication + A – Successful Attempts Transaction
SignatureVerification	AN(1)	Transaction Signature status identifier. Possible Values: + Y - Indicates that the signature of the PARes has been validated successfully and the message contents can be trusted. + N - Indicates that the PARes could not be validated. This result could be for a variety of reasons; tampering, certificate expiration, etc., and the result should not be trusted.
XID	AN(40)	Transaction identifier resulting from authentication processing. NOTE: Gateway/Processor API specification may require this value to be appended to the authorization message. This value will be encoded according to the merchant’s configuration in either Base64 encoding or Hex encoding. A Base64 encoding merchant configuration will produce values of 28 characters. A Hex encoding merchant configuration will produce values of 40 characters.
UCAFIndicator	AN(1)	Universal Cardholder Authentication Field (UCAF) Indicator value provided by the issuer. Possible Values: 0 - Non-SecureCode transaction, bypassed by the Merchant 1 - Merchant-Only SecureCode transaction 2 - Fully authenticated SecureCode transaction NOTE: This field is only returned for MasterCard transactions
ACSTransactionId	AN(36)	Unique transaction identifier assigned by the ACS to identify a single transaction.
ThreeDSSeverTransactionId	AN(36)	Unique transaction identifier assigned by the 3DS Server to identify a single transaction.
DSTrasactionID	AN(36)	Unique transaction identifier assigned by the Directory Server (DS) to identify a single transaction. NOTE: Required for Mastercard Identity Check transaction in Authorization.

Brand ECI Definitions

Mastercard	Visa	Amex	JCB	Diners Club	ELO
02	05	05	05	05	05
01	06	06	06	06	06
00	07	07	07	07	07