LogoLogo
System Status
  • Digital River API
  • Getting started
  • Using our services
    • Local pricing
    • Item classification
    • Subscriptions
    • e-Invoicing
  • Integration options
    • Low-code checkouts
      • Implementing a Prebuilt Checkout
      • Implementing a Components checkout
      • Offering local pricing
      • Using a shipping endpoint
      • Processing subscription acquisitions
      • Adding custom fields
      • Offering store credit
      • Displaying policies and getting consent
      • Collecting e-invoice information
      • Handling completed checkout-sessions
    • Direct integrations
      • Standard flow
      • Building checkouts
        • Checking out guest and registered customers
        • Describing line items
          • Setting the price of an item
          • Managing items with shared SKU identifiers
        • Providing address information
        • Handling shipping choice
        • Tax identifiers
        • Applying a discount
        • Setting the customer type
        • Providing the IP address
        • Selecting a currency
        • Initiating a charge
        • Setting the purchase location
        • Configuring taxes
        • Accessing regulatory fee information
        • Localizing invoices and credit memos
        • Providing an upstream identifier
        • Applying store credit
        • Handling e-invoicing requirements
        • Landed cost
        • Tax calculation inputs
        • Selling entities
        • Payment sessions
        • Applying store credit (legacy)
        • Country specs
      • Building payment workflows
        • Handling redirect payment methods
        • Handling delayed payment methods
      • Subscription acquisitions
        • Handling subscription acquisitions
        • Handling external subscription acquisitions
        • Subscription information
      • Digital River coordinated fulfillments
        • Checking inventory levels
        • Using shipping quotes
        • Reserving inventory items
        • Managing a fulfillment order
        • Cancelling a fulfillment order
    • Connectors
  • Order management
    • Processing orders
    • Handling a rejected order
    • Accessing invoices and credit memos
    • Fulfilling goods and services
    • Capturing and cancelling charges
    • Payment reauthorizations
    • Handling reversals
      • Return basics
        • Digital River coordinated returns
        • Third party coordinated returns
      • Refund basics
        • Issuing refunds
        • Refunding asynchronous payment methods
      • Disputes and chargebacks
    • Customer notifications
    • Responding to events
      • Events
        • Key event types
        • All event types
      • Webhooks
        • Creating a webhook
        • Digital River API safelist
        • Digital River signature
      • Expanding events
      • Preventing webhooks from getting disabled
    • Distributor model
  • Subscription Management
    • Managing a subscription
    • Managing an external subscription
  • Payments
    • Payment solutions
      • Drop-in payments
        • How Drop-in payments work
        • Drop-in payments integration guide
      • DigitalRiver.js with Elements
        • Elements integration guide
        • Configuring payment methods
          • Configuring Afterpay
          • Configuring Alipay+ (cross-border)
          • Configuring Alipay (domestic)
          • Configuring Amazon Pay
          • Configuring Apple Pay
          • Configuring Bancontact
          • Configuring BNP Paribas
          • Configuring BLIK
          • Configuring CCAvenue
          • Configuring Clearpay
          • Configuring Credit Cards
          • Configuring FPX Online Banking
          • Configuring Google Pay
          • Configuring iDEAL
          • Configuring Klarna
          • Configuring Konbini
          • Configuring Online Banking (IBP)
          • Configuring Online Banking (Korea Bank Transfer)
          • Configuring PayCo
          • Configuring PayPal
          • Configuring SEPA Direct Debit
          • Configuring Trustly
          • Configuring Wire Transfer
          • Common payment sources
          • Common payment objects
    • Supported payment methods
      • Afterpay
      • Alipay (domestic)
      • Alipay+ (cross-border)
      • Amazon Pay
      • Apple Pay
      • Bancontact
      • BNP Paribas
      • BLIK
      • CCAvenue
      • Clearpay
      • Credit Cards
      • FPX Online Banking
      • Google Pay
      • iDEAL
      • Klarna
      • Konbini
      • Korea Bank Transfer (Online Banking)
      • Online Banking (IBP)
      • Pay with Installments France
      • PayCo
      • PayPal
      • PayPal Billing Agreement
      • PayPal Credit
      • PayPal Pay in 3
      • PayPal Pay in 4
      • PayPal RatenZahlung (Installment Payment)
      • SEPA Direct Debit
      • Trustly
      • Wire Transfer
    • Source basics
      • Managing sources
      • Handling credit card sources
      • Retrieving sources
    • Authorization declines
    • PSD2 and SCA
      • How to ensure SCA compliance
    • Payment testing scenarios
  • Product management
    • Product basics
    • Managing SKUs
    • Using product details
    • Grouping SKUs
    • SKU-inventory item pairs
    • Managing inventory items
    • Regulatory fees
      • What are regulatory fees?
        • Fees terminology
        • Regulatory fee management
        • European regulatory fees
        • Compliance obligations
        • WEEE directive requirements
        • Copyright directive requirements
        • Compliance challenges
      • Managing regulatory fees
  • Customer management
    • Customer basics
    • Creating and updating customers
    • Setting up tax exemptions
    • Recording a customer's request to be forgotten
  • Financial reporting
    • Financials basics
    • Sales transactions
      • Returning a list of sales transactions
      • Getting a sales transaction by ID
    • Sales summaries
      • Returning a list of sales summaries
      • Getting a sales summary by ID
    • Payouts
      • Returning a list of payouts
      • Getting a payout by ID
      • Get a list of transactions included in payout by ID
  • Developer resources
    • Digital River API reference
    • DigitalRiver.js reference
      • Including DigitalRiver.js
      • Initializing DigitalRiver.js
      • DigitalRiver object
      • Elements
        • Amazon Pay element
        • Apple Pay elements
        • Google Pay elements
        • IBAN element
        • iDEAL element
        • Konbini elements
        • Compliance element
        • Offline Refund elements
        • Online Banking elements
        • Tax Identifier element
        • Invoice attribute element
        • Delayed Payment Instructions element
        • PayPal elements
      • Guidelines for capturing payment details
      • Security
      • Digital River payment objects
      • Error types, codes, and objects
    • DigitalRiverCheckout.js reference
      • Including DigitalRiverCheckout.js
      • Initializing DigitalRiverCheckout.js
        • DigitalRiverCheckout configuration object
      • DigitalRiverCheckout object
        • Configuring Prebuilt Checkout
          • Performing actions
          • Defining experience
        • Components
          • Configuring components
          • Address component
          • Shipping component
          • Tax identifier component
          • Invoice component
          • Wallet component
          • Payment component
          • Compliance component
          • Order summary component
          • Thank you component
        • Rendering a checkout button
          • Performing actions on the checkout button
        • Determining the checkout's status
      • Accessing country and currency
    • DynamicPricing.js reference
    • Postman collection
  • administration
    • Sign in
    • Digital River Dashboard
      • Digital River Dashboard quick start guide
      • Key features
      • Reset your password
      • Test and production environments
      • Account
        • Adding an account
        • Switching accounts
        • Account access
      • Profile settings
        • Viewing your personal information
        • Changing your password
        • Updating your phone number
        • Enabling multi-factor authentication
      • Finance
        • Payouts
          • Viewing your payout details
          • Filtering your payouts
          • Exporting your payouts
        • Sales summaries
          • Viewing your sales summaries details
          • Filtering your sales summaries
          • Exporting your sales summaries
          • Exporting your sales summary details
        • Transactions
          • Viewing your transaction details
          • Filtering your transactions
          • Exporting your transactions
      • Order management
        • Orders
          • Searching for orders
          • Filtering your orders
          • Viewing the order details
          • Cancelling items
          • Fulfilling items
          • Downloading an invoice
          • Downloading a credit memo
          • Creating shipping labels
          • Recording a customer's request to be forgotten
          • Viewing returns and refunds
          • Creating a return
          • Accepting a return
          • Creating a refund
          • Viewing the order's timeline
        • Checkouts
          • Searching for checkouts
          • Filtering your checkouts
          • Viewing the checkout details
        • Prebuilt Checkout links
          • Generate Prebuilt Checkout links
          • View and work with Prebuilt Checkout link details
          • Add a customer during Prebuilt Checkout
          • Add a product during Prebuilt Checkout
      • Customers
        • Viewing customer details
        • Searching for customers
        • Filtering your customers
        • Editing account information
        • Adding a customer
        • Tax IDs and certificates
          • Adding a tax certificate
          • Adding a tax ID
          • Deleting a tax ID
        • Metadata
          • Adding metadata
          • Editing metadata
        • Manage subscriptions from the Customer Details page
        • Disabling a customer
        • Recording a customer's request to be forgotten
        • Deleting a customer
      • Catalog
        • SKUs
          • Viewing the SKU details
          • Searching for SKUs
          • Filtering your SKUs
          • Adding a SKU
          • Editing a SKU
          • Deleting a SKU
          • Adding a fee to a SKU
          • Editing a fee
          • Deleting a fee
          • Viewing product tariff codes
        • Managing customer subscriptions from Digital River Dashboard
      • Developers
        • API keys
          • Updating your API version
          • Getting your API keys
          • Changing the API version for your key
          • Creating a restricted key
          • Editing a restricted key
          • Deleting a restricted key
          • Rotating keys
        • Webhooks
          • Creating a webhook
          • Editing a webhook
          • Deleting a webhook
          • Rotating a webhook's secret
        • API logs
          • Filtering the API log
          • Viewing the API log details
        • Event logs
          • Filtering the events log
          • Viewing the event details
      • Settings
        • Users and roles
          • Roles
          • Searching for a user by name or email
          • Filtering your users and roles
          • Adding a user
          • Editing a user
          • Deleting a user
        • Prebuilt Checkout
        • Payment methods
          • Viewing your payment methods
          • Viewing payment method details
            • Enabling currencies
            • Managing countries
          • Enabling or disabling a payment method
  • General Resources
    • eCompass
    • eCompass documentation
    • Release notes
      • 2024
      • 2023
      • 2022
      • 2021
      • 2020
      • 2019
    • Standards and certifications
      • Certification process
      • Compliance requirements
      • Documentation requirements
      • Integration checklists
        • Admin portal
        • Products and SKUs
        • Customers and tax exemptions
        • Checkouts, payment sources, and orders
        • Disclosures, compliance statements, and emails
        • Fulfillments and cancellations
        • Customer portal
        • Order refund synchronization
        • Reversals
        • Error handling
      • Test and use cases
    • Commerce infrastructure
    • Versioning
    • Glossary
Powered by GitBook
On this page
  • element.mount();
  • element.on();
  • Blur
  • Cancel
  • Change
  • Click
  • Focus
  • Ready
  • Return
  • Shipping address change
  • Shipping option Change
  • Source
  • Element functions
  • element.blur();
  • element.clear();
  • element.focus();
  • element.destroy();
  • element.unmount();
  • element.update(options);
  • Styling an element container
  • Custom classes
  • Custom styles
  • Pseudo-classes
  • Other customizable attributes
  1. Developer resources
  2. DigitalRiver.js reference

Elements

Learn how to customize and stylize elements to seamlessly integrate them into your user experience or purchase flow.‌

PreviousDigitalRiver objectNextAmazon Pay element

Last updated 8 months ago

An Element is a UI component that creates to collect sensitive customer information without having the data touch your servers. You can customize and stylize these components to seamlessly integrate them into your user experience or purchase flow. The library collects and tokenizes the data contained in these elements without exposing you to PCI-compliance liability.‌

element.mount();

Use this function to place the created elements on your page. The function accepts an identifier of a container div. The library will load the created element within the specified container.

<form id="payment-form">
    <div id="card-number"></div>
    <div id="card-expiration"></div>
    <div id="card-cvv"></div>
    <button type="submit">Submit</button>
</form>


cardNumber.mount('card-number');
cardExpiration.mount('card-expiration');
cardCVV.mount('card-cvv');

element.on();

Use this function to listen to events that you can use to build and enhance your purchase flow.

Event
Trigger When
Applies To

The element has lost focus.

cardnumber, cardexpiration, cardcvv, onlinebanking

The customer has canceled the experience.

applepay, googlepay

The element's state has changed.

cardnumber, cardexpiration, cardcvv, onlinebanking

A shopper clicked the element's button.

applepay, googlepay

The element has gained focus.

cardnumber, cardexpiration, cardcvv, onlinebanking

The created element is loaded and ready to accept an update request.

cardnumber, cardexpiration, cardcvv, applepay, googlepay, onlinebanking

The customer has pressed the Return key while focused in the input field.

cardnumber, cardexpiration, cardcvv

The customer has chosen a different address than was previously selected. You should use this data to re-price your order totals (if applicable).

applepay, googlepay

The customer has chosen a different shipping option than was previously selected. You should use this data to re-price your order totals (if applicable).

applepay, googlepay

The customer has authorized the payment and a source, and DigitalRiver.js returned associated data.

applepay, googlepay

Blur

A Blur event triggers when an element loses focus.

cardNumber.on('blur', function(event) {
    console.log('card number blur', event);
});
{
    elementType: "cardnumber"
}
{
    elementType: "cardnumber"
}

Cancel

A Cancel event occurs when the customer closes the Apple Pay Element Payment Request interface.

applepay.on('cancel', function(event) {
    //do stuff
}
{
    elementType: "applepay"
}

Change

A Change event triggers when an element changes state.‌

cardNumber.on('change', function(event) {
    console.log('card number change', event);
});
{
    brand: "unknown",
    complete: false,
    empty: true,
    elementType: "cardnumber",
    error: null
}

Invalid element change event example

{
    brand: "unknown",
    complete: true,
    empty: false,
    elementType: "cardnumber",
    "error": {
        "type": "validation_error",
        "code": "invalid_card_number",
        "message": "Your card number is invalid."
    }
}

Incomplete element change event example

{
    brand: "unknown",
    complete: false,
    empty: false,
    elementType: "cardnumber",
    error: {
        "type": "validation_error",
        "code": "incomplete_card_number",
        "message": "Your card number is incomplete."
    }
}

Error types, codes, messages

Error Scenario
Error Type
Error Code
Error Message

Credit Card Number field is incomplete.

validation-error

invalid_card_number

Your card number is invalid.

Credit Card Number field is complete but invalid.

validation-error

incomplete_card_number

Your card number is incomplete.

Card Security Code is incomplete

validation-error

invalid_expiration_month

Your card's expiration month is invalid.

Card Security Code is complete but invalid.

validation-error

invalid_expiration_year

Your card's expiration year is in the past.

Card Expiration field is incomplete.

validation-error

invalid_expiration_date

Your card's expiration date is invalid.

Card Expiration Date is complete but the date is invalid.

validation-error

incomplete_expiration_date

Your card's expiration date is incomplete.

Card Expiration Date is complete but has an invalid year.

validation-error

invalid_security_code

Your card's security code is invalid.

Card Expiration Date is complete but has an invalid month.

validation-error

incomplete_security_code

Your card's security code is incomplete.

Card brands‌

The following table lists the supported credit card brands.

Brand
Key

Visa

visa

MasterCard

mastercard

American Express

amex

Diners Club

dinersclub

Discover

discover

UnionPay

unionpay

JCB

jcb

Maestro

maestro

Forbrugsforeningen

forbrugsforeningen

Dankort

dankort

Click

A Click event occurs when the customer clicks an Apple Pay Element.

applepay.on('click', function(event) {
    //do stuff
}
{
    elementType: "applepay"
}

Focus

A Focus event triggers when an element gains focus.

cardNumber.on('ready', function(event) {
    console.log('card number ready', event);
});
{    
    elementType: "cardnumber"
}

Ready

A Ready event triggers when an element is ready and able to receive blur(), focus(), or update() calls.

cardNumber.on('focus', function(event) {
    console.log('card number focus', event);
});
{
    elementType: "cardnumber"
}

Return

A Return event triggers when a customer presses the Return key while the input field has focus.

cardNumber.on('return', function(event) {
    console.log('card number return', event);
});
{
    elementType: "cardnumber"
}

Shipping address change

A Shipping Address Change event occurs when the Customer has selected a different Shipping Address within the Payment Request interface. The event will create the following object structure.

Key
Type
Description

updateWith

Function

shippingAddress

​

applepay.on('shippingaddresschange', function(event) {
    var shippingAddress = event.shippingAddress;


    //create a Payment Request Details Update Object
    var newDetails = createPaymentRequestDetailsUpdateObject();

    event.updateWith(newDetails);
});

Apple Pay shipping address change object

{
    shippingAddress: {
        "name": "John Smith",
        "firstName": "John",
        "lastName": "Smith",
        "phone": "952-111-1111",
        "email": "jsmith@digitalriver.com",
        "address": {
            "line1": "10380 Bren Rd W",
            "line2": "string",
            "city": "Minnetonka",
            "postalCode": "55129",
            "state": "MN",
            "country": "US"
        }
    },
    "updateWith": function(data) {
        callback(data);
    }
}

Shipping option Change

A Shipping Option Change event occurs when the Customer has selected a different Shipping Option within the Payment Request interface. The event will emit the following object structure.

Key
Type
Description

updateWith

Function

shippingOption

​

​

applepay.on('shippingoptionchange', function(event) {
    var shippingOption = event.shippingOption;


    //create a Payment Request Details Update Object
    var newDetails = createPaymentRequestDetailsUpdateObject();
    event.updateWith(newDetails);
});

Apple Pay shipping option change object

{
    "shippingOption": {
        "id": "overnight-shipping",
        "label": "Overnight Shipping",
        "amount": 100,
        "detail": "Get this in 1 business day."
    },
    "updateWith": function(data) {
        callback(data);
    }
}

Source

googlepay.on('source', function(result) {
    var source = result.source;

    //pass the source to your back end for further processing
}

Element functions

Use these functions to trigger functionality within the specified Element to further enhance your purchase flow experience.‌

element.blur();

This function triggers the blur() event. This will remove the focus from the element.

cardNumber.blur();

element.clear();

This function clears the contents of the element.

cardNumber.clear();

element.focus();

This function triggers the focus() event and places the focus on the element.

cardNumber.focus();

element.destroy();

This function destroys the element. It removes the element and all of its associated data so you cannot use it again. You must create a new element if you want to restore the associated data.

cardNumber.destroy();

element.unmount();

This function removes the element from the Document Object Module (DOM). The element and its associated data still exist. You can place it on the page again by calling its mount() function.

cardNumber.unmount();

element.update(options);

This function updates the element with any included options. This can include custom styles and classes.

var options = {
    classes: {
        base: "DRElement",
        complete: "complete",
        empty: "empty",
        focus: "focus",
        invalid: "invalid",
        webkitAutofill: "autofill"
    },
    style: {
        base: {
            color: "#fff",
            fontFamily: "Arial, Helvetica, sans-serif",
            fontSize: "20px",
            fontSmoothing: "auto",
            fontStyle: "italic",
            fontVariant: "normal",
            letterSpacing: "3px"
        },
        empty: {
            color: "#fff"
        },
        complete: {
            color: "green"
        },
        invalid: {
            color: "red"
        }
    }
};

cardNumber.update(options);

Styling an element container

Custom classes

You can specify custom classes as part of a Class object included within the Options object when you create or update an element. If you do not provide custom classes, the system uses the default options.

var options = {
    classes: {
        base: "DRElement",
        complete: "complete",
        empty: "empty",
        focus: "focus",
        invalid: "invalid",
        webkitAutofill: "autofill"
    }
}

var cardNumber = elements.create("cardnumber", options);

Available custom classes

Class Type
ID
Applies When
Default Class Name

Base

base

The Element is in its base state. The user either has not entered anything into the input field or is currently typing.

DRElement

Complete

complete

The Element is in its complete state. The user has input value, and it meets the basic validation requirements of that field.

DRElement--complete

Empty

empty

The Element is empty. The Element once had value but is now empty.

DRElement--empty

Focus

focus

The Element has focus.

DRElement--focus

Invalid

invalid

The Element has value, but it does not meet the basic validation requirements of the field.

DRElement--invalid

WebKit Autofill

webkitAutofill

A saved card stored in a browser automatically fills this element.

DRElement-webkit-autofill

Custom styles

You can specify custom styles as part of a Style object included within the Options object when creating or updating an Element. The system uses the browser defaults if you don't provide custom styles.

var options = {
    style: {
        base: {
            color: "#fff",
            fontFamily: "Arial, Helvetica, sans-serif",
            fontSize: "20px",
            fontSmoothing: "auto",
            fontStyle: "italic",
            fontVariant: "normal",
            letterSpacing: "3px"
        },
        empty: {
            color: "#fff"
        },
        complete: {
            color: "green"
        },
        invalid: {
            color: "red",
        }
    }
}


var cardNumber = elements.create('cardnumber', options);

Available custom style classes

ID
Class Name
Description

base

Base

All other variants inherit from this style.

complete

Complete

Applied when the Element has valid input.

empty

Empty

Applied when the Element has no customer input.

focus

Focus

Applied when the Element has focus.

invalid

Invalid

Applied when the Element has invalid input.

webKitAutofill

Webkit Autofill

Applied when the Element has been filled automatically by a browser.

Available custom styles

Style
ID
Type
Example

Box Shadow

boxShadow

string

inset 0 0 0px 1000px #fff

Text Color

color

string

"#fff"

Font Family

fontFamily

string

"Arial, Helvetica, sans-serif",

Font Size

fontSize

string

"20px"

Font Smoothing

fontSmoothing

string

"antialiased"

Font Style

fontStyle

string

"bold"

Font Variant

fontVariant

string

"normal"

Letter Spacing

letterSpacing

string

"2px"

Text Align

textAlign

string

"center"

Text Decoration

textDecoration

string

"underline"

Text Shadow

textShadow

string

"2px 2px #ff0000"

Font Weight

fontWeight

string

"400"

Padding

padding

string

"2px"

Padding Top

paddingTop

string

"2px"

Padding Right

paddingRight

string

"2px"

Padding Bottom

paddingBottom

string

"2px"

Padding Left

paddingLeft

string

"2px"

Pseudo-classes

Class
ID
Type

:hover

:hover

string

:focus

:focus

string

::placeholder

::placeholder

string

::selection

::selection

string

:-webkit-autofill

:-webkit-autofill

string

:disabled

:disabled

string

Other customizable attributes

Attribute
ID
Type
Example
Description

Placeholder Text

placeholderText

string

"Card Number"

You may override the placeholder text that appears in cardnumber, cardexpiration, cardcvv, and onlinebanking element types. If you specify a placeholderText attribute, localization will not be applied.

Mask

mask

boolean

true/false

You may choose to mask the contents of the DigitalRiver.js Element after a proper number and card security code has been implemented. If enabled, only the last 4 digits of the card number will be exposed in the view.

​

​

​​

If an error is detected, Digital River will return a with the event payload.

Calling this function with a merges your updates into the current Payment Request object.

A

A that contains the customer's Shipping Address.

Calling this function with a merges your updates into the current .

A

A that contains the customer's chosen Shipping Option.

A Source event occurs when the Customer completes their interaction with the Payment Request interface and creates a Payment Source. The emitted object will be a .

DigitalRiver.js
​blur​
​cancel​
​change​
click​
focus
ready​
return
shippingaddresschange
​shippingoptionchange​
​source​
Change Event Error object
Payment Request Response object
Payment Request Details Update object
Payment Request Details Update object​
Shipping Address object
Payment Request Details Update object
Payment Request object
Payment Request Details Update object​
Payment Request Shipping Option object