Drop-in integration guide

Create a payment form using Drop-in.

Getting started

You can set up Drop-in in seven easy steps:‌

Step 1: Include DigitalRiver.js on your page

Include the following script on the pages where you want it to appear (for example, the Cart or My Account page):

<script type="text/javascript" src="https://js.digitalriverws.com/v1/DigitalRiver.js"></script>

Step 2: Include the base Drop-in CSS file

Include the following link to the Drop-in CSS file on the pages where you want it to appear (for example, the Cart or My Account page). If you'd like to customize the styles, simply override the Drop-in CSS file with your own.

<link rel="stylesheet" href="https://js.digitalriverws.com/v1/css/DigitalRiver.css" type="text/css"/>

Step 3: Initialize DigitalRiver.js with your public key

Initialize the DigitalRiver.js library with your public API key and any optional parameters. If you provide a locale, Drop-in will localize the experience accordingly.

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

Step 4: Create a container for Drop-in

Create a container element for the Drop-in and place it on the page where you want it to appear within your experience.

<div id="drop-in"></div>

Step 5: Create a Configuration object for Drop-in

Create a configuration object. The object contains both required and optional values.

The following table lists the parameters for the configuration object.

Parameters

Required/Optional

Description

sessionId

Required for the checkout flow

Optional for the managePaymentMethods flow

The payment session identifier returned by Digital River.

Important: The sessionId is required if you are using Drop-in within a cart flow. If you are using Drop-in to capture payment details on a customer portal, then the sessionId is not required.

options

Optional

Drop-in specific configuration options.

billingAddress

Required

The customer's billing address.

billingAddress.firstName

Required

The customer's first name.

billingAddress.lastName

Required

The customer's last name.

billingAddress.email

Required

The customer's email address.

billingAddress.organization

Optional

The business customer's organization.

billingAddress.phoneNumber

Required

The customer's phone number.

billingAddress.address.line1

Required

The first line of the billing address.

billingAddress.address.line2

Optional

The second line of the billing address

billingAddress.address.city

Optional

City or town.

billingAddress.address.state

Optional

The state, county, province, or region.

billingAddress.address.postalCode

Required

ZIP or postal code.

billingAddress.address.country

Required

A two-letter Alpha-2 country code as described in the ISO 3166 international standard.

billingAddress.address.additional AddressInfo

Optional

Additional address information that may be useful or required for some addresses.

paymentMethodConfiguration

Optional

Additional configuration details.

For configuration structure, see Configuring payment methods within Drop-in.

onSuccess

​Content

The function called when the shopper has authorized payment and a payment source has been successfully created. Returns a Source object.

For event structure, see Drop-in Events.

onCancel

​Content

The function called when the shopper cancels the payment process before authorizing payment.

For event structure, see Drop-in Events.

onError

​Content

The function called when an error has occurred.

For event structure, see Drop-in Events.

onReady

​Content

The function called when Drop-in is ready for user interaction.

For event structure, see Drop-in Events.

In the following example, you have already collected the customer's address information.

let configuration = {
sessionId: "YOUR_SESSION_IDENTIFIER",
billingAddress: {
firstName: "John",
lastName: "Doe",
organization: "Digital River",
phoneNumber: "000-000-0000",
address: {
line1: "10380 Bren Road W",
line2: "",
city: "Minnetonka",
state: "MN",
postalCode: "55343",
country: "US"
}
},
onSuccess: function (data) { },
onCancel: function(data) { },
onError: function (data) { },
onReady: function(data) { }
}

Step 6: Use the Configuration object to create an instance of Drop-in

Create an instance of Drop-in by passing the Configuration object using the createDropin() function.

let dropin = digitalriver.createDropin(configuration);

Step 7: Place Drop-in on your Cart or Shopper page

Add the following statement to your Cart or Shopper page:

dropin.mount("drop-in");

Using Drop-in within your Cart flow

Finalize your order totals

Create a checkout and provide the necessary information to have a final total for all amounts including taxes, shipping, duties, and fees.

Initialize and place Drop-in within your application

Follow the instructions in Getting started.

From the experience page where you added the Drop-in container, customers select how they want to pay. Drop-in provides what is needed, including redirects to return a payment source that can be used in downstream API calls with the Commerce API.

The customer provides payment details

The customer may be redirected to authorize their payment.

The onSuccess event returns the source

The following source object contains the customer's payment details for a one-time charge.

{
"source": {
"clientId": "gc",
"channelId": "drdod15",
"liveMode": false,
"id": "9ddf3f08-7c56-4ce6-88b3-aee6cabe54a5",
"clientSecret": "9ddf3f08-7c56-4ce6-88b3-aee6cabe54a5_46b96409-e4f1-457e-aed9-d273e2d0c0bd",
"type": "creditCard",
"reusable": false,
"owner": {
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"organization": "Digital River",
"phoneNumber": "555-000-0000",
"upstreamId": "e1cd9cf0-2d19-49e2-9455-d89836a2b880",
"address": {
"line1": "10380 Bren Road West",
"line2": "",
"city": "Minnetonka",
"state": "MN",
"country": "US",
"postalCode": "55343"
},
},
"state": "chargeable",
"creationIp": "10.81.3.84",
"createdTime": "2020-08-27T02:05:04.557Z",
"updatedTime": "2020-08-27T02:05:04.557Z",
"flow": "standard",
"creditCard": {
"brand": "MasterCard",
"expirationMonth": 10,
"expirationYear": 2030,
"lastFourDigits": "5454",
"fundingSource": "credit"
}
},
"readyForStorage": false
}

Optional. Allowing the customer to save their payment details

During the cart flow, you may want to offer the customer the ability to save their payment details to use for future purchases. You can offer this via Drop-in. When using this solution, you must ensure that you collect the details your customer provides in a compliant manner and display required Strong Customer Authentication (SCA) prompts. You may access this mode by enabling the showSavePaymentAgreement option when configuring Drop-in.

let configuration = {
sessionId: "YOUR_SESSION_IDENTIFIER",
options: {
showSavePaymentAgreement: true
},
billingAddress: {
firstName: "John",
lastName: "Doe",
organization: "Digital River",
phoneNumber: "000-000-0000",
address: {
line1: "10380 Bren Road W",
line2: "",
city: "Minnetonka",
state: "MN",
postalCode: "55343",
country: "US"
}
},
onSuccess: function (data) { },
onCancel: function(data) { },
onError: function (data) { },
onReady: function(data) { }
}

When you enable this mode, the cart displays an optional check box that the customer must select when they agree to save their payment details on their account.

If the customer selects the check box and clicks the Add Payment button, Drop-in performs the required authentication and marks the source as ready for storage. When the source is ready for storage, the onSuccess event returns the readyForStorage value.

The readyForStorage identifier signifies the creation of the source with the intention of storage, and any necessary authentications have occurred. To reuse the source, attach it to a Shopper by calling the appropriate API with your secret key.

Using Drop-in to collect payment details on a My Account page

Initialize and place Drop-in within your application

Follow the instructions in Getting started. You do not need to provide your sessionId in your Configuration object. Instead, you should provide a flow variable that tells Drop-in you are collecting details for future use.

let configuration = {
options: {
flow: "managePaymentMethods"
}
billingAddress: {
firstName: "John",
lastName: "Doe",
organization: "Digital River",
phoneNumber: "555-000-0000",
address: {
line1: "10380 Bren Road W",
line2: "",
city: "Minnetonka",
state: "MN",
postalCode: "55343",
country: "US"
}
},
onSuccess: function (data) { },
onCancel: function(data) { },
onError: function (data) { },
onReady: function(data) { }
}

The Customer provides payment details

As part of collecting payment details for future use, the customer may be presented with Strong Customer Authentication and may also be required to agree to specific terms of storage. These details will automatically be displayed and collected to ensure compliance.

The onSuccess event returns the source

This flow presents and collects any required authentications and opt-ins. When the source collects the customer's payment details, authentication details, and opt-ins, the onSuccess event will return this information with a "readyForStorage": true parameter.

The readyForStorage identifier signifies the creation of the source with the intention of storage, and any necessary authentications have occurred. To reuse the source, attach it to a Shopper by calling the appropriate API with your secret key.

{
"source": {
"clientId": "gc",
"channelId": "drdod15",
"liveMode": false,
"id": "9ddf3f08-7c56-4ce6-88b3-aee6cabe54a5",
"clientSecret": "9ddf3f08-7c56-4ce6-88b3-aee6cabe54a5_46b96409-e4f1-457e-aed9-d273e2d0c0bd",
"type": "creditCard",
"reusable": false,
"owner": {
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"organization": "Digital River",
"phoneNumber": "555-000-0000",
"upstreamId": "e1cd9cf0-2d19-49e2-9455-d89836a2b880",
"address": {
"line1": "10380 Bren Road West",
"line2": "",
"city": "Minnetonka",
"state": "MN",
"country": "US",
"postalCode": "55343"
},
"additionalAddressInfo": {
"neighborhood": "Centro",
"phoneticFirstName": "John",
"phoneticLastName": "Doe",
"division": "Product"
}
},
"state": "chargeable",
"creationIp": "10.81.3.84",
"createdTime": "2020-08-27T02:05:04.557Z",
"updatedTime": "2020-08-27T02:05:04.557Z",
"flow": "standard",
"creditCard": {
"brand": "MasterCard",
"expirationMonth": 10,
"expirationYear": 2030,
"lastFourDigits": "5454",
"fundingSource": "credit"
}
},
"readyForStorage": true
}

Drop-in options

When creating your Drop-in instance, you can specify options to trigger different features or functionality.

Option

Value

Description

Is Default

flow

managePaymentMethods

Use this option to specify a different Drop-in mode of operation. Enable this flow if you are using Drop-in as part of a My Account page where your customer is managing their stored payment methods.

False

flow

checkout

Use this option if you are using Drop-in within a standard checkout flow.

True

showSavePaymentAgreement

true

When enabled, presents the customer with an option to save their payment details for future use within Drop-in. Enabling this feature will show the appropriate check boxes and localized disclosure statements and facilitate any necessary Strong Customer Authentication.

False

showSavePaymentAgreement

false

If disabled, Drop-in will not present the customer with an option to save their payment details.

True

showComplianceSection

true

Will show a localized compliance link section as part of Drop-in. This is an important piece for accessing the Digital River business model.

True

showComplianceSection

false

Disables the compliance section within Drop-in.

button

An object which specifies a type as well as a custom buttonText attribute.

Use this option to customize the text of the Drop-in button.

usage

subscription

convenience

unscheduled

Use this option to specify the future use of a source.

showTermsOfSaleDisclosure

true

Use this option to show the required terms of sale disclosure. These localized terms automatically update if recurring products are purchased.

showTermsOfSaleDisclosure

false

Hides the terms of sale disclosure.

True

redirect

An object that specifies the options you want to use to disable the automatic redirect functionality built into Drop-in.

Use this option if you would like to handle redirecting the customer yourself to the payment provider. See Disabling redirects within Drop-in.

Disabling redirects within Drop-in

Enable the disableAutomaticRedirects attribute if you do not want Drop-in to redirect your customer to the payment provider. Use this setting in your checkout flow if you do not want to create the order from Drop-in. In this scenario, you can allow your customer to choose their payment method, review and then authorize later by redirecting the customer to the redirect.returnUrl when the customer has reviewed the order totals and is ready to create their order.

Key

Required/Optional

Description

disableAutomaticRedirects

Required if using the redirect object.

Set to true to disable automatic redirects within Drop-in.

returnUrl

Required if using the redirect object.

The URL where the customer should be returned after successfully authorizing payment at the payment provider.

cancelUrl

Required if using the redirect object.

The URL where the customer should be returned after cancelling at the payment provider.

Redirect code example
Redirect code example
"options": {
"redirect": {
"disableAutomaticRedirects": true,
"returnUrl": "https://www.yourwebsite.com/return",
"cancelUrl": "https://www.yourwebsite.com/cancel"
}
}

Customizing the text of the Drop-in button

The text of the Drop-in button is customizable. You can either display pre-configured text or you can specify a unique text. In both cases, how the text is localized is determined by the locale you used when initializing DigitalRiver.js.

Type

Description

continue(default)

Use the following configuration to create a Continue button:

"options": { "button": { "type": "continue" } }

payNow

Use the following configuration to create a Pay Now button:

"options": { "button": { "type": "payNow" } }

buyNow

Use the following configuration to create a Buy Now button:

"options": { "button": { "type": "buyNow" } }

completeOrder

Use the following configuration to create a Submit and Complete Payment button:

"options": { "button": { "type": "completeOrder" } }

submitOrder

Use the following configuration to create a Submit Order button:

"options": { "button": { "type": "submitOrder" } }

custom

In the following configuration, use buttonText to create a button with customized text:

"options": { "button": { type": "custom". "buttonText": "Custom Text For Button" } }

Specifying a source's future use

When creating a source using Drop-in, you should identify the types of transactions the source 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 mostly 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 saved 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.

Configuring payment methods within Drop-in

Drop-in uses DigitalRiver.js elements to capture secure payment details. Drop-in comes with a predefined style that should meet most use cases. In the event you would like to customize the look and feel, you should familiarize yourself with the Styling an element container in the DigitalRiver.js documentation.

Here is an example of customizing several payment methods:

const apiKey = 'YOUR_PUBLIC_API_KEY';
digitalriver = new DigitalRiver(apiKey, {
"locale": "en-us"
});
const configuration = {
sessionId: 'd6deb2b4-347e-431e-9d56-095038e0e338',
billingAddress: {
firstName: "John",
lastName: "Doe",
organization: "Digital River",
phoneNumber: "000-000-0000",
address: {
line1: "10380 Bren Road West",
line2: "",
city: "Minnetonka",
state: "MN",
postalCode: "55346",
country: "US"
}
},
paymentMethodConfiguration: {
style: {
base: {
color: '#495057',
height: '35px',
fontSize: '1rem',
fontFamily: 'apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Helvetica Neue,Arial,sans-serif',
':hover': {
color: '#137bee',
},
'::placeholder': {
color: '#999'
},
':-webkit-autofill': {
color: 'purple'
},
':focus': {
color: 'blue'
}
},
invalid: {
color: '#dc3545',
':-webkit-autofill': {
color: '#dc3545'
}
},
complete: {
color: '#28a745',
':hover': {
color: '#28a745',
},
':-webkit-autofill': {
color: '#28a745'
}
},
empty: {
color: '#000000'
},
},
creditCard: {
cardNumberPlaceholderText: "Credit Card Number",
cardExpirationPlaceholderText: "MM/YY",
cardCvvPlaceholderText: "CVV",
style: styles,
mask: true
},
onlineBanking: {
style: styles,
placeholderText: "Select a Bank",
},
googlePay: {
style: {
buttonType: 'plain',
buttonColor: 'dark',
buttonLanguage: 'en'
}
},
applePay: {
style: {
buttonType: 'plain',
buttonColor: 'dark',
buttonLanguage: 'en'
}
},
payPal: {
style: {
label: 'checkout',
size: 'responsive',
color: 'gold',
shape: 'pill',
layout: 'horizontal',
fundingicons: 'false',
tagline: 'false'
},
},
msts: {
enrollmentUrl: "https://acmeUS.b2b.credit/en-US/apply?client_reference_id=Acme-123456&ecommerce_url=www.acme-returnURL.com",
},
},
onSuccess: function(data) {
console.log(data);
},
onError: function(data) {
console.log(data);
},
onCancel: function(data) {
console.log(data);
},
onReady: function(data) {
console.log(data);
},
};
digitalriver.createDropin(configuration).mount('dropin');

Drop-in specific configurations

Use the following fields to configure payment methods.

Payment Method

Variable

Description

creditCard

cardNumberPlaceholderText

The placeholder that appears in the card number field. If you specify a different value for cardNumberPlaceholderText, localization will not be applied.

cardExpirationPlaceholderText

The placeholder that appears in the card expiration field. If you specify a different value for cardExpirationPlaceholderText, localization will not be applied.

cardCvvPlacholderText

The placeholder that appears in the card expiration field. If you specify a different value for cardCvvPlacholderText, localization will not be applied.

style

A Style object created following the Styling an element container instructions.

mask

Indicates whether the card number and card security code fields will automatically mask the input details after successful validation.

onlineBanking

style

A Style object created following the Styling an element container instructions.

placeholderText

The placeholder text appears in the online banking selector.

googlePay

style

A Style object created following the Google Pay element styles and customization instructions.

applePay

style

A Style object created following the Apple Pay styles and customization instructions.

payPal

style

A Style object created following the PayPal element style option instructions.

msts

enrollment

An enrollment URL created following the TreviPay enrollment URL instructions.

Filtering payment methods shown in Drop-in

In the Drop-in configuration, you can optionally add a list of enabled payment methods, disabled payment methods, or both. If the list of enabled or disabled payment methods is not present, Drop-in displays all the payment methods available for the payment session. The enabled list will not add any payment methods that are not available for the payment session.

paymentMethodConfiguration:
{
enabledPaymentMethods: ['msts', 'creditCard'],
disabledPaymentMethods: ['klarna']
},

Drop-in events

Learn how to receive real-time updates on the state of your payment methods in Drop-in.

Drop-in supports the following events:

  • onSuccess–This occurs whenever a source is successfully created.

  • onError–This occurs whenever there is a validation error.

  • onCancel–This occurs whenever a payment method is cancelled.

  • onReady–This occurs whenever Drop-in has successfully mounted.

onSuccess

When your customer has provided the necessary details for payment and followed any necessary redirects, you will receive an event.

{
"source": {
"clientId": "gc",
"channelId": "paylive",
"liveMode": false,
"id": "aa388280-a8a6-4fe9-9969-a85a17a89f6d",
"sessionId": "cecf3581-e47b-4679-9b51-afbc44a15b91",
"clientSecret": "aa388280-a8a6-4fe9-9969-a85a17a89f6d_376f54df-6025-474e-bc7d-4d74ff28de8a",
"type": "creditCard",
"reusable": false,
"owner": {
"firstName": "John",
"lastName": "Doe",
"customerId": "501457412489",
"email": "[email protected]",
"organization": "Digital River",
"phoneNumber": "952-253-1234",
"address": {
"line1": "10380 Bren Road W",
"city": "Minnetonka",
"state": "MN",
"country": "US",
"postalCode": "55343"
}
},
"amount": "521.04",
"currency": "USD",
"state": "chargeable",
"upstreamId": "9C981EC0-49DB-41E3-B55C-5702A4D6EBEA",
"creationIp": "209.87.180.27",
"createdTime": "2021-02-22T20:26:08.196Z",
"updatedTime": "2021-02-22T20:26:08.196Z",
"flow": "standard",
"creditCard": {
"brand": "Visa",
"expirationMonth": 11,
"expirationYear": 2030,
"lastFourDigits": "1111"
}
},
"readyForStorage": false
}

Variable

Value

Description

source

A payment source

The created payment source.

readyForStorage

true/false

Indicates whether the source has been enabled for future use.

Important: If this value is true, it does not mean the customer can use this source multiple times. This flag identifies whether the necessary downstream actions have been triggered to prepare the source for storage. You must attach the source to your customer for it to be truly reusable.

onError

If an error occurs, Drop-in emits an event that identifies the payment method associated with the error. Instruct your customer to provide a new method of payment.

{
"paymentMethod":"googlePay"
}

onCancel

When your customer chooses to pay with a specific payment method and decides to cancel during the redirect phase, Drop-in emits an event that identifies the cancelled payment method.

{
"paymentMethod": "googlePay"
}

onReady

When ready, Drop-in will emit an event that contains a "paymentMethodTypes" array of the available payment methods.

{
"paymentMethodTypes": [
"applePay",
"creditCard",
"directDebit",
"googlePay",
"wireTransfer"
]
}