Elements
Learn how to customize and stylize elements to seamlessly integrate them into your user experience or purchase flow.
An Element is a UI component that DigitalRiver.js creates to collect sensitive customer information without having the data touch your servers. You can customize and stylize these components to seamlessly integrate 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.
Example
1
<form id="payment-form">
2
<div id="card-number"></div>
3
<div id="card-expiration"></div>
4
<div id="card-cvv"></div>
5
<button type="submit">Submit</button>
6
</form>
7
8
9
cardNumber.mount('card-number');
10
cardExpiration.mount('card-expiration');
11
cardCVV.mount('card-cvv');
Copied!
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 created element is loaded and ready to accept an update request.
cardnumber, cardexpiration, cardcvv, applepay, googlepay, onlinebanking
The shopper 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.
JavaScript
1
cardNumber.on('blur', function(event) {
2
console.log('card number blur', event);
3
});
Copied!
Response object
Response object
1
{
2
elementType: "cardnumber"
3
}
4
{
5
elementType: "cardnumber"
6
}
Copied!
Cancel
A Cancel event occurs when the customer closes the Apple Pay Element Payment Request interface.
Example
1
applepay.on('cancel', function(event) {
2
//do stuff
3
}
Copied!
Response object
1
{
2
elementType: "applepay"
3
}
Copied!
Change
A Change event triggers when an element changes state.
If an error is detected, Digital River will return a Change Event Error object with the event payload.
Example
1
cardNumber.on('change', function(event) {
2
console.log('card number change', event);
3
});
Copied!
Response object
1
{
2
brand: "unknown",
3
complete: false,
4
empty: true,
5
elementType: "cardnumber",
6
error: null
7
}
Copied!
Invalid element change event example
Change Response Object Error - Invalid
1
{
2
brand: "unknown",
3
complete: true,
4
empty: false,
5
elementType: "cardnumber",
6
"error": {
7
"type": "validation_error",
8
"code": "invalid_card_number",
9
"message": "Your card number is invalid."
10
}
11
}
Copied!
Incomplete element change event example
Change Response Object Error - Incomplete
1
{
2
brand: "unknown",
3
complete: false,
4
empty: false,
5
elementType: "cardnumber",
6
error: {
7
"type": "validation_error",
8
"code": "incomplete_card_number",
9
"message": "Your card number is incomplete."
10
}
11
}
Copied!
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.
Example
1
applepay.on('click', function(event) {
2
//do stuff
3
}
Copied!
Response object
1
{
2
elementType: "applepay"
3
}
Copied!
Focus
A Focus event triggers when an element gains focus.
Example
1
cardNumber.on('ready', function(event) {
2
console.log('card number ready', event);
3
});
Copied!
Response object
1
{
2
elementType: "cardnumber"
3
}
Copied!
Ready
A Ready event triggers when an element is ready and able to receive
blur(), focus(), or update() calls.Example
1
cardNumber.on('focus', function(event) {
2
console.log('card number focus', event);
3
});
Copied!
Response object
1
{
2
elementType: "cardnumber"
3
}
Copied!
Return
A Return event triggers when a customer presses the Return key while the input field has focus.
Example
1
cardNumber.on('return', function(event) {
2
console.log('card number return', event);
3
});
Copied!
Response object
1
{
2
elementType: "cardnumber"
3
}
Copied!
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
Calling this function with a Payment Request Details Update object merges your updates into the current Payment Request object.
shippingAddress
JavaScript
1
applepay.on('shippingaddresschange', function(event) {
2
var shippingAddress = event.shippingAddress;
3
4
5
//create a Payment Request Details Update Object
6
var newDetails = createPaymentRequestDetailsUpdateObject();
7
8
event.updateWith(newDetails);
9
});
Copied!
Apple Pay shipping address change object
JavaScript
1
{
2
shippingAddress: {
3
"name": "John Smith",
4
"firstName": "John",
5
"lastName": "Smith",
6
"phone": "952-111-1111",
7
"email": "[email protected]",
8
"address": {
9
"line1": "10380 Bren Rd W",
10
"line2": "string",
11
"city": "Minnetonka",
12
"postalCode": "55129",
13
"state": "MN",
14
"country": "US"
15
}
16
},
17
"updateWith": function(data) {
18
callback(data);
19
}
20
}
Copied!
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
Calling this function with a Payment Request Details Update object merges your updates into the current Payment Request object.
shippingOption
Example
1
applepay.on('shippingaddresschange', function(event) {
2
var shippingAddress = event.shippingAddress;
3
4
5
//create a Payment Request Details Update Object
6
var newDetails = createPaymentRequestDetailsUpdateObject();
7
8
event.updateWith(newDetails);
9
});
Copied!
Apple Pay shipping option change object
Example
1
{
2
"shippingOption": {
3
"id": "overnight-shipping",
4
"label": "Overnight Shipping",
5
"amount": 100,
6
"detail": "Get this in 1 business day."
7
},
8
"updateWith": function(data) {
9
callback(data);
10
}
11
}
Copied!
Source
A Source event emits when the Customer completes their interaction with the Payment Request interface and creates a Payment Source. The emitted object will be a Payment Request Response object.
Example
1
googlepay.on('source', function(result) {
2
var source = result.source;
3
4
//pass the source to your back end for further processing
5
}
Copied!
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.Example
1
cardNumber.blur();
Copied!
element.clear();
This function clears the contents of the element.
Example
1
cardNumber.clear();
Copied!
element.focus();
This function triggers the
focus() event and places the focus on the element.Example
1
cardNumber.destroy();
Copied!
element.destroy();
This function destroys the element. 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.
Example
1
cardNumber.destroy();
Copied!
element.unmount();
This function removes the element from the Document Object Module (DOM). The element and its associated data still exists. You can place it on the page again by calling its
mount() function.Example
1
cardNumber.unmount();
Copied!
element.update(options);
This function updates the element with any included options. This can include custom styles and classes.
Example
1
var options = {
2
classes: {
3
base: "DRElement",
4
complete: "complete",
5
empty: "empty",
6
focus: "focus",
7
invalid: "invalid",
8
webkitAutofill: "autofill"
9
},
10
style: {
11
base: {
12
color: "#fff",
13
fontFamily: "Arial, Helvetica, sans-serif",
14
fontSize: "20px",
15
fontSmoothing: "auto",
16
fontStyle: "italic",
17
fontVariant: "normal",
18
letterSpacing: "3px"
19
},
20
empty: {
21
color: "#fff"
22
},
23
complete: {
24
color: "green"
25
},
26
invalid: {
27
color: "red"
28
}
29
}
30
};
31
32
cardNumber.update(options);
Copied!
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.Example
1
var options = {
2
classes: {
3
base: "DRElement",
4
complete: "complete",
5
empty: "empty",
6
focus: "focus",
7
invalid: "invalid",
8
webkitAutofill: "autofill"
9
}
10
}
11
12
var cardNumber = elements.create("cardnumber", options);
Copied!
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. If you don't provide custom styles, the system uses the browser defaults.Example
1
var options = {
2
style: {
3
base: {
4
color: "#fff",
5
fontFamily: "Arial, Helvetica, sans-serif",
6
fontSize: "20px",
7
fontSmoothing: "auto",
8
fontStyle: "italic",
9
fontVariant: "normal",
10
letterSpacing: "3px"
11
},
12
empty: {
13
color: "#fff"
14
},
15
complete: {
16
color: "green"
17
},
18
invalid: {
19
color: "red",
20
}
21
}
22
}
23
24
25
var cardNumber = elements.create('cardnumber', options);
Copied!
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
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
Example
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.
Last modified 1mo ago
Copy link
Contents
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