Use encrypted CVVs for payment instruments

This topic describes how to securely collect and use encrypted CVVs for payment instruments in the FramePay JavaScript library.

When this feature is active, your customers can speed up the payment process for future transactions by choosing to securely store their payment card CVVs. The FramePay library will encrypt the customer-provided CVV with the Rebilly API and store it in the customer's web browser. The CVV is not stored on Rebilly servers and will only be usable on the browser where it was collected.

Collect CVV securely for future use

This process describes how to securely collect and store payment card CVVs for future transactions.

1. Set up FramePay

Add this code to your page to enable the FramePay library.

<link href="https://framepay.rebilly.com/framepay.css" rel="stylesheet" />
<script src="https://framepay.rebilly.com/framepay.js"></script>

2. Create a form

Create a form with fields to collect payment card information. Include fields for the cardholder's name, card number, expiration date, and CVV. Include a checkbox input to allow customers to choose to store their payment card CVVs securely.

For more information on creating checkout forms, see Checkout form and token creation.

<form>
    <fieldset>
        <div class="field">
            <label for="first">First Name</label>
            <input id="first" data-rebilly="firstName" placeholder="First Name" />
        </div>
        <div class="field">
            <label for="last">Last Name</label>
            <input id="last" data-rebilly="lastName" placeholder="Last Name" />
        </div>
        <div id="framepay-payment-card"></div>
        <div class="field">
            <label for="cvv">Store CVV for future use?</label>
            <input id="cvv" data-rebilly="enableEncryptedCVV" type="checkbox"/>
        </div>
    </fieldset>
    <button type="submit">Create payment card</button>
</form>

3. Generate the token

In the JavaScript function where FramePay is initialized, use Framepay.createToken to generate and inject the payment token into your form. Use this token to create a payment instrument.

form.addEventListener('submit', function (e) {
    e.preventDefault();
    e.stopPropagation();

    Framepay.createToken(form)
        .then(result => {
            console.log('FramePay success', result);
        })
        .catch(error => {
            console.log('FramePay error', error);
        });
});

4. Use the token

Use the generated token with any of the Rebilly SDKs to create a payment instrument with the token to be used in the future.

Collect encrypted CVV for an existing payment instrument

This process describes how to securely collect and store payment card CVVs for an existing instrument.

1. Set up FramePay

Add this code to your page to enable the FramePay library. Then, initialize the FramePay library with your publishable key and website ID. Replace the publishableKey and websiteId with your own values.

For more information, see Obtain a publishable key and Obtain your organization ID and website ID.

<link href="https://framepay.rebilly.com/framepay.css" rel="stylesheet" />
<script src="https://framepay.rebilly.com/framepay.js"></script>

(function () {
    Framepay.initialize({
        publishableKey: 'pk_sandbox_Lvl5rm8lLrtAV6iSL3CIdYLAburumF4Ld8b1KDs', // Replace with your publishable key
        websiteId: `website-123`, // Replace with your website ID
    });
})();

2. Fetch the customer's payment instruments

Use the Retrieve payment instruments API operation to fetch all customer payment instruments. This operation returns a list of payment instruments that are associated with each customer.

3. Create a form

<form>
    <fieldset>
        <div class="fields">
            <div class="field">
                <label for="cvv">CVV</label>
                <div id="cvv">
                    <!-- FramePay will inject the payment card CVV field here -->
                </div>
                <div class="error"></div>
            </div>
            <div class="field">
                <label for="cvv">Store CVV for future use?</label>
                <input id="cvv" data-rebilly="enableEncryptedCVV" type="checkbox"/>
            </div>
        </div>
    </fieldset>
    <button type="submit">Update payment card</button>
</form>

4. Generate the token

Use the Framepay.createToken function to generate a token that includes the encrypted CVV. This token can then be used to update the payment instrument with the encrypted CVV.

Pass the following required values to createToken to use the encrypted CVV:

enableEncryptedCVV: Set to true to enable encrypted CVV.
method: Set to payment-card to indicate that the token is for a payment card.
billingAddress: An object containing the billing address information.
paymentInstrument: An object containing the payment instrument information. bin, last4, expMonth, and expYear.

Framepay.createToken(form, {
    enableEncryptedCVV: true,
    method: 'payment-card',
    billingAddress: {
        address: '123 Main St', // Replace with the billing address
        city: 'Any town', // Replace with the billing city
        region: 'CA', // Replace with the billing region
        postalCode: '12345', // Replace with the billing postal code
        country: 'US' // Replace with the billing country
    },
    paymentInstrument: {
        bin: '123456', // Replace with the BIN of the payment instrument
        last4: '1234', // Replace with the last 4 digits of the payment instrument
        expMonth: '12', // Replace with the expiration month of the payment instrument
        expYear: '2025' // Replace with the expiration year of the payment instrument
    }
})
    .then(result => {
        console.log('FramePay success', result);
    })
    .catch(error => {
        console.log('FramePay error', error);
    });

5. Update the payment instrument with the token and use for a transaction

Use the token to update the payment instrument before using the payment instrument for a transaction. Use any of the Rebilly SDKs and the Update the payment instrument API operation.

Use a stored encrypted CVV

This process describes how to use an encrypted CVV for a payment card instrument that was previously created by the FramePay library.

1. Set up FramePay

For more information, see Obtain a publishable key and Obtain your organization ID and website ID.

<link href="https://framepay.rebilly.com/framepay.css" rel="stylesheet" />
<script src="https://framepay.rebilly.com/framepay.js"></script>

(function () {
    Framepay.initialize({
        publishableKey: 'pk_sandbox_Lvl5rm8lLrtAV6iSL3CIdYLAburumF4Ld8b1KDs', // Replace with your publishable key
        websiteId: `website-123`, // Replace with your website ID
    });
})();

2. Fetch the customer's payment instruments

Use the Retrieve payment instruments API operation to fetch all customer payment instruments. This operation returns a list of payment instruments that are associated with each customer.

3. Verify if the payment instrument has an encrypted CVV stored in the browser

Use the framepay.hasEncryptedCVV({ bin, last4, expMonth, expYear }) function to check if the payment instrument has an encrypted stored CVV in the customer's current web browser.

If the payment instrument has an encrypted CVV, the function returns true. If the result is true, generate the token and update the payment instrument.

If the result is false, update the payment instrument and collect the CVV.

    if (Framepay.hasEncryptedCVV({ bin, last4, expMonth, expYear })) {
        // Proceed to generate the token and update the payment instrument
    } else {
        // Handle the case where the payment instrument does not have an encrypted CVV
    }

4. Generate the token

Use the Framepay.createToken function to generate a token that includes the encrypted CVV. This token can then be used to update the payment instrument with the encrypted CVV.

Pass the following required values to createToken to use the encrypted CVV:

enableEncryptedCVV: Set to true to enable encrypted CVV.
method: Set to payment-card to indicate that the token is for a payment card.
billingAddress: An object containing the billing address information.
paymentInstrument: An object containing the payment instrument information. bin, last4, expMonth, and expYear.

Framepay.createToken(form, {
    enableEncryptedCVV: true,
    method: 'payment-card',
    billingAddress: {
        address: '123 Main St', // Replace with the billing address
        city: 'Any town', // Replace with the billing city
        region: 'CA', // Replace with the billing region
        postalCode: '12345', // Replace with the billing postal code
        country: 'US' // Replace with the billing country
    },
    paymentInstrument: {
        bin: '123456', // Replace with the BIN of the payment instrument
        last4: '1234', // Replace with the last 4 digits of the payment instrument
        expMonth: '12', // Replace with the expiration month of the payment instrument
        expYear: '2025' // Replace with the expiration year of the payment instrument
    }
})
    .then(result => {
        console.log('FramePay success', result);
    })
    .catch(error => {
        console.log('FramePay error', error);
    });

5. Update the payment instrument with the token and use for a transaction

Use the token to update the payment instrument before using the payment instrument for a transaction. Use any of the Rebilly SDKs and the Update the payment instrument API operation.

Remove encrypted CVVs

This process describes how to remove an encrypted CVV for a payment card instrument that was previously created by the FramePay library.

1. Set up FramePay

For more information, see Obtain a publishable key and Obtain your organization ID and website ID.

<link href="https://framepay.rebilly.com/framepay.css" rel="stylesheet" />
<script src="https://framepay.rebilly.com/framepay.js"></script>

(function () {
    Framepay.initialize({
        publishableKey: 'pk_sandbox_Lvl5rm8lLrtAV6iSL3CIdYLAburumF4Ld8b1KDs', // Replace with your publishable key
        websiteId: `website-123`, // Replace with your website ID
    });
})();

2. Remove encrypted CVVs

Select one of the following options:

Remove all encrypted CVVs

In the JavaScript function where FramePay is initialized, use Framepay.removeAllEncryptedCVVs to remove all stored encrypted CVVs for this website.

Framepay.removeAllEncryptedCVVs();

Remove one encrypted CVV

In the JavaScript function where FramePay is initialized, use Framepay.removeEncryptedCVV to remove a specific encrypted CVV. Pass the payment instrument details to identify which CVV to remove.

Framepay.removeEncryptedCVV({
    bin: '123456', // Replace with the BIN of the payment instrument
    last4: '1234', // Replace with the last 4 digits of the payment instrument
    expMonth: '12', // Replace with the expiration month of the payment instrument
    expYear: '2025' // Replace with the expiration year of the payment instrument
});

Update an encrypted CVV

This process describes how to update an encrypted CVV for a payment card instrument that was previously created.

1. Set up FramePay

For more information, see Obtain a publishable key and Obtain your organization ID and website ID.

<link href="https://framepay.rebilly.com/framepay.css" rel="stylesheet" />
<script src="https://framepay.rebilly.com/framepay.js"></script>

(function () {
    Framepay.initialize({
        publishableKey: 'pk_sandbox_Lvl5rm8lLrtAV6iSL3CIdYLAburumF4Ld8b1KDs', // Replace with your publishable key
        websiteId: `website-123`, // Replace with your website ID
    });
})();

1. Create a form with CVV field to update

This step is similar to collecting the encrypted CVV initially, but you will use a separated form style to capture the CVV field to update. Optionally, You can also update the other properties of the payment instrument.

Include a checkbox input to allow customers to choose to store their payment card CVVs securely.

<form>
    <fieldset>
        <div class="field">
            <label for="cvv">CVV</label>
            <div id="cvv">
                <!-- FramePay will inject the payment card CVV field here -->
            </div>
            <div class="error"></div>
        </div>
        <div class="field">
            <label for="cvv">Store CVV for future use?</label>
            <input id="cvv" data-rebilly="enableEncryptedCVV" type="checkbox"/>
        </div>
    </fieldset>
    <button type="submit">Update payment card</button>
</form>

2. Generate the token

On the JavaScript function where FramePay was initialized, trigger Framepay.createToken to generate and inject the payment token into your form. We will use this token later to update the payment instrument.

form.addEventListener('submit', function (e) {
        e.preventDefault();
        e.stopPropagation();

        Framepay.createToken(form, {
            enableEncryptedCVV: true,
            method: 'payment-card',
            billingAddress: {
                address: '123 Main St', // Replace with the billing address
                city: 'Any town', // Replace with the billing city
                region: 'CA', // Replace with the billing region
                postalCode: '12345', // Replace with the billing postal code
                country: 'US' // Replace with the billing country
            },
            paymentInstrument: {
                bin: '123456', // Replace with the BIN of the payment instrument
                last4: '1234', // Replace with the last 4 digits of the payment instrument
                expMonth: '12', // Replace with the expiration month of the payment instrument
                expYear: '2025' // Replace with the expiration year of the payment instrument
            }
        })
            .then(result => {
                console.log('FramePay success', result);
            })
            .catch(error => {
                console.log('FramePay error', error);
            });
    });

3. Use the token to update the payment instrument

Now that your FramePay token is generated, use any of the Rebilly's backend SDKs to finish the update process.

The update process only requires the id of the payment instrument you want to update and the token generated by FramePay.

Our Solutions

Products

Features

Solutions

About

Use encrypted CVVs for payment instruments

Collect CVV securely for future use

Collect encrypted CVV for an existing payment instrument

Use a stored encrypted CVV

Remove encrypted CVVs

Update an encrypted CVV

Rebilly API SDKs

Was this helpful?