Skip to main content

Documentation Index

Fetch the complete documentation index at: https://bancofcalifornia-preview.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

3-D Secure can help you avoid fraudulent transactions by authenticating transactions before submitting them to the gateway for processing. When a credit card enrolled in 3-D Secure is submitted it will ensure that the customer is the owner of the credit card. Their bank will first collect a fingerprint of their device. On some occasions, this fingerprint is sufficient and the customer is immediately authenticated. This flow is often called “frictionless” because it does not require additional inputs from the user and does not interrupt the customer’s checkout flow. On other occasions, the bank will issue a challenge to the customer requiring them to submit a password or other information to validate themselves. This flow is often called “step up authentication”.

​
3-D Secure Variables

When a customer successfully authenticates a transaction, the library may provide you the following, which you should submit to the payment API:
VariableDescriptionWhen Received
cavvCardholder Authentication Verification Value The value that signifies that a customer was successfully authenticated.On all successful authentications
xidA transaction identifier from authentication processingOccasionally provided for some card brands
directory_server_idA transaction identifier assigned by the directory server.On all successful 3DS2 authentications
eciA number that indicates the result of the attempt to authenticate the cardholder. Values are dependent on the card brand.On successful authentications
cardholder_authA string describing if a customer was successfully verified or attempted. “verified” indicates that a cardholder’s bank successfully verified the user. “attempted” indicates that a cardholder is enrolled in 3DS, but their bank does not support 3DS. Examples: verified, attemptedOn successful authentications
three_ds_versionDetermines which version of 3DS was used. Examples: 1.0.2, 2.1.0, 2.2.0On all successful authentications
cardholder_info*Text provided by the ACS/Issuer to Cardholder. Example: Additional authentication is needed for this transaction, please contact (Issuer Name) at xxx-xxx-xxxx.Occasionally provided for frictionless transactions
* cardholder_info should not be passed into the API and should be displayed to the customer if a value is present.

​
Handling in Gateway.js

Using Collect.js or Customer Vault? See “Running 3DS with Collect.js” or “Running 3DS with Customer Vault” guides for information about integrating with other gateway services. example.html 
<html>
    <body>
    <script src="https://secure.networkmerchants.com/js/v1/Gateway.js"></script>
    <script>
        // Initialize Gateway.js
        const gateway = Gateway.create('collect_checkout_0000000000000000000000');

        // Initialize the ThreeDSService
        const threeDS = gateway.get3DSecure();

        // Create a 3DS Frame
        // This will start out 0px x 0px during fingerprinting.
        // If the customer is prompted to complete a challenge, it will resize automatically.
        const options = {
            cardNumber: "4111111111111111",
            cardExpMonth: "01",
            cardExpYear: "2024",
            currency: 'USD',
            amount: '10.00',
            email: 'none@example.com',
            phone: '8008675309',
            city: 'New York',
            state: 'NY',
            address1: '123 First St.',
            country: 'US',
            firstName: 'Jane',
            lastName: 'Doe',
            postalCode: '60001'
        };

        const threeDSecureInterface  = threeDS.createUI(options);

        // Mount the threeDSecureInterface to the DOM
        // This begins the collection of 3DS data.
        threeDSecureInterface.start('body');

        // Listen for the threeDSecureInterface to ask the user for a password
        threeDSecureInterface.on('challenge', function(e) {
            console.log('Challenged');
        });

        // Listen for the threeDSecureInterface to provide all the needed 3DS data
        threeDSecureInterface.on('complete', function(e) {
            fetch('direct-post-back-end.php', {
                method: 'POST',
                body: JSON.stringify({
                    ...options,
                    cavv: e.cavv,
                    xid: e.xid,
                    eci: e.eci,
                    cardHolderAuth: e.cardHolderAuth,
                    threeDsVersion: e.threeDsVersion,
                    directoryServerId: e.directoryServerId,
                    cardHolderInfo: e.cardHolderInfo,
                })
            })
        });

        // Listen for the threeDSecureInterface to indicate that the customer
        // has failed to authenticate
        threeDSecureInterface.on('failure', function(e) {
            console.log('failure');
            console.log(e);
        });

        // Listen for any errors that might occur.
        gateway.on('error', function (e) {
            console.error(e);
        })
    </script>
    </body>
</html>
direct-post-back-end.php 
<?php
$jsonContent = json_decode(file_get_contents('php://input'));

$fields = array(
    'security_key' => '01234567890123456789012345678901',
    'ccnumber' => $jsonContent->cardNumber,
    'ccexp' => $jsonContent->cardExpMonth . substr($jsonContent->cardExpYear, -2),
    'amount' => '10.00',
    'email' => $jsonContent->email,
    'phone' => $jsonContent->phone,
    'city' => $jsonContent->city,
    'address1' => $jsonContent->address1,
    'country' => $jsonContent->country,
    'first_name' => $jsonContent->firstName,
    'last_name' => $jsonContent->lastName,
    'zip' => $jsonContent->postalCode,
    'cavv' => $jsonContent->cavv,
    'xid' => $jsonContent->xid,
    'eci' => $jsonContent->eci,
    'cardholder_auth' => $jsonContent->cardHolderAuth,
    'three_ds_version' => $jsonContent->threeDsVersion,
    'directory_server_id' => $jsonContent->directoryServerId,
    'cardholder_info' => $jsonContent->cardHolderInfo
);

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://secure.networkmerchants.com/api/transact.php',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => $fields
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
1

Initialize Gateway.js

Start by initializing Gateway.js with your public key. You can view your existing public keys or create a new one in the merchant portal’s Security Keys.
2

Initialize the ThreeDSService

Initialize the ThreeDSService by calling gateway.getThreeDSService().
3

Create the interface object

Create an interface object with the details of the transaction. The details should include cardNumber, cardExpMonth, cardExpYear, currency, amount, email, city, address1, country, firstName, lastName, and postalCode. The created interface will emit events that your application can subscribe to in order to respond to various results from processing.
4

Mount the interface to the DOM

Mount the interface to the DOM by providing a selector. The frame will be mounted inside the provided element. This starts the authentication process.JavaScript frameworks such as React, Vue, or Angular may control the DOM in such a way that would cause the frame to become detached from the DOM. You may need to prevent them from managing the mount point in order to ensure that a mounted interface remains on the page.
5

Attach callbacks

Attach callbacks to listen for when the customer finishes authenticating themselves.
6

Send the 3DS data to your backend

Implement a callback for the complete event that sends the 3DS data to your backend.
7

Submit via the Payment API

Submit the 3DS data via the payment API with your private key.