Drop-in Payments integration guide
Create a payment form using Drop-in Payments.
This page explains how to get started integrating Drop-in payments into both cart flows and account management flows.
You can set up Drop-in Payments in seven steps:‌
Include the following script on the pages where you want Drop-in payments to appear (for example, the cart or My Account page):
<script type="text/javascript" src="https://js.digitalriverws.com/v1/DigitalRiver.js"></script>
On the same pages, include the following link to the Drop-in Payments CSS file. If you'd like to customize the styles, simply override the CSS file with your own.
<link rel="stylesheet" href="https://js.digitalriverws.com/v1/css/DigitalRiver.css" type="text/css"/>
​Initialize the DigitalRiver.js library with your public API key. If you provide a
locale
, Drop-in Payments is localized based on that value.let digitalriver = new DigitalRiver("YOUR_PUBLIC_API_KEY", {
"locale": "en-US"
});
Create a container element on the page where you want the Drop-in Payments to appear.
<div id="drop-in"></div>
let configuration = {
sessionId: "YOUR_SESSION_IDENTIFIER",
billingAddress: {
firstName: "John",
lastName: "Doe",
email: "[email protected]",
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) { }
}
Field | Required | Description |
---|---|---|
sessionId | Required for the checkout flow​ Optional for the managePaymentMethods flow | Important: The sessionId is required if you are using Drop-in Payments within a cart flow. If you are using Drop-in Paymentsn to capture payment details on a customer portal, then the sessionId is not required. |
options | Optional | |
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 | 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 | |
billingAddress.address.additional AddressInfo | Optional | Additional address information that may be useful or required for some addresses. |
paymentMethodConfiguration | Optional | Additional configuration details. |
​Content | The function called when the shopper has authorized payment and a payment source has been successfully created. Returns a Source object. | |
​Content | The function called when the shopper cancels the payment process before authorizing payment. | |
​Content | The function called when an error has occurred. | |
​Content | The function called when Drop-in Payments is ready for user interaction. |
let dropin = digitalriver.createDropin(configuration);
Add the following statement to the appropriate cart or account management page:
dropin.mount("drop-in");
Create a cart and provide the necessary information to have a final total for all amounts including taxes, shipping, duties, and fees.
From the experience page where you added the Drop-in Payments container, customers select how they want to pay. Drop-in Payments 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 may be redirected to authorize their payment.
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
}
During the cart flow, 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: "YOUR_SESSION_IDENTIFIER",
options: {
showSavePaymentAgreement: true
},
billingAddress: {
firstName: "John",
lastName: "Doe",
email: "[email protected]",
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 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.
In this case, handle
onSuccess
by passing source.id
to your back-end and use your secret API key to first associate the source with the customer before you associate the source with the cart.If your integration allows customers to save payment methods outside of a cart 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. ??? Add links. ???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. ??? Add link. ???There's no need to enable
showComplianceSection
, showTermsOfSaleDisclosure
, and showSavePaymentAgreement
since those features only need to be turned on in cart flows.let configuration = {
options: {
flow: "managePaymentMethods"
}
billingAddress: {
firstName: "John",
lastName: "Doe",
email: "[email protected]",
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) { }
}
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.
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. 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.
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
}
When creating your Drop-in Payments 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 Payments mode of operation. Enable this flow if you are using Drop-in Payments 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 Payments 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 Payments. 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 Payments 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 Payments. This is an important piece for accessing the Digital River business model. ​ ![]() | True |
showComplianceSection | false | Disables the compliance section within Drop-in Payments. | ​ |
button | An object which specifies a type as well as a custom buttonText attribute. | ​ | |
usage | subscription convenience unscheduled | ​ | |
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 Payments. | Use this option if you would like to handle redirecting the customer yourself to the payment provider. See Disabling redirects within Drop-in Payments. | ​ |
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 Payments. In this scenario, you can allow your customer to choose their payment method, review and then authorize it 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 Payments. |
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
"options": {
"redirect": {
"disableAutomaticRedirects": true,
"returnUrl": "https://www.yourwebsite.com/return",
"cancelUrl": "https://www.yourwebsite.com/cancel"
}
}
The Drop-in Payments 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"
}
} ​ ![]() |
When creating a source using Drop-in Payments, 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 most closely corresponds to your business model. The available options are subscription, convenience, and unscheduled.Set
usage
to subscription
when you create sources that are used primarily for recurring transactions, made at regular intervals for a product or a service.The
convenience
setting applies mainly to saved payment sources that are used for one-off transactions. These are sources where customers are typically present during the checkout flow and want to quickly access their payment information. Select this option if you don't offer subscriptions or don't have unscheduled merchant=initiated transactionsSet
usage
to unscheduled
when you create sources for unscheduled merchant-initiated transactions. These are contracts that occur on a non-fixed schedule using 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.Drop-in Payments uses DigitalRiver.js elements to capture secure payment details. Drop-in Payments come 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",
email: "[email protected]",
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');
Use the following fields to configure payment methods.
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 | |
​ | mask | Indicates whether the card number and card security code fields will automatically mask the input details after successful validation. |
onlineBanking | style | |
​ | placeholderText | The placeholder text appears in the online banking selector. |
googlePay | style | |
applePay | style | |
payPal | style | |
msts | enrollment |
In the Drop-in Payments 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 Payments 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']
},
Learn how to receive real-time updates on the state of your payment methods in Drop-in Payments.
Drop-in Payments supports the following events:
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. |
If an error occurs, Drop-in Payments emits an event that identifies the payment method associated with the error. Instruct your customer to provide a new method of payment.
{
"paymentMethod":"googlePay"
}
When your customer chooses to pay with a specific payment method and decides to cancel during the redirect phase, Drop-in Payments emits an event that identifies the cancelled payment method.
{
"paymentMethod": "googlePay"
}
When ready, Drop-in Payments will emit an event that contains a
"paymentMethodTypes"
array of available payment methods.{
"paymentMethodTypes": [
"applePay",