Drop-in Integration Guide

Drop-in is a fast and easy way to add payment methods to your store’s checkout experience.

Drop-in is a default payments integration tool that allows you to quickly enable payment methods and begin accepting payments on your website with little or no customization.

Drop-in uses the DigitalRiver.js library and provides a default look and feel that you can customize. By interpreting data collected during the checkout session, Drop-in automatically renders supported payments. Adding a new payment method does not require any additional implementation effort but may require additional configuration steps.

Drop-in allows you to use the same payment structure with our API clients (both Commerce API and Digital River API), our technology connectors (like WordPress and Magento), and our hosted store.

Supported payment methods

  • Apple Pay

  • bPay

  • Credit Cards

  • Direct Debit

  • Direct Debit UK

  • Google Pay

  • Japan COD

  • Konbini

  • Korea Bank – Bank Transfer

  • Korea PayCo

  • Online Banking

  • PayPal

  • Wire Transfer

Getting started

Digital River helps you get up and running quickly. Follow the instructions below to discover how easily you can integrate Digital River payment methods into your app or website.

Before you begin

Sign up for a Digital River test account. Contact your Sales Representative for more information.‌

Important: If you want to use Drop In with the Commerce API, ask your Account Representative to enable payment sessions for your hosted store.

Integrating Drop-in with your front end

Perform the following steps to integrate the Drop-in with your front end implementation:‌

Step 1. Include DigitalRiver.js on your page

Include the following script on your page:

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

Step 2. Include the Drop-in CSS file

Include the following link to the Drop-in CSS file on your 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 digitalriverpayments = 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. Configure Drop-in

To configure Drop-in, create a configuration object and pass it to the createDropin() function. The object contains both required and optional values. In this example, you have already collected the customer's address information.

const configuration = {
sessionId: "a0dfd128-0d55-4a44-9b02-2c075281b780",
billingAddress: {
firstName: "John",
lastName: "Doe",
email: "test@digitalriver.com",
phoneNumber: "000-000-0000",
address: {
line1: "10380 Bren Road West",
line2: "",
city: "Minnetonka",
state: "MN",
postalCode: "55346",
country: "US"
}
},
// paymentMethodConfiguration is optional. Add any custom styling per payment method. For example styles see below (have example styles of each payment method and their types somewhere or refer to the large example).
paymentMethodConfiguration: {
creditCard: {
style: {
base: {
color: "#fff",
fontFamily: "Arial, Helvetica, sans-serif",
fontSize: "16px"
}
}
},
onlineBanking: {
style: {
base: {
color: "#fff",
fontFamily: "Arial, Helvetica, sans-serif",
fontSize: "16px"
}
},
placeholderText: "Select a Bank"
}
}
}
let dropin = digitalriverpayments.createDropin(configuration);
dropin.mount("drop-in");

Configuration object

Field

Required

Description

sessionId

Required

The sessionId returned from Commerce API or Digital River API. This identifies the Payment Session created by the platform.

For Digital River API:

"paymentSessionId": "8cecaa32-f692-44cc-b103-4cf24dc93913",

For Commerce API:

"paymentSession": { "id": "8af78166-e526-40bd-9c95-1071d161a94a", "clientSecret": "8af78166-e526-40bd-9c95-1071d161a94a_4179e432-b714-4451-9137-ac08a1d9af19", "status": "requires_source" }

billingAddress

Required

The billing address of the shopper.

billingAddress.firstName

Required

The shopper's first name.

billingAddress.lastName

Required

The shoppers last name.

billingAddress.email

Required

The shopper's email address.

billingAddress.phoneNumber

Required

The shopper'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

State/County/Province/Region.

billingAddress.address.postalCode

Required

ZIP or postal code.

billingAddress.address.country

Required

Two-letter country code.

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.

Step 6. Allow the shopper to interact with Drop-in

From the experience page where you added the Drop-in container, shoppers 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 or Digital River API.

Step 7. Listen to the onSuccess event and process the source

‌When the onSuccess event fires, the source returns a state of either chargeable or pending_funds. See below for an example response:

onSuccess: function(data) {
//send to back end for processing
console.log(data);
},

‌In either state, the source can be attached to a cart or checkout with the Commerce API or Digital River API.‌

Use with Commerce API

‌You can use the Commerce API to attach the payment method to an order or cart.

{
"paymentMethod": {
"sourceId": "e7ba0595-059c-460c-bad8-2812123b9313"
}
}

Use with Digital River API

You can use the Digital River API to attach the payment method to the checkout.

{
"sourceId": "src_a78cfeae-f7ae-4719-8e1c-d05ec04e4d37"
}

Configuring payment methods within Drop-in

You can include the additional configurations when instantiating Drop-in on your payments form.

Drop-in wraps DigitalRiver.js functionality, which facilitates the display of various payment methods. Some payment methods may have additional configurations that can be set by the integrator to build a custom experience. All customization variables are optional parameters.

Customize credit card fields

Use the following fields to configure credit cards.

Key

Description

cardNumberPlaceholderText

Overwrites the default placeholder text in the card number field. If you specify a cardNumberPlaceholderText attribute, localization will not be applied.

cardExpirationPlaceholderText

Overwrites the default placeholder text in the card expiration field. If you specify a cardExpirationPlaceholderText attribute, localization will not be applied.

cardCvvPlacholderText

Overwrites the default placeholder text in the card security code field. If you specify a cardCvvPlacholderText attribute, localization will not be applied.

style

Drop-in applies an object of custom style classes as the input proceeds through its life cycle.

Available custom style classes

ID

Class Name

Description

base

Base

All other variants inherit from this style.

complete

Complete

Applied when the Element has valid input.

empty

Empty

Applied when the Element has no customer input.

focus

Focus

Applied when the Element has focus.

invalid

Invalid

Applied when the Element has invalid input.

webKitAutofill

Applied when the Element has been filled automatically by a browser.

Available custom styles

Style

ID

Type

Example

Text Color

color

string

"#fff"

Font Family

fontFamily

string

"Arial, Helvetica, sans-serif",

Font Family

fontSize

string

"20px"

Font Smoothing

fontSmoothing

string

"antialiased"

Font Style

fontStyle

string

"bold"

Font Variant

fontVariant

string

"normal"

Letter Spacing

letterSpacing

string

"2px"

Text Align

textAlign

string

"center"

Text Decoration

textDecoration

string

"underline"

Text Shadow

textShadow

string

"2px 2px #ff0000"

Font Weight

fontWeight

string

"400"

Pseudo classes

Class

ID

Type

:hover

:hover

string

:focus

:focus

string

::placeholder

::placeholder

string

::selection

::selection

string

:-webkit-autofill

:-webkit-autofill

string

:disabled

:disabled

string

PayPal button customization

Key

Description

style.color

Overwrites the default style color for the button in the PayPal selector.

style.shape

Overwrites the default style shape for the button in the PayPal selector.

Apple Pay customization

Key

Description

style.buttonType

Overwrites the default button type for the Apple Pay selector.

style.buttonColor

Overwrites the default button color for the Apple Pay selector.

Google Pay customization

Key

Description

style.buttonType

Overwrites the default button type for the Google Pay selector.

style.buttonColor

Overwrites the default button color for the Google Pay selector.

Online Banking customization

Key

Description

placeholderText

Overwrites the default placeholder text in the online banking selector. If you specify a placeholderText attribute, localization will not be applied.

style

Drop-in applies an object of custom style classes as the input proceeds through its life cycle.

Available custom style classes

ID

Class Name

Description

base

Base

All other variants inherit from this style.

complete

Complete

Applied when the Element has valid input.

empty

Empty

Applied when the Element has no customer input.

focus

Focus

Applied when the Element has focus.

invalid

Invalid

Applied when the Element has invalid input.

webKitAutofill

Applied when the Element has been filled automatically by a browser.

Available custom styles

Style

ID

Type

Example

Text Color

color

string

"#fff"

Font Family

fontFamily

string

"Arial, Helvetica, sans-serif",

Font Family

fontSize

string

"20px"

Font Smoothing

fontSmoothing

string

"antialiased"

Font Style

fontStyle

string

"bold"

Font Variant

fontVariant

string

"normal"

Letter Spacing

letterSpacing

string

"2px"

Text Align

textAlign

string

"center"

Text Decoration

textDecoration

string

"underline"

Text Shadow

textShadow

string

"2px 2px #ff0000"

Font Weight

fontWeight

string

"400"

Pseudo classes

Class

ID

Type

:hover

:hover

string

:focus

:focus

string

::placeholder

::placeholder

string

::selection

::selection

string

:-webkit-autofill

:-webkit-autofill

string

:disabled

:disabled

string

Konbini customization

Key

Description

placeholderText

Overwrites the default placeholder text in the Konbini selector. If you specify a placeholderText attribute, localization will not be applied.

style

Drop-in applies an object of custom style classes as the input proceeds through its life cycle.

Available custom style classes

ID

Class Name

Description

base

Base

All other variants inherit from this style.

complete

Complete

Applied when the Element has valid input.

empty

Empty

Applied when the Element has no customer input.

focus

Focus

Applied when the Element has focus.

invalid

Invalid

Applied when the Element has invalid input.

webKitAutofill

Applied when the Element has been filled automatically by a browser.

Available custom styles

Style

ID

Type

Example

Text Color

color

string

"#fff"

Font Family

fontFamily

string

"Arial, Helvetica, sans-serif",

Font Family

fontSize

string

"20px"

Font Smoothing

fontSmoothing

string

"antialiased"

Font Style

fontStyle

string

"bold"

Font Variant

fontVariant

string

"normal"

Letter Spacing

letterSpacing

string

"2px"

Text Align

textAlign

string

"center"

Text Decoration

textDecoration

string

"underline"

Text Shadow

textShadow

string

"2px 2px #ff0000"

Font Weight

fontWeight

string

"400"

Pseudo classes

Class

ID

Type

:hover

:hover

string

:focus

:focus

string

::placeholder

::placeholder

string

::selection

::selection

string

:-webkit-autofill

:-webkit-autofill

string

:disabled

:disabled

string

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

{
"source": {
"clientId": "gc",
"channelId": "drdod15",
"liveMode": false,
"id": "ee1c11e4-b947-45a2-b9d7-429a1154cfff",
"clientSecret": "ee1c11e4-b947-45a2-b9d7-429a1154cfff_b99c11e4-b947-45a2-b9d7-429a1154cfff",
"type": "applePay",
"reusable": false,
"owner": {
"firstName": "John",
"lastName": "Doe",
"email": "test@gmail.com",
"address": {
"line1": "10380 Bren Rd W",
"line2": "",
"city": "Hopkins",
"state": "MN",
"country": "US",
"postalCode": "55343"
}
},
"currency": "USD",
"state": "chargeable",
"creationIp": "67.216.233.5",
"createdTime": "2019-04-26T16:30:33.984Z",
"updatedTime": "2019-04-26T16:30:33.984Z",
"flow": "standard",
"applePay": {}
}
}

onError

{
"type": "validation_error",
"errors": [{
"code": "incomplete_card_number",
"message": "Please enter a valid credit card number."
}, {
"code": "incomplete_expiration_date",
"message": "Enter valid expiration year"
}, {
"code": "incomplete_security_code",
"message": "Invalid Code"
}]
}

onCancel

{
"paymentMethod": "paypal"
}

onReady

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