Bill1st 3DSecure Implementation Guide

Simplified Process

The simplified workflow is appropriate when the merchant wishes to give up control of the secure
authentication process to the Bill1st MPI. The Bill1st Javascript API will control the browser and interact
with the cardholder prompting for the secure authentication information as needed.

The steps needed to implement this process on a payment page can be found below:

Step 1: Generate JWT

A JSON Web Token (JWT) must be generated in server-side code to facilitate secure communication with
the Bill1st MPI. JWTs are an open, industry standard (RFC-7519), method for signing and encrypting
payloads between two parties. The JWT required by the Bill1st MPI utilizes shared key HS256
encryption. Please see the official JWT website https://jwt.io/ for more information and to find the
library for your language of choice.
The payload of the initial JWT needed on the paypage consists of:

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

MerchantCode is an identifier provided by Bill1st that will appear in the payload. This value will also be used as the issuer when encrypting and signing the JSON web token.
OrderNumber is a unique identifier specified by the merchant. This identifier can be of any format up to 50 alpha-numeric characters but may not be reused. This identifier is used to prevent malicious reuse of intercepted tokens.

Step 2: Insert Bill1st Javascript Library

The Bill1st MPI Javascript library must be inserted into the payment page:

<script src="https://secure3d.bill1st.com/js/v2/Bill1stSecure3D.js?profile=<PROFILEID>" >

The will be provided by Bill1st Merchant Support.

Step 3: Initialize Bill1st Javascript Library

Once the library is included, it must be initialized using the MerchantCode and server-generated JWT.
This should occur before the cardholder interacts with the page, it is suggested to perform this
initialization during the document.ready event.
To create a 3D secure object:

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 how to generate the JWT in 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 will be provided by Bill1st Support Team (along with your MerchantCode
    value)

Step 4: Subscribe to Events

The authentication flow relies on Javascript events to inform the caller of the results. This requires the
merchant to add event handlers for two events. This should be done AFTER initialization of the library
but before the cardholder has submitted payment. See Appendix B for details on the object passed into this function.

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

The page is now ready to perform authentication using the Bill1st MPI. Prior to submitting the payment
information to the Bill1st Gateway, the authentication API must be called to interact with the
cardholder, typically via a button click or a form submission. This is done by creating an order object
(Appendix A) with the payment information and calling Secure.do3D with that object:

var order ={
   "Consumer":{
      "Email1":"[email protected]",              // 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
   }
 };

Secure.do3D( order );

Authorization

After authentication has occurred (events payments.validated or payments.noAction have fired), the payment information is ready for submission to the Bill1st gateway for authorization of the transaction. Please see the Bill1st Integration Guide for more information on the authorization gateway. Only the 3D-Secure specifics are detailed here:

ThreeDService: indicates the source of the data to be provided. Should be set to “CARDINAL” as the Bill1st 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 Bill1st TransactionID from a previous
transaction.

Example authorization request:

<?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="[email protected]" 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 is the Revised Payment Services Directive, a new EU regulation for electronic and non-cash
payments. This version introduces the requirement for implementing Strong Customer Authentication
(SCA) to make online payments more secure and reduce fraud.
SCA is required when the business and the cardholder’s bank are located within the European Economic Area (EEA). There are, however, some out-of-scope transactions and exemptions.
If you want to send parameters to disable the automatic application of exemptions by both the Bill1st
gateway and the acquiring/issuing banks, use the following:

  • SCAExemptionOverride - If this parameter is activated with a value of "Y", then no automatic
    exemptions will be used, and the value sent in SCAExemption will always be applied.
  • SCAExemption – See Table below for values and definitions:
SCAExemption ValueDefinition
LowValueTransactions under €30 are exempt from SCA. If the total amount attempted on the card without strong authentication is higher than €100, or if five consecutive transactions have been conducted without SCA, SCA is required.
RiskAnalysisThe ability for a payment to be considered low risk is based on
the average fraud levels of 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
RecurringRecurring transactions with a fixed amount are exempt beginning with the 1 st rebill. Only the initial transaction requires SCA.
TrustedBeneficiaryCustomers can assign businesses to a whitelist of trusted beneficiaries. Whitelisted merchants are exempt from SCA.
MITPayments made with saved cards when the customer is not present in the checkout flow may qualify as merchant-initiated transactions. You need to authenticate the card on the first payment and make an agreement with the customer to charge their card at a later time. If a transaction is merchant-initiated, both fixed and variable payments will be exempt from SCA.
AnonymousCardA transaction processed using an anonymous card can only be identified by the issuing bank, not by the customer.
CorporateCardWhen the transaction is initiated by a legal person, for example, a business rather than a consumer, and it is processed through a secured dedicated payment protocol.

Example of the SCA Exemption parameters

Below is an example of the optional SCA Exemption parameters that can be sent in your auth request to the gateway:

SCAExemptionOverride=”Y”
SCAExemption=”LowValue”

Issuer Mandated Authentication

During an authorization request, an issuer may decide that strong authentication is required even though it did not make that determination during the authentication/lookup phase of 3D Secure. When this occurs, the Bill1st gateway will respond with a 3009 - Strong Authentication Required response code. The merchant should detect this has occurred and enter an alternative flow for 3D Secure which forces authentication as follows:

var order ={
   "Consumer":{
      "Email1":"[email protected]",              // 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 more control over the authentication process is desired, the merchant may perform additional steps
to determine what authentication steps will be required BEFORE they are executed in the cardholder’s
browser. 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. The interpret lookup
function can be used to take whatever additional steps the merchant may desire. When it is desired to
continue the authentication flow, simply call Secure.continue.
For example, to perform authentication ONLY when the card is enrolled in Secure 3D 2.0 or greater:

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

Appendix A: Order Object Full Example

{
    "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

FieldTypeDescription
ActionCodeAN(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.
AuthorizationAuthorization ObjectAn object related to tokenization.
AuthorizationProcessor
ProcessorOrderIdAN(50)The OrderId returned back
from the Processor
ProcessorTransactionIdAN(50)The Transaction Identifier
returned back from the
Processor.
ReasonCodeAN(255)Third party error number. A
non-zero value represents the
error encountered while
attempting the process the
message request.
ReasonDescriptionAN(255)The thrid party description for
the associated ReasonCode
------------------
Consumer
Email1AN(255)Consumer's primary E-mail
Address
Email2AN(255)Consumer's alternate E-
mail Address.
ShippingAddressAddress ObjectConsumer's Shipping
Address.
BillingAddressAddress ObjectConsumer's Billing
Address.
AccountAccount ObjectConsumer's Account
Information.
------------------
ErrorNumberAN(255)Application error number. A non-zero value
represents the error encountered while
attempting the process the message request.
ErrorDescriptionAN(255)Application error description for the associated
error number.
Payment
BillingAddressAddressConsumers billing address.
This field may not be
present in every payment
brand.
ExtendedDataPayment Extension ObjectSee Payment Extension
Object section below
ProcessorTransactionIdAN(255)The Transaction Identifier
returned back from the
Processor.
OrderIdAN(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.
OrderNumberAN(255)Order Number or
transaction identifier from
the Merchant website.
ShippingAddressAddressConsumers shipping
address. This field may not
be present in every
payment brand.
TypeAN(50)The payment type of this
transaction.
Possible Values:

+ CCA
+ Paypal
+ Wallet
+ VisaCheckout
+ ApplePay
+ DiscoverWallet
ReasonDescriptionAN(255)Third party error description for the associated ReasonCode.
------------------
ValidatedbooleanThis value represents whether transaction was
successfully or not.
TokenToken ObjectThe token details associated with this transaction

Payment Extension Object:

FieldTypeDescription
EnrolledAN(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.
CAVVAN(40)Cardholder Authentication Verification Value (CAVV)
Authentication Verification Value (AVV)
Universal Cardholder Authentication Field (UCAF).
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).
ECIFlagAN(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
PAResStatusAN(1)Transaction status result identifier.
Possible Values:

+ Y – Successful Authentication
+ N – Failed Authentication
+ U – Unable to Complete Authentication
+ A – Successful Attempts Transaction
SignatureVerificationAN(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.
XIDAN(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.
UCAFIndicatorAN(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
ACSTransactionIdAN(36)Unique transaction identifier assigned by the ACS to identify a single transaction.
ThreeDSServerTransactionIdAN(36)Unique transaction identifier assigned by the 3DS Server to
identify a single transaction.
DSTransactionIdAN(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

MasterCardVisaAmexJCBDiners ClubElo
020505050505
010606060606
000707070707