DigitalRiver object

Learn how to use the DigitalRiver object
Creating a DigitalRiver object
For details, refer to the Initializing DigitalRiver.js page.
let digitalRiver = new DigitalRiver("pk_test_fh9861t8b7384b7dke9e8dn4fb79808192", {
     "locale": "en-US"
});
Creating an instance of Drop-in
createDropin(config)
Use createDropin(config) to create an instance of Drop-in payments. For details, refer to the Drop-in payments integration guide. 
Creating elements
createElement(element, config)
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
amazonPay
​AmazonPay element​
applepay
​Apple Pay element​
cardCVV
A card security code field
cardExpiration
A credit card expiration field
cardNumber
A credit card number field
googlepay
​Google Pay element​
ideal
​iDEAL element​
konbini
​A Konbini element​
onlineBanking
​An online banking element​
offlineRefund
​An offline refund data collection element​
paypal
​A PayPal element​
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);
JavaScript
<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>
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
Creating sources
When creating sources, you have the option of selecting a method that accepts an element or using a method that doesn't require an element. Both methods however require that you provide source data to tokenize. When configuring this data, you can also specify a future use for the source.
For both versions, the createSource() method returns a promise that contains a Result object. The Result object, in turn, contains one of two possible objects:‌
source — A Source object created by Digital River.
error — An error object that indicates a problem with the tokenization request. It provides the data you must correct before attempting to create a source again.
createSource(sourceData)
Use the createSource(sourceData) method to create a payment source that contains information you can safely use with other Digital River APIs. This includes immediate sources (if PCI compliant), redirect sources, or delayed sources. See Configuring payment methods for more information on the structure of these requests.‌
In the following example, the method takes a single argument. The sourceData contains the data that you want Digital River to tokenize.
Example
var sourceData = {
        "type": "creditCard",
        "owner": {
            "firstName": "firstName",
            "lastName": "lastName",
            "email": "[email protected]",
            "address": {
                "line1": "1234 First 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.errors[0].message;
    } else {
​
        //send source to back end for processing
        var source = result.source;
    }
});
A successful response returns a source with a unique id.
Source response
{
    "error": undefined,
    "source": {
        "id": "775d3ff1-99a3-4640-bd2c-24e4b6b13324",
        "type": "creditCard",
        "owner": {
            "firstName": "John",
            "lastName": "Doe",
            "email": "[email protected]",
            "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"
        }
    }
}
An unsuccessful response returns an error with information on what needs to be corrected.
Error response
{
    "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
}
createSource(element, sourceData)
Use the createSource(element, sourceData) method to create a tokenized source that you can safely transmit to the backend for use in downstream API calls. This method requests two parameters:‌
element — A Element object created using the Elements portion of this library.
sourceData — The source data that you want Digital River to tokenize. See Common payment sources for more information on the required source data.
In the following example, the method takes both a source data and element argument.
Example
var sourceData = {
        "type": "creditCard",
        "owner": {
            "firstName": "firstName",
            "lastName": "lastName",
            "email": "[email protected]",
            "address": {
                "line1": "1234 First 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.errors[0].message;
    } else {
        //send source to back end for processing
        var source = result.source;
    }
});
A successful response returns a source with a unique id.
Source response
{
    "error": undefined,
    "source": {
        "id": "775d3ff1-99a3-4640-bd2c-24e4b6b13324",
        "clientId": "gc",
        "channelId": "drdod15",
        "type": "creditCard",
        "owner": {
            "firstName": "Gwen",
            "lastName": "Sawayn",
            "email": "[email protected]",
            "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"
        }
    }
}
An unsuccessful response returns an error with information on what needs to be corrected.
Error response
{
    "error": {
        "type": "validation_error",
        "errors": [{
            "code": "incomplete_card_number",
            "message": "Your card number is incomplete."
        }]
    },
    source: undefined
}
Specifying a source's future use
When creating a source using DigitalRiver.js, you should identify the types of transactions it will likely be used for in the future. This increases the probability that these future transactions will be approved. The usage value you select should be the one that most closely corresponds to your business model. The available options are subscription, convenience, and unscheduled.
Subscription
Set usage to subscription when you create sources that are used primarily for recurring transactions, made at regular intervals for a product or a service.
Convenience
The convenience setting applies mainly to saved payment sources that are used for one-off transactions. These are sources where customers are typically present during the checkout flow and want to quickly access their payment information. Select this option if you don't offer subscriptions or don't have unscheduled merchant-initiated transactions
Unscheduled
Set usage to unscheduled when you create sources for unscheduled merchant-initiated transactions. These are contracts that occur on a non-fixed schedule using stored card information. Automatic top-ups are an example of one such transaction. They occur whenever a customer's balance drops below a pre-defined amount.
Retrieving sources
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.errors[0].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": "[email protected]",
            "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"
        }
    }
}
Authenticating sources
The authenticate source method determines whether the saved payment source selected by a customer during the checkout process requires Strong Customer Authentication (SCA).
You can use this method when building workflows that allow customers to retrieve saved payment information during one-off purchases and subscription acquisitions.
The standard version of the method accepts a configuration object that contains the data we need to authenticate the source. With the exception of the returnUrl, you can set the parameters of this object by retrieving the source and then getting the required data.
Parameter
Required/Optional
Description
sessionId
Required
The payment session identifier of this transaction.
sourceId
Required
The identifier of the payment source used in this transaction.
sourceClientSecret
Required
The source client secret for this transaction.
returnUrl
Required
The return URL where the customer is directed when 3D Secure 1 is required. If the value is not provided, we use the current page location.
Do not log, embed in URLs, or expose the sourceClientSecret to anyone other than the customer. On any page that includes the secret, ensure that TLS is enabled.
The other version of the authenticate source method accepts this same data plus an optional CVV Element type.
After you call either version of this method, Digital River automatically handles the SCA requirements. Once the customer completes the necessary authentication or we determine that authentication isn't required, the method resolves and the checkout flow can continue.
More specifically, the method returns a promise which is resolved by a source authentication result object. The following are the possible results and the recommended actions:
Status
Description
complete
The customer successfully completed the steps necessary to authenticate the source. You can now submit the order.
authentication_not_required
Digital River determined that the payment source didn't require authentication for this particular payment session. You can now submit the order.
failed
Source authentication failed. The source can still be used in the transaction but may be declined. You should attempt to authenticate the source again.
authenticateSource(data)
You can use this method to authenticate a payment source before it is applied to a transaction.
digitalriver.authenticateSource({
    "sessionId": "65b1e2c2-632c-4240-8897-195ca22ce108",
    "sourceId": "ee90c07c-5549-4a6b-aa5f-aabe29b1e97a",
    "sourceClientSecret": "ee90c07c-5549-4a6b-aa5f-aabe29b1e97a_51afe818-0e7f-46d7-8257-b209b20f4d8",
    "returnUrl": "https://returnurl.com"
});
The following is an example response when a source is successfully authenticated:
{
    "status": "complete"
}
authenticateSource([cvvElement], data)
In this alternative version of the method to authenticate sources, you can provide an optional CVV Element type (assuming it is correctly created and mounted). By setting this parameter, the value contained in the field of the CVV Element is included in the authentication request.
digitalriver.authenticateSource(cvvElement, {
    "sessionId": "65b1e2c2-632c-4240-8897-195ca22ce108",
    "sourceId": "ee90c07c-5549-4a6b-aa5f-aabe29b1e97a",
    "sourceClientSecret": "ee90c07c-5549-4a6b-aa5f-aabe29b1e97a_51afe818-0e7f-46d7-8257-b209b20f4d8",
    "returnUrl": "https://returnurl.com"
});
The following is an example response when a source is successfully authenticated:
{
    "status": "complete"
}
Updating sources
updateSource([element,] sourceData)
Use this method to update details on a source.
When updating a source, you can update the owner and the expiration details for Credit Cards only. If you need to update a non-Credit Card (creditCard) payment type, use createSource.
This method takes two parameters:‌
element—An optional card expiration element for using the Elements portion of this library.
sourceData—A required data object which contains additional data that is 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.
Note: You can only update the owner information for Credit Cards.
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 to update the source.
Updating expiration and address information
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 protected]",
            "address": {
                "line1": "1234 First 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.errors[0].message;
    } else {
        //the source has been updated with new details
        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": "firstName",
            "lastName": "lastName",
            "email": "[email protected]",
            "address": {
                "line1": "1234 First 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
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 protected]",
            "address": {
                "line1": "1234 First 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.errors[0].message;
    } else {
        //the source has been updated with new details
        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": "firstName",
            "lastName": "lastName",
            "email": "[email protected]",
            "address": {
                "line1": "1234 First 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
//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.errors[0].message;
    } else {
        //the source has been updated with new details
        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": "firstName",
            "lastName": "lastName",
            "email": "[email protected]",
            "address": {
                "line1": "1234 First 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
DigitalRiver object

Creating a DigitalRiver object

Creating an instance of Drop-in

`createDropin(config)`

Creating elements

`createElement(element, config)`

Options

Creating sources

`createSource(sourceData)`

`createSource(element, sourceData)`

Specifying a source's future use

Subscription

Convenience

Unscheduled

Retrieving sources

`retrieveSource(sourceId, sourceClientSecret)`

Authenticating sources

`authenticateSource(data)`

`authenticateSource([cvvElement], data)`

Updating sources

`updateSource([element,] sourceData)`

Updating expiration and address information

Updating only address information

Updating only card expiration information

Update error‌

Element Type	Description
`amazonPay`	AmazonPay element
`applepay`	Apple Pay element
`cardCVV`	A card security code field
`cardExpiration`	A credit card expiration field
`cardNumber`	A credit card number field
`googlepay`	Google Pay element
`ideal`	iDEAL element
`konbini`	A Konbini element
`onlineBanking`	An online banking element
`offlineRefund`	An offline refund data collection element
`paypal`	A PayPal element
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
Parameter	Required/Optional	Description
`sessionId`	Required	The payment session identifier of this transaction.
`sourceId`	Required	The identifier of the payment source used in this transaction.
`sourceClientSecret`	Required	The source client secret for this transaction.
`returnUrl`	Required	The return URL where the customer is directed when 3D Secure 1 is required. If the value is not provided, we use the current page location.
Status	Description
`complete`	The customer successfully completed the steps necessary to authenticate the source. You can now submit the order.
`authentication_not_required`	Digital River determined that the payment source didn't require authentication for this particular payment session. You can now submit the order.
`failed`	Source authentication failed. The source can still be used in the transaction but may be declined. You should attempt to authenticate the source again.
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. Note: You can only update the `owner` information for Credit Cards.