Drop-in payments integration guide
Learn how to integrate Drop-in payments
Last updated
Learn how to integrate Drop-in payments
Last updated
This page explains how to integrating into both and .
We recommend also using the and the to learn how to integrate 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 or pages):
Include the following link to the Drop-in payments CSS file on the same pages. If you'd like to customize styles, override this CSS file with your own.
Create a container element on the page where you want Drop-in payments to appear.
Add the following statement to the appropriate checkout or account management page:
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 handle all these redirects.
onSuccess eventIn this type of flow:
onSuccessThe options object allows you to:
Use options.flow to specify a mode of operation.
The options.showSavePaymentAgreement attribute determines whether customers are given the option to save a selected payment method to their account.
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 display compliance information.
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.
continue (default)
payNow
buyNow
completeOrder
submitOrder
You also can personalize the text by setting button.type to custom and button.buttonText to the characters you want to display.
The options.showTermsOfSaleDisclosure attribute determines whether Drop-in payments display the terms of sale to customers.
If set to true (default), then the terms of sale disclosure are displayed, and customers must accept them.
If set to false, no terms of sale are displayed.
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.
It's nested disableAutomaticRedirects boolean determines who initiates the redirect to the payment provider.
If you want to handle this redirect, then set disableAutomaticRedirects to true.
If you do, then returnUrl and cancelUrl are required and should be assigned the same value.
If you want DigitalRiver.js to handle redirecting customers to the payment provider, then set disableAutomaticRedirects to false. If you do, returnUrl and cancelUrl are optional, and we ignore any values assigned to them.
When Drop-in payments loads options.expandFirstPaymentMethod determines whether the first payment method in the accordion control element is expanded or collapsed.
If expandFirstPaymentMethod is true(default) then the first displayed payment method is expanded.
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 the card number and 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, respectively.
If you don't define either of these lists, then, by default, Drop-in payments display all transaction-applicable payment methods to customers.
If you do define enabledPaymentMethods, then Drop-in payments only display those that are in this list. However, it's not displayed if your list contains a payment method that doesn't apply to the transaction.
These events provide real-time updates on the status of payment methods.
onSuccessIt also contains readyForStorage and supportsStorage booleans.
When these variables are true, it signifies customers were presented with that specific disclosure and actively accepted it.
For details on how to handle this event, refer to:
onErrorIf an error occurs, you receive the onError event. The event's data object contains a type and an array of errors[], each of which typically has a code and a message.
onCancelYou receive the onCancel event when customers cancel the payment process (e.g., during the redirect phase) before authorizing payment. The event's data object cancelled the paymentMethod.
onReadyYou will receive the onReady event when Drop-in payments are ready to accept input. The event's data object contains an array that lists all paymentMethodTypes presented to the customer.
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.
with your . If you provide locale, then Drop-in payments are localized based on that value.
Create a configuration object. For details, refer to .
Create an instance of Drop-in payments by passing the to .
Once invoked, mount() displays Drop-in payments in the .
Sign in to and .
To use Drop-in payments in checkout flows, you'll need to (1) , (2) , and (3) .
You can also .
Before interacting with Drop-in payments, your integration should obtain the customer's billing information and use it to set the billTo.
For more details, refer to on the page.
The checkout's totalAmount should also be finalized. So, when applicable, make sure you've set the checkout's , , shippingDiscount, , and any other data that may affect totalAmount.
Retrieve the checkout's and use it to set in the . In that same object, you should also set:
to checkout
to true
to true
Once the and methods are invoked, Drop-in payments open on the experience page containing the container element. For more details on this process, refer to the section.
If customers supply the required information, click the , and payment is successfully authorized, you should handle by passing source.id to your backend and use your to .
In the following example, the data object of onSuccess contains a whose is chargeable. Since readyForStorage is false, this source can only be used once (i.e., it can't generate multiple ).
During , you can also allow customers to save their payment details for use in future transactions by enabling .
This feature ensures that a customer's payment details are collected in a manner.
When you enable this feature, each displayed 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 , Drop-in payments perform any required authentications and, assuming that process is successful, the data object of contains a that is readyForStorage.
In this case, handle onSuccess by passing source.id to your backend and use your to before you .
Outside of , you can use to collect a customer's payment information and then determine whether the resulting should be saved to the . To do this, you'll need to:
In the , set to managePaymentMethods. This informs Digital River that you're collecting payment information in an account management setting.
Drop-in payments currently support and the . To ensure that customers are only presented with these options, add creditCard and/or payPalBilling to your list in .
There's no to reference, so you shouldn't define . Instead, you need to pass the billing information you collect from customers in .
If customers are replacing an active subscription's recurring payment method, make sure you set to subscription and to true. This prompts Drop-in payments to display a recurring billing agreement and forces customers to accept it.
Drop-in payments automatically (a) require customers to agree to save their payment information for use in future transactions, and (b) don't display compliance information. As a result, you don't need to pass or .
Once you invoke the and functions, Drop-in payments open on your designated account management page. For details, refer to the section.
Customers then select the payment method to add to their account, provide their personal information, and agree to the storage terms. They may also be required to complete , a process handled by Drop-in payments.
If Digital River successfully creates a , the data object of contains a that is readyForStorage. Handle this event by sending source.id to your backend and use your to .
The method requires a configuration object. You can use this object to:
The sessionId references a .
If is checkout, then you should retrieve the 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 .
In , Digital River recommends that, before calling , you pass the customer's billing information in the billTo. Doing so lets you use the returned tax data to present customers with finalized tax amounts before moving into the payment collection stage.
If you set 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 .
If you're , set flow to checkout (default).
If you're , then set flow to managePaymentMethods. This setting informs Digital River that you're collecting and saving a customer's payment information for future transactions and doing so outside of a checkout flow.
You only need to set this flag when is checkout. If options.flow is managePaymentMethods, then the save payment agreement is automatically displayed.
If showSavePaymentAgreement is true, and the selected , customers are presented with a box that they must check to save the payment method. Digital River displays appropriate localized disclosure statements with this setting and handles any needed .
If true (default), then Drop-in payments display to a -specific compliance section. The information in this section is localized based on how you .
These settings don't change the text of the Google Pay and PayPal buttons. For information on styling these buttons, refer to .
The button's text is localized based on the locale you pass when .
Set options.usage to indicate how the will likely 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 is to be used for , made at regular intervals, for a product or a service.
convenience: This value applies mainly to saved payment used for . These are scenarios where customers are typically present during checkout and want to access their payment information quickly. Always select this option if you don't offer subscriptions or don't have unscheduled merchant-initiated transactions.
unscheduled: The 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 terms are localized based on how you .
The terms depend on whether customers make a one-time purchase or .
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, must be true.
Once you and Drop-in payments, your consents are appended to Digital River's disclosures.
In , redirect allows you to configure how with a of redirect are handled.
With this configuration, if customers select a redirect payment method, then returns a whose is pending_redirect.
At this point, you can and allow customers to review the transaction's details. If they decide to purchase, and redirect them to the payment provider's portal.
While there, customers approve or cancel the transfer of funds. Once they complete either of these actions, they're sent to the location you specified in returnUrl and cancelUrl. When this resource loads, call a function that triggers a server-side refresh order request and then, in the response, check the and the . Use these values to determine whether to (1) display the order confirmation page (i.e., the "thank you" page) or (2) recreate the and redo the payment collection stage.
For details, refer to .
With this configuration, once customers select a payment method, DigitalRiver.js creates a , checks its , and then, if it's redirect, immediately sends customers to the payment provider's portal. If customers approve the transfer of funds and the provider authorizes payment, then returns a whose is chargeable.
The paymentMethodConfiguration allows you to customize payment methods.
Drop-in payments use 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 .
style: For details, refer to .
style: For details, refer to .
For details on googlePay.style, refer to .
For details on applePay.style, refer to .
For details on payPal.style, refer to .
The supports the following events:
: Occurs when a is successfully created
: Occurs when there's a validation error
: Occurs when a payment method is cancelled
: Occurs when Drop-in payments are ready to accept input
If Digital River creates a , you receive the onSuccess event.
The event's data contains the .
If readyForStorage is true then (1) customers approved saving the source to their account and (2) Digital River has performed any required .
A readyForStorage value of true doesn't indicate that customers can reuse that same in future transactions. To accomplish that, you must . This request flips the source's value to true.
The supportsStorage value indicates whether the .
If you set to true, then data also contains consents. Its termsOfSale boolean references Digital River's terms of sale and its eula and termsOfUse booleans indicate whether in the contains a eula.url and termsOfUse.url.
in the section
in the section
You can use billingAddress to pass a customer's billing information. For details on when to use this object, refer to the in the section.
A two-letter Alpha-2 country code as described in the international standard.
