DigitalRiver object
Learn how to use the DigitalRiver object
let digitalRiver = new DigitalRiver("pk_test_fh9861t8b7384b7dke9e8dn4fb79808192", {
"locale": "en-US"
});
Use
createDropin(
config
)
to create an instance of Drop-in payments. For details, refer to the Drop-in payments integration guide. 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 | |
applepay | |
cardCVV | A card security code field |
cardExpiration | A credit card expiration field |
cardNumber | A credit card number field |
googlepay | |
ideal | |
konbini | |
onlineBanking | |
offlineRefund | |
paypal |
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>
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 |
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.
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
}
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:- 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
}
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.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.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 transactionsSet
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.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"
}
}
}
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 | |
sourceId | Required | |
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. |
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"
}
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"
}
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 Serviceresult.error
—An error occurred that must be corrected to update the source.
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"
}
}
}
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"
}
}
}
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"
}
}
}
If there is a problem with the update request, an error object will be returned in the response.
Source Errors