Drop-in payments integration guide
Learn how to integrate Drop-in payments
This page explains how to get started integrating Drop-in payments into both checkout flows and account management flows.
We recommend you also use the Drop-in payments builder and the Building payment workflows page to learn how to integrate our supported payment methods into your app or website.

Getting started

Follow these steps to set up Drop-in payments:‌

Step 1: Include DigitalRiver.js

Include the following script on the pages where you want Drop-in payments to display (for example, on checkout or account management pages):
<script type="text/javascript" src="https://js.digitalriverws.com/v1/DigitalRiver.js"></script>

Step 2: Include the base CSS file

On the same pages, include the following link to the Drop-in payments CSS file. If you'd like to customize styles, simply override this 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. If you provide locale, then Drop-in payments is localized based on that value.
let digitalriver = new DigitalRiver("YOUR_PUBLIC_API_KEY", {
"locale": "en-US"
});

Step 4: Create a Drop-in payments container

Create a container element on the page where you want Drop-in payments to appear.
<div id="drop-in"></div>

Step 5: Create a Drop-in payments configuration object

Create a configuration object. For details, refer to Configuring Drop-in payments.
let configuration = {
"sessionId": "7637affb-cb4a-4d9a-815c-d4e6e393e28f",
"options": {
"button": {
"type": "submitOrder"
},
"flow": "checkout",
"showComplianceSection": true,
"showSavePaymentAgreement": true,
"showTermsOfSaleDisclosure": true,
"usage": "unscheduled"
},
onSuccess: function(data) {},
onError: function(data) {},
onReady: function(data) {},
onCancel: function(data) {}
}

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

Create an instance of Drop-in payments by passing the configuration object to createDropin().
let dropin = digitalriver.createDropin(configuration);

Step 7: Mount Drop-in payments on the checkout or account management page

Add the following statement to the appropriate checkout or account management page:
dropin.mount("drop-in");
Once invoked, mount() displays Drop-in payments in the designated container.

Using Drop-in payments in checkouts

To use Drop-in payments in checkout flows, you'll need to (1) finalize your checkout, (2) configure and mount Drop-in payments, and (3) handle the onSuccess event.

Finalize the checkout

Prior to interacting with Drop-in payments, your integration should obtain the customer's billing information and use it to set the checkout's billTo.
For more details, refer to Billing address requirements on the Providing address information page.
The checkout's totalAmount should also be finalized. So, when applicable, make sure you've set the checkout's shipFrom, shipTo, shippingDiscount, shippingChoice, taxIdentifiers[] and any other data that may affect totalAmount.

Configure and mount Drop-in payments

Retrieve the checkout's payment.session.id and use it to set sessionId in the Drop-in payments' configuration object. In that same object, you should also set:
...
let configuration = {
"sessionId": "7637affb-cb4a-4d9a-815c-d4e6e393e28f",
"options": {
"button": {
"type": "submitOrder"
},
"flow": "checkout",
"showComplianceSection": true,
"showTermsOfSaleDisclosure": true
},
onSuccess: function(data) {},
onError: function(data) {},
onReady: function(data) {},
onCancel: function(data) {}
}
let dropin = digitalriverpayments.createDropin(configuration);
dropin.mount("drop-in-container");
Once the create and mount methods are invoked, Drop-in payments opens on the experience page that holds the container element. For more details on this process, refer to the Getting started section.
Customers then select how they want to pay.
Depending on which payment method customers select, they may be redirected to a third-party payment authorization site. Drop-in payments handles all these redirects.

Handle the onSuccess event

If customers supply the required information, click the configurable button, and payment is successfully authorized, you should handle onSuccess by passing source.id to your back-end and using your secret API key to associate the source with the checkout.
In the following example, the data object of onSuccess contains a source whose state is chargeable. Since readyForStorage is false, this source can only be used one-time (i.e., it can't generate multiple charges).
{
"source": {
"clientId": "gc",
"channelId": "paylive",
"liveMode": false,
"id": "ebca2f55-1667-4e30-84be-68bb1be115f8",
"sessionId": "02a86286-4924-41fa-ae82-dbafec952cb3",
"clientSecret": "ebca2f55-1667-4e30-84be-68bb1be115f8_e9c65c5f-6778-4351-9230-2bdfa5f6de98",
"type": "creditCard",
"reusable": false,
"owner": {
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"phoneNumber": "952-253-1234",
"organization": "Digital River",
"address": {
"line1": "10380 Bren Road W",
"city": "Minnetonka",
"state": "MN",
"country": "US",
"postalCode": "55343"
}
},
"amount": "521.04",
"currency": "USD",
"state": "chargeable",
"creationIp": "73.65.125.164",
"createdTime": "2022-05-31T18:27:43.543Z",
"updatedTime": "2022-05-31T18:27:43.543Z",
"flow": "standard",
"language": "en",
"creditCard": {
"brand": "Visa",
"expirationMonth": 12,
"expirationYear": 2023,
"lastFourDigits": "1111"
}
},
"readyForStorage": false,
"supportsStorage": true
}

Optional. Allowing customers to save their payment information

During checkout flows, you can also give customers the opportunity to save their payment details for use in future transactions by enabling showSavePaymentAgreement.
This feature ensures that a customer's payment details are collected in a PSD2 and SCA compliant manner.
...
let configuration = {
"sessionId": "d5437992-c2d3-4cc9-9be5-c49a9ed68bbb",
"options": {
"flow": "checkout",
"showSavePaymentAgreement": true
}
onSuccess: function(data) {},
onError: function(data) {},
onReady: function(data) {},
onCancel: function(data) {}
}
let dropin = digitalriverpayments.createDropin(configuration);
dropin.mount("drop-in-container");
When you enable this feature, each displayed reusable payment method is accompanied by a box that customers must check if they want that payment information saved to their account.
If customers check the box and click the configurable button, Drop-in payments performs any required authentications and, assuming that process is successful, the data object of onSuccess contains a source that is readyForStorage.
In this case, handle onSuccess by passing source.id to your back-end and using your secret API key to first associate the source with the customer before you associate the source with the checkout.

Using Drop-in payments in an account management portal

If your integration allows customers to save payment methods outside of a checkout flow, you can add Drop-in payments to their account management portal.
In this flow, the Drop-in payments' configuration object doesn't require a sessionId. Instead, you should set options.flow to managePaymentMethods. This informs Digital River that you're collecting and saving payment information in an account management setting.
Since you're not referencing a payment session, you'll need to use the configuration object's billingAddress to pass the billing information you collect from customers.
There's no need to enable showComplianceSection, showTermsOfSaleDisclosure, and showSavePaymentAgreement since those features only need to be turned on in checkout flows.
let configuration = {
options: {
flow: "managePaymentMethods",
usage: "convenience"
}
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"
}
},
...
}

Configure and mount Drop-in payments

Once the create and mount methods are invoked, Drop-in payments opens on the experience page that holds the container element. For more details on this process, refer to the Getting started section.
Customers then select the payment method they want added to their account and agree to specific storage terms. They may also be required to complete SCA, a process that Drop-in payments handles.

Handle onSuccess

If Digital River successfully creates a payment source, the data object of onSuccess contains a source that is readyForStorage. Handle the event by sending source.id to your back-end and using your secret API key to associate the source with the customer.

Configuring Drop-in payments

The createDropIn() method requires a configuration object. You can use this object to:
...
let configuration = {
"sessionId": "d5437992-c2d3-4cc9-9be5-c49a9ed68bbb",
"options": {
"button": {
"type": "custom",
"buttonText": "A fully customized button"
},
"flow": "checkout",
"redirect": {
"disableAutomaticRedirects": true,
"returnUrl": "https://mysite.com/success",
"cancelUrl": "https://mysite.com/cancel"
},
"showComplianceSection": true,
"showSavePaymentAgreement": true,
"showTermsOfSaleDisclosure": true,
"usage": "unscheduled",
"consents": {
"companyName": "Cool Company",
"eula": {
"url":https: //myecommercesite.com/eula
},
"termsOfUse": {
"url":https: //myecommercesite.com/termsOfUse
}
}
},
"paymentMethodConfiguration": {
"enabledPaymentMethods": [
"alipay",
"bankTransfer"
]
},
onSuccess: function(data) {},
onError: function(data) {},
onReady: function(data) {},
onCancel: function(data) {},
"billingAddress": {
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"organization": "Digital River",
"phoneNumber": "952-253-1234",
"address": {
"line1": "10380 Bren Road W",
"city": "Minnetonka",
"state": "MN",
"postalCode": "55343",
"country": "US"
}
}
}
...

Payment session identifier

The sessionId uniquely identifies a payment session.
...
let configuration = {
"sessionId": "d5437992-c2d3-4cc9-9be5-c49a9ed68bbb",
...
}
...
If options.flow is checkout, you'll need to use the checkout's payment.session.id to set sessionId. DigitalRiver.js uses that identifier to look up the customer's billing address that you assigned to the checkout's billTo.
In checkout flows, Digital River recommends that, prior to calling createDropin(), you pass the customer's billing information in the checkout's billTo. By doing so, you can use the checkout's tax data to present customers with finalized tax amounts before moving into the payment collection stage.
If you set options.flow to managePaymentMethods, then you don't need to pass a sessionId. But, as a result, you're required to send a customer's billing information in billingAddress.

Options

The options object allows you to:
...
let configuration = {
...
"options": {
"flow": "checkout",
"showSavePaymentAgreement": true,
"showComplianceSection": true,
"button": {
"type": "custom",
"buttonText": "A fully customized button"
},
"usage": "unscheduled",
"showTermsOfSaleDisclosure": true,
"redirect": {
"disableAutomaticRedirects": true,
"returnUrl": "https://mysite.com/success",
"cancelUrl": "https://mysite.com/cancel"
},
"consents": {
"companyName": "Cool Company",
"eula": {
"url":https: //myecommercesite.com/eula
},
"termsOfUse": {
"url":https: //myecommercesite.com/termsOfUse
}
}
},
...
}
...

Flow

Use options.flow to specify a mode of operation.
If you're using Drop-in payments in a checkout flow, set flow to checkout (default).
If you're using Drop-in payments in an account management flow, then set flow to managePaymentMethods. This setting informs Digital River that you're collecting and saving a customer's payment information for use in future transactions and that you're doing so outside of a checkout flow.

Show save payment agreement

The options.showSavePaymentAgreement attribute determines whether customers are given the option to save a selected payment method to their account.
You only need to set this flag when options.flow is checkout. If options.flow is managePaymentMethods, then the save payment agreement is automatically displayed.
If showSavePaymentAgreement is true, and the selected payment method supports reusability, then customers are presented with a box that they must check if they want to save the payment method. With this setting, Digital River displays appropriate localized disclosure statements and handles any needed SCA.
If set to false (default), customers are not given the option to save their payment details.

Show compliance section

The options.showComplianceSection attribute determines whether Drop-in payments displays compliance information.
If true (default), then Drop-in payments displays a selling entity specific compliance section. The information in this section is localized based on how you initialize DigitalRiver.js.
Making this compliance information available to customers is a critical part of gaining access to Digital River's merchant of record business model.
If false, then the compliance section is not displayed.

Customizing the text of the Drop-in button

By setting options.button.type to any of the following values, you can customize the text of the Drop-in payments button.
These settings don't change the text of Google Pay and Pay Pal buttons. For information on styling these buttons, refer to Payment method configurations.
The button's text is localized based on the locale you pass when initializing DigitalRiver.js.
Value
Output (locale of en-US)
continue (default)
payNow
buyNow
completeOrder
submitOrder
You also have the ability to fully personalize the text by setting button.type to custom and button.buttonText to the characters you want displayed.

Specifying a source's future use

Set options.usage to indicate how the payment source is likely to be used in future transactions. Passing this value increases the probability that payment providers will approve future authorization requests. The accepted values are subscription, convenience, and unscheduled.
  • subscription: the source is to be used for recurring transactions, made at regular intervals, for a product or a service.
  • convenience: applies mainly to saved payment sources that are used for one-off transactions. These are scenarios where customers are typically present during the checkout flow and want to quickly access their payment information. Always select this option if you don't offer subscriptions or don't have unscheduled merchant initiated transactions
  • unscheduled: the source is to be used in unscheduled merchant-initiated transactions. These are contracts that occur on a non-fixed schedule using saved card information. Automatic top-ups are one such example. They occur whenever a customer's balance drops below a pre-defined amount.

Show terms of sale disclosure

The options.showTermsOfSaleDisclosure attribute determines whether Drop-in payments displays the terms of sale to customers.
If set to true (default), then the terms of sale disclosure are displayed and customers must accept them.
The terms are localized based on how you initialize DigitalRiver.js.
The actual terms depend on whether customers are making a one-time purchase or buying a subscription product.
One-time purchase
Subscription acqusition
If set to false, no terms of sale are displayed.

Add disclosures

You can use options.consents to add your end user license agreement and terms of use to Digital River's disclosures. To make this feature work, showTermsOfSaleDisclosure must be true.
If you pass consents, then companyName is required. You're not required to provide either eula or termsOfUse, but if you do, you must specify a url that links to the relevant document.
...
let configuration = {
...
"options": {
...
"showTermsOfSaleDisclosure": true,
...
"consents": {
"companyName": "Cool Company",
"eula": {
"url": "https: //myecommercesite.com/eula"
},
"termsOfUse": {
"url": "https: //myecommercesite.com/termsOfUse"
}
}
},
...
}
...
Once you create and mount Drop-in payments, your consents are appended to Digital River's disclosures.

Disabling redirects

The options.redirect object 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.
Enable the disableAutomaticRedirects attribute if you do not want Drop-in payments 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.
Choose one of the following options:
  • Set to true to disable automatic redirects within Drop-in.
  • Set to false to enable automatic redirects within Drop-in and return a redirect URL to follow in the POST /orders response. This option is required for Pay with Installments France.
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.
"options": {
"redirect": {
"disableAutomaticRedirects": true,
"returnUrl": "https://www.yourwebsite.com/return",
"cancelUrl": "https://www.yourwebsite.com/cancel"
}
}

Expand first payment method

When Drop-in payments loads, options.expandFirstPaymentMethod determines whether the first payment method in the accordion control element is expanded or collapsed.
Expanded
Collapsed
If expandFirstPaymentMethod is true(default) then the first displayed payment method is expanded.
If expandFirstPaymentMethod is false, then the first displayed payment method is collapsed.

Payment method configurations

The configuration object's paymentMethodConfiguration allows you to customize payment methods.
...
const configuration = {
...
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",
},
enabledPaymentMethods: ['msts', 'creditCard'],
disabledPaymentMethods: ['klarna']
},
...
};
digitalriver.createDropin(configuration).mount("dropin");

Style

Drop-in payments uses elements to capture secure payment details. These elements have a predefined style, but you can also customize their look and feel by defining a style object.
For details, refer to Styling an element container.

Credit card

The creditCard object allows you to configure how credit cards are displayed.
  • cardNumberPlaceholderText: The placeholder that appears in the card number field. If you specify a value, then localization is not applied.
  • cardExpirationPlaceholderText: The placeholder that appears in the card expiration date field. If you specify a value, then localization is not applied.
  • cardCvvPlacholderText: The placeholder that appears in the card security code field. If you specify a value, then localization is not applied.
  • style: For details, refer to Styling an element container.
  • mask: Indicates whether data entered in card number and card security code fields is automatically masked after successful validation.

Online banking

The onlineBanking object allows you to configure how the online banking payment method is displayed.

Google Pay

For details on googlePay.style, refer to Google Pay element styles and customization.

Apple Pay

For details on applePay.style, refer to Apple Pay styles and customization.

Pay pal

For details on payPal.style, refer to PayPal element style options.

MSTS

Use msts.enrollmentUrl to add a link to the TreviPay enrollment URL.

Enable and disable payment methods

Use enabledPaymentMethods and disabledPaymentMethods to enable and disable specific payment methods.
If you don't enumerate either of these lists, then by default Drop-in payments displays all transaction-applicable payment methods. If enabledPaymentMethods contains a payment method that's not transaction-applicable, then it's not displayed.

Drop-in payment events

The Drop-in payments' configuration object supports the following events:
  • onSuccess: Occurs when a source is successfully created
  • onError: Occurs when there's a validation error
  • onCancel: Occurs when a payment method is cancelled
  • onReady: Occurs when Drop-in payments is ready to accept input
These events provide real-time updates on the status of payment methods.
...
let configuration = {
...
onSuccess: function(data) {},
onError: function(data) {},
onReady: function(data) {},
onCancel: function(data) {}
...
}
...

onSuccess

Once customers supply their payment details, follow any required redirects, and successfully authorize payment, you receive the onSuccess event. The event's data object contains a source .
That same data object also contains a readyForStorage boolean. If readyForStorage is true then (1) customers gave approval for you to save the source to their account and (2) Digital River has performed any required SCA.
A readyForStorage value of true doesn't indicate that customers can reuse that same source in multiple transactions. To accomplish that, you must associate the source with the customer. This flips the source's reusable value to true.
If you set showTermsOfSaleDisclosure to true, then the event's data contains consents. The termsOfSale boolean references Digital River's terms of sale. The eula and termsOfUse booleans indicate whether consents in the configuration object contains a eula.url and/or termsOfUse.url.
When these event variables are true, it signifies customers were presented with that specific disclosure and actively accepted it.
{
"source": {
"clientId": "gc",
"channelId": "paylive",
"liveMode": false,
"id": "ab1fce40-e8a3-4b62-86a1-8a524111c4e7",
"sessionId": "c09e1774-4f6d-47da-8617-ba42a87dd5e8",
"clientSecret": "ab1fce40-e8a3-4b62-86a1-8a524111c4e7_9b6021c7-c813-4314-b8ee-a1180f4ee80a",
"type": "creditCard",
"reusable": false,
"owner": {
"firstName": "Fred",
"lastName": "Flintstone",
"email": "[email protected]",
"phoneNumber": "000-000-0000",
"address": {
"line1": "10380 Bren Road West",
"line2": "Ichikawa-shi",
"city": "Minnetonka",
"state": "MN",
"country": "US",
"postalCode": "55346"
}
},
"amount": "371.04",
"currency": "USD",
"state": "chargeable",
"creationIp": "209.87.180.27",
"createdTime": "2022-07-08T10:09:30.503Z",
"updatedTime": "2022-07-08T10:09:30.503Z",
"flow": "standard",
"language": "en",
"creditCard": {
"brand": "Visa",
"expirationMonth": 12,
"expirationYear": 2023,
"lastFourDigits": "1111"
}
},
"readyForStorage": false,
"supportsStorage": true,
"consents": {
"eula": false,
"termsOfUse": false,
"termsOfSale": true
}
}
For details on how to handle this event, refer to:

onError

If an error occurs, you receive the onError event. The event's data object identifies the paymentMethod associated with the error. Handle this error by instructing customers to provide a new method of payment.
{
"paymentMethod":"googlePay"
}

onCancel

When customers cancel the payment process (e.g., during the redirect phase) before authorizing payment, you receive the onCancel event. The event's data object identifies which paymentMethod was cancelled.
{
"paymentMethod": "googlePay"
}

onReady

When Drop-in payments is ready to accept input, you receive the onReady event. The event's data object contains an array that lists all the paymentMethodTypes presented to the customer.
{
"paymentMethodTypes": [
"applePay",
"creditCard",
"directDebit",
"googlePay",
"wireTransfer"
]
}

Billing address

You can use billingAddress to pass a customer's billing information. For details on when you should use this object, refer to Payment session identifier in the Configuring Drop-in payments section.
...
let configuration = {
...
"billingAddress": {
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"organization": "Digital River",
"phoneNumber": "952-253-1234",
"address": {
"line1": "10380 Bren Road W",
"city": "Minnetonka",
"state": "MN",
"postalCode": "55343",
"country": "US"
}
}
}
...
Field
Required or Optional
Description
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 address.
billingAddress.address.line2
Optional
The second line of the address
billingAddress.address.city
Optional