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": "nl"
});

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 with createSource() to create a payment source.

Element TypeDescription

amazonPay

applepay

cardCVV

A card security code field

cardExpiration

A credit card expiration field

cardNumber

A credit card number field

googlepay

iban

ideal

konbini

onlineBanking

offlineRefund

paypal

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

HeadingStateDefault 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 a payment request

For details, refer to the Payment request object in the Digital River payment objects article.

Creating sources

When creating sources, you can select a method that accepts an element or use 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 specify a future source use.

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

var sourceData = {
        "type": "creditCard",
        "owner": {
            "firstName": "firstName",
            "lastName": "lastName",
            "email": "email@email.org",
            "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.

{
    "error": undefined,
    "source": {
        "id": "775d3ff1-99a3-4640-bd2c-24e4b6b13324",
        "type": "creditCard",
        "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"
        }
    }
}

An unsuccessful response returns an error with information on what must be corrected.

{
    "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 to 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.

The method uses source data and an element argument in the following example.

var sourceData = {
        "type": "creditCard",
        "owner": {
            "firstName": "firstName",
            "lastName": "lastName",
            "email": "email@email.org",
            "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.

{
    "error": undefined,
    "source": {
        "id": "775d3ff1-99a3-4640-bd2c-24e4b6b13324",
        "clientId": "gc",
        "channelId": "drdod15",
        "type": "creditCard",
        "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"
        }
    }
}

An unsuccessful response returns an error with information on what must be corrected.

{
    "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 use 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 our business model. The available options are subscription, convenience, and unscheduled.

Subscription

Set usage to subscription when you create sources primarily for recurring transactions made at regular intervals for a product or a service.

Convenience

The convenience setting applies mainly to saved payment sources used for one-off transactions. These are sources where customers are typically present during the checkout flow and want to access their payment information quickly. 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 with 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.

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;
    }
});
{
    "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"
        }
    }
}

Authenticating sources

The authenticate source method determines whether a saved payment source, selected by a customer during a checkout, requires Strong Customer Authentication (SCA).

The first version of the method accepts a required configuration object that contains the data we need to authenticate the source. The second version requires this same data plus a CVV Element.

ParameterRequired/OptionalDescription

sessionId

Required

The payment session identifier of this transaction.

sourceId

Required

The identifier of the payment source selected by the customer.

sourceClientSecret

Required

The source's client secret.

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.

After you call either version, Digital River automatically handles any 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.

The method returns a source authentication result object with a promise. The following are its possible status values and the recommended actions:

statusDescription

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

Call this method to authenticate a payment source before applying it 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 its determined that authentication isn't required:

{
    "status": "authentication_not_required"
}

authenticateSource([cvvElement], data)

In this alternative authenticate source method, you can provide an optional CVV Element (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 only update the owner and the expiration details for Credit Cards. 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 containing additional data required to update the payment source.

FieldRequiredTypeDescription

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

//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 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;
    }
});
{
    "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 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

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 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;
    }
});
{
    "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 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

//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;
    }
});
{
    "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 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.

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

Retrieving available payment methods

retrieveAvailablePaymentMethods([filters])

Use this method to retrieve an array of available payment methods. You can use this to filter and determine applicable payment methods while building your checkout flows. The filters object is optional.

AttributeRequired/OptionalDescription

currency

Optional

The currency of the transaction.

country

Optional

The country of the billing addresses associated with this transaction.

supportsStorage

Optional

Whether the payment supports storage.

supportsRecurring

Optional

Whether the payment method supports recurring payments.

supportsFreeTrial

Optional

Whether the payment method supports free trials.

sessionId

Optional

The Payment Session ID. If used, the response will return the payment methods which apply to your transaction.

Retrieve available payment methods response without using session ID

The following example shows a request with no filters applied.

digitalriver.retrieveAvailablePaymentMethods().then(function(result) {
    //do something with the result, this could include showing or hiding specific payment methods that are applicable to the display
});

The following response includes all payment methods that you configured for your account.

{
    "paymentMethods": [
        {
            "type": "alipay",
            "flow": "redirect",
            "supportsRecurring": false,
            "supportsFreeTrial": false,
            "images": {
                "iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/alipay.png"
            }
        },
        {
            "type": "applePay",
            "flow": "standard",
            "supportsRecurring": false,
            "supportsFreeTrial": false,
            "images": {
                "iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/applepay.png"
            }
        },
        {
            "type": "bankTransfer",
            "flow": "redirect",
            "supportsRecurring": false,
            "supportsFreeTrial": false,
            "images": {
                "iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/bankTransfer.png"
            }
        },
        {