Reference

This is the API reference for DigitalRiver.js' APIs. It shows you how to tokenize customer information, collect sensitive card data using customizable elements, and accept payments.

Do you want to dive in? Check out the Quick start.

Including DigitalRiver.js on your page

To leverage the functionality included in the DigitalRiver.js library, you must include the src attribute and specify the location (URL) of the library on your web page and set your API key.

HTML
<script src="https://js.digitalriverws.com/v1/DigitalRiver.js"></script>

Digital River publishable API Key

Use the DigitalRiver(publishableAPIKey) object to create an instance of the DigitalRiver object. This is called a Digital River publishable API key.

let digitalriver = new DigitalRiver("YOUR_PUBLIC_API_KEY");

This function accepts an optional options object using the following format: DigitalRiver(publishableApiKey[, options])

You may specify the following options within this object.

Option

Description

locale

The locale used to localize the various display and error strings within DigitalRiver.js

Currently supported locales:

ar-EG, cs-CZ, da-DK, de-AT, de-CH, de-DE, el-GR, en-AU, en-BE, en-CA, en-CH, en-DK, en-FI, en-GB, en-IE, en-IN, en-MY, en-NL, en-NO, en-NZ, en-PR, en-SE, en-SG, en-US, en-ZA, es-AR, es-CL, es-CO, es-EC, es-ES, es-MX, es-PE, es-VE, et-EE, fi-FI, fr-BE, fr-CA, fr-CH, fr-FR, hu-HU, it-CH, it-IT, iw-IL, ja-JP, ko-KR, lt-LT, lv-LV, nl-BE, nl-NL, no-NO, pl-PL, pt-BR, pt-PT, ro-RO, ru-RU, sk-SK, sl-SI, sr-YU, sv-SE, th-TH, tr-TR, zh-CN, zh-HK, zh-TW

Localizing DigitalRiver.js

The following example localizes the various display and error strings to English (United States).

let digitalriver = new DigitalRiver("YOUR_PUBLIC_API_KEY", {
"locale": "en-us"
});

DigitalRiver object

Creating a payment source

digitalriver.createSource(element, sourceData);

Use createSource(sourceData) to create a payment source using source information that you can safely pass to your backend for use with other Digital River APIs. This can include Immediate Sources (if PCI compliant) Redirect Sources, or Delayed Sources. See Payment methods for more information on the structure of these requests.

In the following example, the method takes one argument (sourceData). The sourceData is an object that contains the data that you want to tokenize within the Payment service.

Example
var sourceData = {
"type": "creditCard",
"owner": {
"firstName": "firstName",
"lastName": "lastName",
"email": "email@email.org",
"address": {
"line1": "1234 Fake St.",
"city": "Minnetonka",
"state": "MN",
"country": "US",
"postalCode": 55410
}
},
"creditCard": {
"number": "4444333322221111",
"expirationMonth": 12,
"expirationYear": 2025,
"cvv": "123"
}
}
digitalriver.createSource(sourceData).then(function(result) {
if(result.error) {
//handle error message
var errorMessage = result.error.message;
} else {
//send source to back end for processing
var source = result.source;
}
});
Source response
{
"error": undefined,
"source": {
"id": "775d3ff1-99a3-4640-bd2c-24e4b6b13324",
"type": "creditCard",
"usage": "single",
"owner": {
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@yahoo.com",
"referenceId": "",
"address": {
"line1": "10380 Bren Road W.",
"line2": "Suite 929",
"city": "Minnetonka",
"state": "MN",
"country": "US",
"postalCode": "55343"
}
},
"status": "chargeable",
"creationIp": "67.256.231.1",
"creationDate": "2018-08-22T19:21:59.26Z",
"flow": "standard",
"creditCard": {
"brand": "Visa",
"expirationMonth": 10,
"expirationYear": 2019,
"lastFourDigits": "1111"
}
}
}
Source error
{
"error": {
"type": "bad_request",
"errors": [{
"code": "invalid_parameter",
"parameter": "owner.firstName",
"message": "'' is not a valid owner.firstname."
},
{
"code": "currency_unsupported",
"parameter": "currency",
"message": "currency 'xyz' is not supported."
}]
},
source: undefined
}

digitalriver.createSource(element, sourceData);

Use createSource(element, sourceData) to create a tokenized source that you can safely transmit to the backend for use in downstream API calls. This method request two parameters:

  • element—A required object that is an Element created using the Elements portion of this library.

  • sourceData—A required object that contains additional data that creates the specified type within the Payment Service. See Common payment sources for more information on the required source data.

The digitalriver.createSource() returns a Promise that contains a Result object. (See Source response in the following example.) The Result object will contain one of the following results:

  • result.source—A Source object created in the Payments Service.

  • result.error—An error occurred that you must correct before you can create a source.

If there is a problem with the tokenization request, Digital River returns a Create Source Error object in the response that shows the data you need to correct before trying again.

Example
var sourceData = {
"type": "creditCard",
"owner": {
"firstName": "firstName",
"lastName": "lastName",
"email": "email@email.org",
"address": {
"line1": "1234 Fake St.",
"city": "Minnetonka",
"state": "MN",
"country": "US",
"postalCode": 55410
}
}
}
digitalriver.createSource(cardNumber, sourceData).then(function(result) {
if(result.error) {
//handle error messages
var errorMessage = result.error.message;
} else {
//send source to back end for processing
var source = result.source;
}
});
Source response
{
"error": undefined,
"source": {
"id": "775d3ff1-99a3-4640-bd2c-24e4b6b13324",
"clientId": "gc",
"channelId": "drdod15",
"type": "creditCard",
"usage": "single",
"owner": {
"firstName": "Gwen",
"lastName": "Sawayn",
"email": "Felicita81@yahoo.com",
"referenceId": "",
"address": {
"line1": "04644 Altenwerth Drives",
"line2": "Suite 929",
"city": "North Aurelia",
"state": "NV",
"country": "US",
"postalCode": "93414-6991"
}
},
"amount": "100.00",
"currency": "USD",
"status": "chargeable",
"creationIp": "67.216.237.4",
"creationDate": "2018-08-22T19:21:59.26Z",
"flow": "standard",
"creditCard": {
"brand": "Visa",
"expirationMonth": 10,
"expirationYear": 2019,
"lastFourDigits": "1111"
}
}
}
Source error
Source error
{
"error": {
"type": "validation_error",
"errors": [{
"code": "incomplete_card_number",
"message": "Your card number is incomplete."
}]
},
source: undefined
}

digitalriver.retrieveSource(sourceId, sourceClientSecret);

Use this method to retrieve a source with the front-end DigitalRiver.js library. This method takes two parameters:

  • sourceId—The unique ID of the source you want to retrieve.

  • sourceClientSecret—The clientSecret value of the source you are trying to retrieve. This is specific to the source.

The digitalriver.createSource() returns a Promise that includes a Result object. (See the following source response example.) The Result object will have either:

  • result.source—If this object is not null, it will contain the Source object you requested.

  • result.error— If this object is not null, it will contain an Error object with details on the specific error.

Example
digitalriver.retrieveSource("ee90c07c-5549-4a6b-aa5f-aabe29b1e97a","ee90c07c-5549-4a6b-aa5f-aabe29b1e97a_51afe818-0e7f-46d7-8257-b209b20f4d8").then(function(result) {
if(result.error) {
//handle error messages
var errorMessage = result.error.message;
} else {
//do something with the source
var source = result.source;
}
});
Source response
{
"error": undefined,
"source": {
"id": "775d3ff1-99a3-4640-bd2c-24e4b6b13324",
"clientId": "gc",
"channelId": "drdod15",
"type": "creditCard",
"usage": "single",
"owner": {
"firstName": "Gwen",
"lastName": "Sawayn",
"email": "Felicita81@yahoo.com",
"referenceId": "",
"address": {
"line1": "04644 Altenwerth Drives",
"line2": "Suite 929",
"city": "North Aurelia",
"state": "NV",
"country": "US",
"postalCode": "93414-6991"
}
},
"amount": "100.00",
"currency": "USD",
"status": "chargeable",
"creationIp": "67.216.237.4",
"creationDate": "2018-08-22T19:21:59.26Z",
"flow": "standard",
"creditCard": {
"brand": "Visa",
"expirationMonth": 10,
"expirationYear": 2019,
"lastFourDigits": "1111"
}
}
}

digitalriver.updateSource([element,] sourceData);

Use this method to update details on a source. When updating a source, you may update the Owner or in the case of a Credit Card source, the card expiration details. This method takes two parameters:

  • element—An optional card expiration element created using the Elements portion of this library.

  • sourceData—A required data object which contains additional data required to update the payment source.

Field

Required

Type

Description

clientSecret

Required

String

The Client Secret of the source you are updating.

id

Required

String

The ID of the source you are updating.

owner

Optional

An Owner Object

An object containing the Owner details.

digitalriver.updateSource() returns a Promise that returns a result object. The result object will have either:

  • result.source—A source object that was updated in the Payments Service

  • result.error—An error occurred that must be corrected in order to update the source.

Updating expiration and address information

Example
Example
//Create the element using DigitalRiver.js and place it on the page.
var options = {
style: {
base: {
color: "#fff",
fontFamily: "Arial, Helvetica, sans-serif",
fontSize: "20px",
fontSmoothing: "auto",
fontStyle: "italic",
fontVariant: "normal",
letterSpacing: "3px"
}
...
}
var cardExpiration = digitalriver.createElement('cardexpiration', options);
cardExpiration.mount('card-expiration');
var sourceData = {
"id": "14381d1c-8bff-4350-aeea-82b36f3a196c",
"clientSecret": "14381d1c-8bff-4350-aeea-82b36f3a196c_14381d1c-8bff-4350-aeea-82b36f3a196c",
"owner": {
"firstName": "firstName",
"lastName": "lastName",
"email": "email@email.org",
"address": {
"line1": "1234 Fake St.",
"city": "Minnetonka",
"state": "MN",
"country": "US",
"postalCode": 55410
}
}
}
digitalriver.updateSource(cardExpiration, sourceData).then(function(result) {
if(result.error) {
//handle error messages
var errorMessage = result.error.message;
} else {
//the source has been updated with new details
var source = result.source;
}
});
Source Response
Source Response
{
"error": undefined,
"source": {
"id": "775d3ff1-99a3-4640-bd2c-24e4b6b13324",
"clientId": "gc",
"channelId": "drdod15",
"type": "creditCard",
"usage": "single",
"owner": {
"firstName": "firstName",
"lastName": "lastName",
"email": "email@email.org",
"address": {
"line1": "1234 Fake St.",
"city": "Minnetonka",
"state": "MN",
"country": "US",
"postalCode": 55410
}
},
"status": "chargeable",
"creationIp": "67.216.237.4",
"creationDate": "2018-08-22T19:21:59.26Z",
"flow": "standard",
"creditCard": {
"brand": "Visa",
"expirationMonth": 10,
"expirationYear": 2019,
"lastFourDigits": "1111"
}
}
}

Updating only address information

Example
Example
var sourceData = {
"id": "14381d1c-8bff-4350-aeea-82b36f3a196c",
"clientSecret": "14381d1c-8bff-4350-aeea-82b36f3a196c_14381d1c-8bff-4350-aeea-82b36f3a196c",
"owner": {
"firstName": "firstName",
"lastName": "lastName",
"email": "email@email.org",
"address": {
"line1": "1234 Fake St.",
"city": "Minnetonka",
"state": "MN",
"country": "US",
"postalCode": 55410
}
}
}
digitalriver.updateSource(sourceData).then(function(result) {
if(result.error) {
//handle error messages
var errorMessage = result.error.message;
} else {
//the source has been updated with new details
var source = result.source;
}
});
Source Response
Source Response
{
"error": undefined,
"source": {
"id": "775d3ff1-99a3-4640-bd2c-24e4b6b13324",
"clientId": "gc",
"channelId": "drdod15",
"type": "creditCard",
"usage": "single",
"owner": {
"firstName": "firstName",
"lastName": "lastName",
"email": "email@email.org",
"address": {
"line1": "1234 Fake St.",
"city": "Minnetonka",
"state": "MN",
"country": "US",
"postalCode": 55410
}
},
"status": "chargeable",
"creationIp": "67.216.237.4",
"creationDate": "2018-08-22T19:21:59.26Z",
"flow": "standard",
"creditCard": {
"brand": "Visa",
"expirationMonth": 10,
"expirationYear": 2019,
"lastFourDigits": "1111"
}
}
}

Updating only card expiration information

Example
Example
//Create the element using DigitalRiver.js and place it on the page.
var options = {
style: {
base: {
color: "#fff",
fontFamily: "Arial, Helvetica, sans-serif",
fontSize: "20px",
fontSmoothing: "auto",
fontStyle: "italic",
fontVariant: "normal",
letterSpacing: "3px"
}
...
}
var cardExpiration = digitalriver.createElement('cardexpiration', options);
cardExpiration.mount('card-expiration');
var sourceData = {
"id": "14381d1c-8bff-4350-aeea-82b36f3a196c",
"clientSecret": "14381d1c-8bff-4350-aeea-82b36f3a196c_14381d1c-8bff-4350-aeea-82b36f3a196c"
}
digitalriver.updateSource(cardExpiration, sourceData).then(function(result) {
if(result.error) {
//handle error messages
var errorMessage = result.error.message;
} else {
//the source has been updated with new details
var source = result.source;
}
});
Source Response
Source Response
{
"error": undefined,
"source": {
"id": "775d3ff1-99a3-4640-bd2c-24e4b6b13324",
"clientId": "gc",
"channelId": "drdod15",
"type": "creditCard",
"usage": "single",
"owner": {
"firstName": "firstName",
"lastName": "lastName",
"email": "email@email.org",
"address": {
"line1": "1234 Fake St.",
"city": "Minnetonka",
"state": "MN",
"country": "US",
"postalCode": 55410
}
},
"status": "chargeable",
"creationIp": "67.216.237.4",
"creationDate": "2018-08-22T19:21:59.26Z",
"flow": "standard",
"creditCard": {
"brand": "Visa",
"expirationMonth": 10,
"expirationYear": 2019,
"lastFourDigits": "1111"
}
}
}

Update error

If there is a problem with the update request, an error object will be returned in the response.

Source Errors
Source Errors
{
"error": {
"type": "validation_error",
"errors": [{
"code": "incomplete_card_number",
"message": "Your card number is incomplete."
}]
},
source: undefined
}

digitalriver.retrieveOnlineBankingBanks(countryCode, currency);

Use this method to retrieve an array of available banks for a combination of ISO 3166-1 alpha-2 country code and ISO 4217 currency code.

This method returns an array that will either be empty if no banks are available or will contain objects with Issuer IDs and Bank Names. DigitalRiver.js uses this data when creating an Online Banking source. This method is useful if you would like to build a bank selector yourself instead of using the Online Banking element.

Example
digitalriver.retrieveOnlineBankingBanks("DE","EUR").then(function(result) {
//do something with the banks, this could include building a selector or something else
});
Source response
[{
"bankCode": "86",
"bankName": "Sofortüberweisung"
}, {
"bankCode": "21",
"bankName": "Giropay"
}]

digitalriver.createElement();

Use this method to create an instance of an element that you can use to capture payment details. You can use the following Elements in conjunction with createSource to create a payment source.

Element Type

Description

applepay

Apple Pay

cardCVV

A card security code field

cardExpiration

A credit card expiration field

cardNumber

A credit card number field

googlepay

Google Pay

onlineBanking

An online banking select

Example
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",
}
}
};
var cardNumber = digitalriver.createElement('cardnumber', options);
var cardExpiration = digitalriver.createElement('cardexpiration', options);
var cardCVV = digitalriver.createElement('cardcvv', options);

Options

Heading

State

Default Class

classes

base

DRElement

classes

complete

DRElement--complete

classes

empty

DRElement--empty

classes

focus

DRElement--focus

classes

invalid

DRElement--invalid

classes

autofilled

DRElement--autofilled

HTML example

HTML Example
<div id="card-number" class="DRElement">
<!-- The embedded Element iframe -->
<iframe src="cardnumber.html"></iframe>
</div>
<div id="card-number" class="DRElement--complete">
<!-- The embedded Element iframe -->
<iframe src="cardnumber.html"></iframe>
</div>
<div id="card-number" class="DRElement--empty">
<!-- The embedded Element iframe -->
<iframe src="cardnumber.html"></iframe>
</div>
<div id="card-number" class="DRElement--focus">
<!-- The embedded Element iframe -->
<iframe src="cardnumber.html"></iframe>
</div>
<div id="card-number" class="DRElement--invalid">
<!-- The embedded Element iframe -->
<iframe src="cardnumber.html"></iframe>
</div>
<div id="card-number" class="DRElement--autofilled">
<!-- The embedded Element iframe -->
<iframe src="cardnumber.html"></iframe>
</div>

Elements

You can customize and stylize these components to seamlessly integrate 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 will 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
<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

blur

The element has lost focus.

cardnumber, cardexpiration, cardcvv, onlinebanking

cancel

The customer has canceled the experience.

applepay, googlepay

change

The element's state has changed.

cardnumber, cardexpiration, cardcvv, onlinebanking

click

A shopper clicked the element's button.

applepay, googlepay

focus

The element has gained focus.

cardnumber, cardexpiration, cardcvv, onlinebanking

ready

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

cardnumber, cardexpiration, cardcvv, applepay, googlepay, onlinebanking

shippingaddresschange

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

shippingoptionchange

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

source

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.

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

Cancel

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

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

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
cardNumber.on('change', function(event) {
console.log('card number change', event);
});
Response object
{
brand: "unknown",
complete: false,
empty: true,
elementType: "cardnumber",
error: null
}

Invalid element change event example

Change Response Object Error - Invalid
{
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

Change Response Object Error - Incomplete
{
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 invalid year.

validation-error

invalid_security_code

Your card's security code is invalid.

Card Expiration Date is complete, but has 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 emits when the customer clicks an Apple Pay Element.

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

Focus

A Focus event riggers when an element gains focus.

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

Ready

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

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

Shipping Address Change

A Shipping Address Change event emits when the Customer has selected a different Shipping Address 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.

shippingAddress

A Payment Request Details Update object

A Shipping Address object that contains the customer's Shipping Address.

Example
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

Example
{
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 emits 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

A Payment Request Details Update obje

A Payment Request Shipping Option object that contains the customer's chosen Shipping Option.

Example
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

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

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
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.

Example
cardNumber.blur();

element.clear();

This function clears the contents of the element.

Example
cardNumber.clear();

element.focus();

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

Example
cardNumber.focus();

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
cardNumber.destroy();

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
cardNumber.unmount();

element.update(options);

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

Example
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.

Example
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 and Element. If you don't provide custom styles, the system uses the browser defaults.

Example
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

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"

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.

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", } }, placeholderText: "Credit Card Number" }

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

Apple Pay elements

With DigitalRiver.js, you can create an Apple Pay element and interact with Apple Pay.

Creating an Apple Pay element

Example
var paymentRequestData = digitalriver.paymentRequest({
country: "US",
currency: "USD",
total: {
label: "Order Total",
amount: 100
},
displayItems: lineItems,
shippingOptions: shippingOptions,
style: {
buttonType: "plain",
buttonColor: "dark",
buttonLanguage: "en"
}
});
var applepay = digitalriver.createElement('applepay', paymentRequestData);

Apply Pay element styles and customization

Use the following styles and types to create an Apple Pay button that you can more closely integrate into your experience.

Button type

Choose one of the following button types:

Apple Pay button
Buy with Apple Pay button

Button color

Choose one of the following button colors:

Light Apple Pay button
Apply Pay button with outlien
Dark Apple Pay button

Apple Pay Element Functions

applepay.canMakePayment();

Call this function to determine whether or not the Customer's browser supports Apple Pay.

Example
if(applepay.canMakePayment()) {
//can make payment with this element
}

applepay.mount();

Call this function to place the created Apple Pay element on your page.

Example
<div id="apple-pay"></div>
if(applepay.canMakePayment()) {
//can make payment with this element
applepay.mount('apple-pay');
}

applepay.show();

Call this function to show the Apple Pay Payment Request interface. This will automatically happen when using the element. If you'd like to trigger via another mechanism, you must call it as part of the user interaction (click handler).

Example
applepay.show();

applepay.unmount();

Call this function to remove the Apple Pay element from your page. The element may be re-added to your page by calling mount().

Example
applepay.unmount();

applepay.destroy();

Call this function to remove the Apple Pay element from your page as well as remove its functionality. You cannot re-add the element to your page via mount().

Example
applepay.destroy();

applepay.update();

Call this function to update the Apple Pay element's data. Calling this will merge your changes into the already existing Payment Request object.

Example
var paymentRequest = digitalriver.paymentRequest({
country: "US",
currency: "USD",
total: {
label: "Order Total",
amount: 100
},
displayItems: lineItems,
shippingOptions: shippingOptions,
style: {
buttonType: "plain",
buttonColor: "dark",
buttonLanguage: "en"
}
});
applepay.update(paymentRequest);

Apple Pay element events — applepay.on('event', handler);

Call this function to listen to events that can be used to build and enhance your purchase flow.

Event

Triggered When

ready

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

click

A shopper clicked the element's button.

cancel

The customer has canceled the experience.

shippingoptionchange

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).

shippingaddresschange

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

source

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

Source

The Source event emits when the Customer completes their interaction with the Payment Request interface, and they create a Payment Source. The emitted object will be a Payment Request Response object.

Example
applepay.on('source', function(event) {
var source = result.source;
//pass the souce to your back end for further processing.
});

Ready

The Ready event emits when the Apple Pay Element has loaded and is available to take an update() call.

Example
applepay.on('ready', function(event) {
//apple pay element is ready and can accept an update call
});
Response object
{
elementType: "applepay"
}

Click

The Click event emits when the customer clicks an Apple Pay Element.

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

Cancel

The Cancel event emits when the customer closes the Apple Pay Element Payment Request interface.

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

Shipping Option Change

The Shipping Option Change event emits when the Customer selects 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

A Payment Request Details Update object

A Payment Request Shipping Option object contains the details of the customer's chosen Shipping Option.

Example
applepay.on('shippingoptionchange', function(event) {
var shippingOption = event.shippingOption;
//create a Payment Request Details Update Object
var newDetails = createPaymentRequestDetailsUpdateObject();
event.updateWith(newDetails);
});
Response object
{
"shippingOption": {
"id": "overnight-shipping",
"label": "Overnight Shipping",
"amount": 100,
"detail": "Get this in 1 business day."
},
"updateWith": function(data) {
callback(data);
}
}

Shipping Address Change

The Shipping Address Change emits when the Customer selects a different Shipping Address 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.

shippingAddress

A Payment Request Details Update object object

A Payment Request Shipping Option object contains the details of the customer's chosen Shipping Option.

Example
applepay.on('shippingaddresschange', function(event) {
var shippingAddress = event.shippingAddress;
//create a Payment Request Details Update Object
var newDetails = createPaymentRequestDetailsUpdateObject();
event.updateWith(newDetails);
});
Response 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);
}
}

Google Pay elements

With DigitalRiver.js, you can create a Google Pay element and interact with Google Pay.

Creating a Google Pay element

Example
var paymentRequestData = digitalriver.paymentRequest({
country: "US",
currency: "USD",
total: {
label: "Order Total",
amount: 100
},
displayItems: lineItems,
shippingOptions: shippingOptions,
style: {
buttonType: "plain",
buttonColor: "dark",
buttonLanguage: "en"
}
});
var googlepay = digitalriver.createElement('googlepay', paymentRequestData);

Google Pay element styles and customization

Button type

Choose one of the following button types:

Google Pay button
Buy with Google Pay button

Button color

Choose one of the following button colors:

Light Google Pay button
Dark Google Pay button