# DigitalRiver object
## Creating a DigitalRiver object
For details, refer to the [Initializing DigitalRiver.js](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digital-river-publishable-api-key) page.
{% code overflow="wrap" %}
```javascript
let digitalRiver = new DigitalRiver("pk_test_fh9861t8b7384b7dke9e8dn4fb79808192", {
"locale": "nl"
});
```
{% endcode %}
## Creating an instance of Drop-in
### `createDropin(config)`
Use `createDropin(`[`config`](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide#configuring-drop-in-payments)`)` to create an instance of [Drop-in payments](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in). For details, refer to the [Drop-in payments integration guide](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide).
## Creating elements
### `createElement(element, config)`
Use this method to create an instance of an [Element](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements) that you can use to capture payment details. You can use the following Elements with [`createSource()`](#creating-sources) to create a payment source.
| Element Type | Description |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amazonPay` | [AmazonPay element](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements/amazon-pay-element) |
| `applepay` | [Apple Pay element](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements/apple-pay-elements) |
| `cardCVV` | A card security code field |
| `cardExpiration` | A credit card expiration field |
| `cardNumber` | A credit card number field |
| `googlepay` | [Google Pay element](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements/google-pay-elements) |
| `iban` | [IBAN element](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements/iban-element) |
| `ideal` | [iDEAL element](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements/ideal-element) |
| `konbini` | [A Konbini element](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements/konbini-elements) |
| `onlineBanking` | [An online banking element](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements/online-banking-elements) |
| `offlineRefund` | [An offline refund data collection element](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements/offline-refund-elements) |
| `paypal` | [A PayPal element](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements/paypal-elements) |
{% tabs %}
{% tab title="Example" %}
{% code overflow="wrap" %}
```javascript
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);
```
{% endcode %}
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="JavaScript" %}
{% code overflow="wrap" %}
```javascript
```
{% endcode %}
{% endtab %}
{% endtabs %}
#### **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 a payment request
For details, refer to the [Payment request object](https://docs.digitalriver.com/digital-river-api/developer-resources/digital-river-payment-objects#payment-request-object) in the [Digital River payment objects](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digital-river-payment-objects) article.
## Creating sources
When creating sources, you can select a [method that accepts an element](#createsource-sourcedata) or use a [method that doesn't require an element](#createsource-element-sourcedata). Both methods, however, require that you provide source data to tokenize. When configuring this data, you can [specify a future source use](#specifying-a-sources-future-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](https://docs.digitalriver.com/digital-river-api/developer-resources/error-types-codes-and-objects#create-source-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](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/digitalriver.js/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.
{% tabs %}
{% tab title="Example" %}
{% code overflow="wrap" %}
```javascript
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;
}
});
```
{% endcode %}
{% endtab %}
{% endtabs %}
A successful response returns a `source` with a unique `id`.
{% tabs %}
{% tab title="Source response" %}
{% code overflow="wrap" %}
```javascript
{
"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"
}
}
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
An unsuccessful response returns an `error` with information on what must be corrected.
{% tabs %}
{% tab title="Error response" %}
{% code overflow="wrap" %}
```javascript
{
"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
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
### `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](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements) portion of this library.
* **sourceData** — The source data that you want Digital River to tokenize. See [Common payment sources](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digital-river-payment-objects) for more information on the required source data.
The method uses source data and an element argument in the following example.
{% tabs %}
{% tab title="Example" %}
{% code overflow="wrap" %}
```javascript
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;
}
});
```
{% endcode %}
{% endtab %}
{% endtabs %}
A successful response returns a `source` with a unique `id`.
{% tabs %}
{% tab title="Source response" %}
{% code overflow="wrap" %}
```javascript
{
"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"
}
}
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
An unsuccessful response returns an `error` with information on what must be corrected.
{% tabs %}
{% tab title="Error response" %}
{% code overflow="wrap" %}
```javascript
{
"error": {
"type": "validation_error",
"errors": [{
"code": "incomplete_card_number",
"message": "Your card number is incomplete."
}]
},
source: undefined
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
### 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](#subscription), [convenience](#convenience), and [unscheduled](#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](#subscription) or don't have [unscheduled](#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.
{% tabs %}
{% tab title="Example" %}
{% code overflow="wrap" %}
```javascript
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;
}
});
```
{% endcode %}
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Source response" %}
{% code overflow="wrap" %}
```javascript
{
"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"
}
}
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
## Authenticating sources
The authenticate source method determines whether a saved payment [source](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources), selected by a customer during checkout, requires [Strong Customer Authentication](https://docs.digitalriver.com/digital-river-api/payments/psd2-and-sca) (SCA).
The [first version of the method](#digitalriverjs-digitalriver.authenticatesource-data) accepts a required configuration object that contains the data we need to authenticate the source. The [second version](#digitalriverjs-digitalriver.authenticatesource-data-1) requires this same data plus a CVV [Element](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements).
| Parameter | Required/Optional | Description |
| -------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sessionId` | Required | The [payment session](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/payment-sessions) identifier of this transaction. |
| `sourceId` | Required | The identifier of the [payment source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources) 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. |
{% hint style="danger" %}
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](https://en.wikipedia.org/wiki/Transport_Layer_Security) is enabled.
{% endhint %}
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:
| 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 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](#authenticating-sources) before applying it to a transaction.
{% code overflow="wrap" %}
```javascript
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"
});
```
{% endcode %}
The following is an example response when it's determined that authentication isn't required:
{% code overflow="wrap" %}
```javascript
{
"status": "authentication_not_required"
}
```
{% endcode %}
### `authenticateSource([cvvElement], data)`
In this alternative [authenticate source method](#authenticating-sources), you can provide an optional CVV [Element](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements) (assuming it is correctly [created](#creating-elements) and [mounted](https://docs.digitalriver.com/digital-river-api/developer-resources/elements#element-mount)). By setting this parameter, the value contained in the field of the CVV Element is included in the authentication request.
{% code overflow="wrap" %}
```javascript
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"
});
```
{% endcode %}
The following is an example response when a source is successfully authenticated:
{% code overflow="wrap" %}
```javascript
{
"status": "complete"
}
```
{% endcode %}
## Updating sources
### **`updateSource([element,] sourceData)`**
Use this method to update details on a source.
{% hint style="warning" %}
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](#createsource-sourcedata).
{% endhint %}
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.
| 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**
{% tabs %}
{% tab title="Example" %}
{% code overflow="wrap" %}
```javascript
//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;
}
});
```
{% endcode %}
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Source Response" %}
{% code overflow="wrap" %}
```javascript
{
"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"
}
}
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
#### **Updating only address information**
{% tabs %}
{% tab title="Example" %}
{% code overflow="wrap" %}
```javascript
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;
}
});
```
{% endcode %}
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Source Response" %}
{% code overflow="wrap" %}
```javascript
{
"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"
}
}
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
#### **Updating only card expiration information**
{% tabs %}
{% tab title="Example" %}
{% code overflow="wrap" %}
```javascript
//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;
}
});
```
{% endcode %}
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Source Response" %}
{% code overflow="wrap" %}
```javascript
{
"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"
}
}
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
#### **Update error**
If there is a problem with the update request, an error object will be returned in the response.
{% tabs %}
{% tab title="Source Errors" %}
{% code overflow="wrap" %}
```javascript
{
"error": {
"type": "validation_error",
"errors": [{
"code": "incomplete_card_number",
"message": "Your card number is incomplete."
}]
},
```
{% endcode %}
{% endtab %}
{% endtabs %}
## 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.
| Attribute | Required/Optional | Description |
| ----------------- | ----------------- | -------------------------------------------------------------------------------------------------------------- |
| 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.
{% tabs %}
{% tab title="Request Example" %}
{% code overflow="wrap" %}
```javascript
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
});
```
{% endcode %}
{% endtab %}
{% endtabs %}
The following response includes all payment methods that you configured for your account.
{% tabs %}
{% tab title="Response Example" %}
{% code overflow="wrap" %}
```javascript
{
"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"
}
},
{
"type": "carrierFinancing",
"flow": "standard",
"supportsRecurring": false,
"supportsFreeTrial": false,
"images": {}
},
{
"type": "codJapan",
"flow": "standard",
"supportsRecurring": false,
"supportsFreeTrial": false,
"images": {
"iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/codJapan.png"
}
},
{
"type": "creditCard",
"flow": "standard",
"supportsRecurring": true,
"supportsFreeTrial": true,
"images": {
"iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/creditcard.png"
}
},
{
"type": "creditInstallment",
"flow": "redirect",
"supportsRecurring": false,
"supportsFreeTrial": false,
"images": {},
"terms": [
{
"id": "8281",
"name": "4x installment for Cetelem",
"code": "4_months",
"underMinimumAmount": 0,
"overMaximumAmount": 0,
"durationMonths": 4,
"monthlyPaymentAmount": 25.21,
"monthlyPaymentWithFeesAmount": 30.21,
"orderTotal": 100,
"totalRepayable": 120.84,
"creditChargeAmount": 20.84,
"originationFeeAmount": 5,
"administrationFeeAmount": 0,
"nominalApr": 4,
"effectiveApr": 151.1
}
]
},
{
"type": "directDebit",
"flow": "redirect",
"supportsRecurring": true,
"supportsFreeTrial": false,
"images": {
"iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/directDebit.png"
}
},
{
"type": "directDebitGb",
"flow": "redirect",
"supportsRecurring": true,
"supportsFreeTrial": false,
"images": {
"iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/directDebitGb.png"
}
},
{
"type": "googlePay",
"flow": "standard",
"supportsRecurring": true,
"supportsFreeTrial": true,
"images": {
"iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/googlepay.png"
}
},
{
"type": "klarnaCredit",
"flow": "redirect",
"supportsRecurring": false,
"supportsFreeTrial": false,
"images": {
"iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/klarna.png"
}
},
{
"type": "klarnaCreditRecurring",
"flow": "redirect",
"supportsRecurring": true,
"supportsFreeTrial": false,
"images": {
"iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/klarnaRecurring.png"
}
},
{
"type": "konbini",
"flow": "receiver",
"supportsRecurring": false,
"supportsFreeTrial": false,
"images": {
"iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/konbini.png"
}
},
{
"type": "onlineBanking",
"flow": "redirect",
"supportsRecurring": false,
"supportsFreeTrial": false,
"images": {
"iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/onlineBanking.png"
}
},
{
"type": "payco",
"flow": "redirect",
"supportsRecurring": false,
"supportsFreeTrial": false,
"images": {
"iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/payco.png"
}
},
{
"type": "payPal",
"flow": "redirect",
"supportsRecurring": false,
"supportsFreeTrial": false,
"images": {
"iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/paypal.png"
}
},
{
"type": "payPalBilling",
"flow": "redirect",
"supportsRecurring": true,
"supportsFreeTrial": true,
"images": {
"iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/paypalBilling.png"
}
},
{
"type": "wireTransfer",
"flow": "receiver",
"supportsRecurring": false,
"supportsFreeTrial": false,
"images": {
"iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/wireTransfer.png"
}
}
]
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
#### Retrieve available payment methods response using filters
The following example shows a request using filters.
{% tabs %}
{% tab title="Request Example" %}
{% code overflow="wrap" %}
```javascript
digitalriver.retrieveAvailablePaymentMethods({
"currency": "USD",
"country": "US",
"supportsRecurring": true
}).then(function(result) {
//do something with the result, this could include showing or hiding specific payment methods that are applicable to the display
});
```
{% endcode %}
{% endtab %}
{% endtabs %}
The following response only returns payment methods available in the US, using the USD currency and supporting recurring payments.
{% tabs %}
{% tab title="Response example" %}
{% code overflow="wrap" %}
```javascript
{
"paymentMethods": [
{
"type": "creditCard",
"flow": "standard",
"supportsRecurring": true,
"supportsFreeTrial": true,
"images": {
"iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/creditcard.png"
}
},
{
"type": "googlePay",
"flow": "standard",
"supportsRecurring": true,
"supportsFreeTrial": true,
"images": {
"iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/googlepay.png"
}
},
{
"type": "klarnaCreditRecurring",
"flow": "redirect",
"supportsRecurring": true,
"supportsFreeTrial": false,
"images": {
"iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/klarnaRecurring.png"
}
},
{
"type": "payPalBilling",
"flow": "redirect",
"supportsRecurring": true,
"supportsFreeTrial": true,
"images": {
"iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/paypalBilling.png"
}
}
]
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
#### Retrieve available payment methods response with a Session ID
If you specify a Payment Session ID, you will only receive the payment methods that apply to your transaction.
{% tabs %}
{% tab title="Request Example" %}
{% code overflow="wrap" %}
```javascript
digitalriver.retrieveAvailablePaymentMethods({
"sessionId": "d3941a36-6821-4d93-be23-6190226ae5f7"
}).then(function(result) {
//do something with the result, this could include showing or hiding specific payment methods that are applicable to the display
});
```
{% endcode %}
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Response Example" %}
{% code overflow="wrap" %}
```javascript
{
"sessionInformation": {
"currency": "EUR",
"country": "FR",
"amount": "450.00"
},
"paymentMethods": [
{
"type": "applePay",
"flow": "standard",
"supportsRecurring": false,
"supportsFreeTrial": false,
"images": {
"iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/applepay.png"
}
},
{
"type": "creditCard",
"flow": "standard",
"supportsRecurring": true,
"supportsFreeTrial": true,
"images": {
"iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/creditcard.png"
}
},
{
"type": "directDebit",
"flow": "redirect",
"supportsRecurring": true,
"supportsFreeTrial": false,
"images": {
"iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/directDebit.png"
}
},
{
"type": "googlePay",
"flow": "standard",
"supportsRecurring": true,
"supportsFreeTrial": true,
"images": {
"iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/googlepay.png"
}
},
{
"type": "wireTransfer",
"flow": "receiver",
"supportsRecurring": false,
"supportsFreeTrial": false,
"images": {
"iconImage": "https://ui1.img.digitalrivercontent.net/Storefront/images/paymentMethodLogos/wireTransfer.png"
}
}
]
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
### Credit card logos
If you want to display the credit card payment logo on your website, you can use the following URLs to add the appropriate brand logo image to your website:
{% hint style="info" %}
**Best Practices**: To ensure you always use the latest logo, link to the URL instead of downloading the image to your website.
{% endhint %}
* **Visa**  **URL**:
* **Mastercard**  **URL**:
* **American Express**  **URL**:
* **Discover**  **URL**:
* **JCB**  **URL**:
* **Maestro**  **URL**:
* **UnionPay**  **URL**:
## Retrieving available banks for Online Banking
### `retrieveOnlineBankingBanks(countryCode, currency)`
Use this method to retrieve an array of available banks for a combination of [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code and [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code.
This method returns an array that will either be empty if no banks are available or 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 want to build a bank selector instead of using the Online Banking element.
{% tabs %}
{% tab title="Example" %}
{% code overflow="wrap" %}
```javascript
digitalriver.retrieveOnlineBankingBanks("DE","EUR").then(function(result) {
//do something with the banks, this could include building a selector or something else
});
```
{% endcode %}
{% endtab %}
{% endtabs %}
{% tabs %}
{% tab title="Source response" %}
{% code overflow="wrap" %}
```javascript
[{
"bankCode": "86",
"bankName": "Sofortüberweisung"
}, {
"bankCode": "21",
"bankName": "Giropay"
}]
```
{% endcode %}
{% endtab %}
{% endtabs %}
## Getting compliance details
The [`DigitalRiver` object](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object) exposes [`Compliance.getDetails()`](#compliance.getdetails), which returns various disclosures, such as terms of sale, privacy policies, save payment agreements, and cancellation rights, that you can use to ensure sales adhere to compliance requirements.
### `Compliance.getDetails()`
`Compliance.getDetails()` accepts a configuration object, which consists of a [`language`](#language), [`country`](#country), and [`businessEntityCode`](#businessentitycode), all of which are required. This increases the probability that Digital River can return appropriately translated disclosures that apply to the customer’s shopping country and the transaction’s [selling entity](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/selling-entities).
{% code overflow="wrap" %}
```javascript
let config = {
'language': 'en',
'country': 'DE',
'businessEntityCode': 'DR_IRELAND-ENTITY'
};
var complianceDetails = digitalRiver.Compliance.getDetails(config);
```
{% endcode %}
#### `language`
A required string that determines the language each [`disclosure`](#compliance.getdetails-response) is translated into. The value you assign this property doesn't affect which specific disclosures are returned, only how their text is rendered.
For a list of accepted values, refer to [Supported languages](https://app.gitbook.com/s/ZrhMyLX5esFYS64lNWVW/digital-river-api-reference-guide/supported-languages).
#### `country`
A required string, formatted as an [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code, represents the customer's shopping country. Since legal requirements vary slightly from country to country, the value you assign to this property determines which specific disclosures Digital River returns. For example, some `country` values return a customer's cancellation rights, while others do not.
If the transaction involves [physical products](https://docs.digitalriver.com/digital-river-api/product-management/skus#how-products-are-classified-as-physical-or-digital), `country` should ideally be the same as the customer’s ship to country. If customers only purchase [digital products](https://docs.digitalriver.com/digital-river-api/product-management/skus#how-products-are-classified-as-physical-or-digital), you can use their billing country.
#### `businessEntityCode`
A required string that represents the transaction's designated [selling entity](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/selling-entities). Similar to `country`, this affects which disclosures Digital River returns.
{% hint style="success" %}
In [checkouts](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Checkouts), you can find this value in `sellingEntity.id`.
{% endhint %}
For a list of accepted values, refer to [Supported selling entities](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/selling-entities#supported-selling-entities).
### `Compliance.getDetails()` response
[`Compliance.getDetails()`](#compliance.getdetails) returns a [`disclosure`](#disclosure) which contains individual disclosures, such as `termsOfSale` and `privacyPolicy`, that you can display to customers. However, Digital River returns an [error](#error) if the function's parameters are missing or unsupported.
#### `disclosure`
In most cases, the nested objects in `disclosure` contain `localizedText` and the `url` of a Digital River-hosted document.
{% tabs %}
{% tab title="Example disclosure " %}
In the following `disclosure`, the text is rendered in English, and the content applies to customers purchasing in Germany facilitated by the Digital River Ireland Ltd. [selling entity](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/selling-entities).
{% code overflow="wrap" %}
```json
{
"businessEntity": {
"name": "Digital River Ireland Ltd.",
"id": "DR_IRELAND-ENTITY"
},
"autorenewalPlanTerms": {
"localizedText": "By checking the box below and completing your purchase, you expressly authorize and permit Digital River to automatically renew your purchased license or subscription for successive renewal terms each equal in length to the initial term specified above, at the purchase price for your initial term (plus taxes and fees, less any applicable discounts) using the payment information you provided for your initial purchase, until you cancel. At least one email will be sent to you to remind you of each upcoming renewal. We may change the renewal price as of the next renewal date if we provide you with prior notice of the change by email (you can elect to cancel automatic renewal as described below if you do not agree to the change). The Digital River Terms of Sale and Privacy Policy will apply to each renewal transaction. You may cancel your auto-renewal plan at any time by logging into the account interface (access information will be included in your order confirmation email or on the Customer Service Help page), selecting your product, and selecting the option to disable automatic renewal.
I agree that Digital River may store my payment information for future purchases including the processing of any subsequent subscription renewals which may occur following the date of this order."
},
"saveCardMandate": {
"localizedText": "Yes, please save this account and payment information for future purchases."
},
"idealRecurringAgreement": {
"localizedText": "By clicking the box, you authorize Digital River to collect your first payment via iDEAL and use your IBAN to collect the subsequent subscription payments by SEPA direct debit. You can review your SEPA Direct Debit information after order submission.
As part of your rights, you are entitled to a refund from your bank under the terms and conditions of your agreement with your bank. A refund must be claimed within 8 weeks starting from the date on which your account was debited. "
},
"confirmDisclosure": {
"localizedText": "By submitting my order, I agree to the Terms of Sale and the Privacy Policy of Digital River Ireland Ltd."
},
"privacyPolicy": {
"localizedText": "Privacy Policy",
"url": "https://store.digitalriver.com/store/defaults/en_IE/DisplayDRPrivacyPolicyPage/eCommerceProvider.Digital%20River%20Ireland%20Ltd."
},
"termsOfSale": {
"localizedText": "Terms of Sale",
"url": "https://store.digitalriver.com/store/defaults/en_IE/DisplayDRTermsAndConditionsPage/eCommerceProvider.Digital%20River%20Ireland%20Ltd."
},
"cookiePolicy": {
"localizedText": "Cookies",
"url": "https://store.digitalriver.com/store/defaults/en_IE/DisplayDRCookiesPolicyPage/eCommerceProvider.Digital%20River%20Ireland%20Ltd."
},
"legalNotice": {
"localizedText": "Legal Notice",
"url": "https://store.digitalriver.com/store/defaults/en_IE/DisplayDRContactInformationPage/eCommerceProvider.Digital%20River%20Ireland%20Ltd."
},
"cancellationRights": {
"localizedText": "Cancellation Right",
"url": "https://store.digitalriver.com/store/defaults/en_IE/DisplayDRTermsAndConditionsPage/eCommerceProvider.Digital%20River%20Ireland%20Ltd.#cancellationRight"
},
"resellerDisclosure": {
"localizedText": "Digital River Ireland Ltd. is the authorised retailer and merchant providing e-commerce services for this shop.",
"url": "https://store.digitalriver.com/store/defaults/en_IE/DisplayDRAboutDigitalRiverPage/eCommerceProvider.Digital%20River%20Ireland%20Ltd."
}
}
```
{% endcode %}
{% endtab %}
{% tab title="Description of individual disclosures " %}
* `businessEntity`: The [selling entity's ](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/selling-entities)name and identifier.
* `resellerDisclosure`: Digital River's reseller disclosure.
* `termsOfSale:` Digital River's terms of sale.
* `privacyPolicy`: Digital River's privacy policy.
* `cookiePolicy`: Digital River's cookie policy.
* `cancellationRights`: An explanation of a customer's cancellation rights.
* `legalNotice`: Digital River's legal notice.
* `confirmDisclosure`: Digital River's confirmation disclosure statement. Place this disclosure next to your confirm order button.
* `autorenewalPlanTerms`: Digital River's autorenewal terms.
* `idealRecurringAgreement`: Digital River's [iDEAL](https://docs.digitalriver.com/digital-river-api/payments/supported-payment-methods/ideal) recurring payment agreement.
* `saveCardMandate`: The save payment methods for future purchase agreements.
* `californiaPrivacyRights`: An explanation of a customer's California privacy rights.
* `invoiceAgreement`: Digital River's [e-invoicing](https://docs.digitalriver.com/digital-river-api/using-our-services/e-invoicing) agreement.
* `warrantyInformation`: An explanation of warranty information applicable to residents of Italy.
{% endtab %}
{% endtabs %}
#### `Error`
If [`language`](#language), [`country`](#country), or [`businessEntityCode`](#businessentitycode) are not defined or are assigned an unsupported value, then [`Compliance.getDetails()`](#compliance.getdetails) returns a console error.
```
Uncaught Error: businessEntityCode is missing or unsupported, country is missing or unsupported, language is missing or unsupported
```