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.
Follow these steps to set up Drop-in payments:
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>
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"/>
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"
});
Create a container element on the page where you want Drop-in payments to appear.
<div id="drop-in"></div>
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) {}
}
let dropin = digitalriver.createDropin(configuration);
Add the following statement to the appropriate checkout or account management page:
dropin.mount("drop-in");
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. 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
. 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
. 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.
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. {
"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
}
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. Outside of checkout flows, you can use Drop-in payments to collect a customer's payment information and then determine whether the resulting source should be saved to the customer's record. To do this, you'll need to:
In the configuration object, set
flow
to managePaymentMethods
. This informs Digital River that you're collecting payment information in an account management setting.Because this is a
managePaymentMethods
flow, and there's no payment session to reference, you shouldn't provide a sessionId
. As a result, you'll need to pass the billing information you collect from customers in billingAddress
.In
managePaymentMethods
flows, Drop-in payments automatically (a) requires customers to agree to save their payment information for use in future transactions and (b) doesn't display compliance information. As a result, you don't need to pass showSavePaymentAgreement
or showComplianceSection
.If you set
showSavePaymentAgreement
to false
or showComplianceSection
to true
, then Digital River overrides the values you pass.Additionally, if customers are replacing an active subscription's recurring billing instrument, make sure you set
usage
to subscription
and showTermsofSaleDisclosure
to true
. This prompts Drop-in payments to display a recurring billing agreement and forces customers to accept it. Once you invoke the create and mount functions, Drop-in payments opens on the account management page you designated. For details, refer to the Getting started section.
Customers then select the payment method they want to add to their account, provide their personal information and agree to the storage terms. They may also be required to complete SCA, a process handled by Drop-in payments.
If Digital River successfully creates a source, the
data
object of onSuccess
contains a source that is readyForStorage
. Handle this event by sending source.id
to your back-end and using your secret API key to associate the source with the customer. ...
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"
}
}
}
...
...
let configuration = {
"sessionId": "d5437992-c2d3-4cc9-9be5-c49a9ed68bbb",
...
}
...
If
options.flow
is checkout
, then you should retrieve the checkout's payment.session.id
and use it to set sessionId
. DigitalRiver.js then uses that identifier to look up the payment session and retrieve 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 returned 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
.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
}
}
},
...
}
...
Use
options.flow
to specify a mode of operation. 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. 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.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. 
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 the Google Pay and Pay Pal buttons. For information on styling these buttons, refer to Payment method configurations.
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 to display.
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.
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 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. 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"
}
}
},
...
}
...

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:
|
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"
}
}
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.

...
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");
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.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.mask
: Indicates whether data entered in card number and card security code fields is automatically masked after successful validation.
The
onlineBanking
object allows you to configure how the online banking payment method is displayed. placeholderText
: The placeholder that appears in the online banking selector.
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.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) {}
...
}
...
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
also contains readyForStorage
and supportsStorage
booleans. 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 future transactions. To accomplish that, you must associate the source with the customer. This request 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",