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/v3/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]", // 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 );
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 Value | Definition |
|---|---|
| LowValue | Transactions 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. |
| RiskAnalysis | The 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 |
| 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 | Payments 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. |
| AnonymousCard | A transaction processed using an anonymous card can only be identified by the issuing bank, not by the customer. |
| CorporateCard | When 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
| 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. |
| AuthorizationProcessor | ||
| 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 | AN(255) | The thrid 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) | 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). |
| 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. |
| ThreeDSServerTransactionId | AN(36) | Unique transaction identifier assigned by the 3DS Server to identify a single transaction. |
| DSTransactionId | 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 |
Updated about 1 month ago