# Drop-in payments integration guide This page explains how to [get started](#getting-started) integrating [Drop-in payments](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in) into both [checkout flows](#using-drop-in-payments-within-a-checkout-flow) and [account management flows](#using-drop-in-to-collect-payment-details-on-a-my-account-page). {% hint style="success" %} We recommend also using the [Drop-in payments builder](https://drapi.io/drop-in-builder/) and the [Building payment workflows page](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/building-you-workflows) to learn how to integrate [our supported payment methods](https://docs.digitalriver.com/digital-river-api/payments/supported-payment-methods) into your app or website. {% endhint %} ## Getting started Follow these steps to set up Drop-in payments:‌ * [Step 1: Include DigitalRiver.js](#step-1-include-digitalriver-js-on-your-page) * [Step 2: Include the base CSS file](#step-2-include-the-hydrate-css-file) * [Step 3: Initialize DigitalRiver.js with your public key](#step-3-initialize-digitalriver-js-with-your-public-key) * [Step 4: Create a Drop-in payments container](#step-4-create-a-drop-in-payments-container) * [Step 5: Create a Drop-in payments configuration object](#step-5-configure-hydrate) * [Step 6: Use the configuration object to create an instance of Drop-in](#step-6-allow-the-shopper-to-interact-with-hydrate) * [Step 7: Mount Drop-in payments on a checkout or account management page](#step-7-mount-drop-in-payments-on-a-checkout-or-account-management-page) * [Step 8: Enable the payment method in Digital River Dashboard](#step-8-enable-the-payment-method-from-the-dashboard) ### Step 1: Include DigitalRiver.js Include the following script on the pages where you want Drop-in payments to display (for example, on [checkout](#using-drop-in-payments-within-a-checkout-flow) or [account management](#using-drop-in-to-collect-payment-details-on-a-my-account-page) pages): ```javascript ``` ### Step 2: Include the base CSS file 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. ```javascript ``` ### Step 3: Initialize DigitalRiver.js with your public key [Initialize the DigitalRiver.js library](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digital-river-publishable-api-key) with your [public API key](https://app.gitbook.com/s/ZrhMyLX5esFYS64lNWVW/digital-river-api-reference-guide/api-structure#public-keys). If you provide `locale`, then Drop-in payments are localized based on that value. ```javascript 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. ```javascript
``` ### Step 5: Create a Drop-in payments configuration object Create a configuration object. For details, refer to [Configuring Drop-in payments](#configuring-drop-in-payments). ```javascript 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](#configuring-drop-in-payments) to [`createDropin()`](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/digitalriver-object#creating-an-instance-of-drop-in). ```javascript 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: ```javascript dropin.mount("drop-in"); ``` Once invoked, `mount()` displays Drop-in payments in the [designated container](#step-4-create-a-drop-in-payments-container). ### Step 8: Enable the payment method in Digital River Dashboard Sign in to [Digital River Dashboard ](https://dashboard.digitalriver.com/login)and [enable payment methods](https://docs.digitalriver.com/digital-river-api/administration/dashboard/settings/payment-methods/disabling-a-payment-method). ## Using Drop-in payments in checkouts To use Drop-in payments in checkout flows, you'll need to (1) [finalize your checkout](#finalize-your-order-totals), (2) [configure and mount Drop-in payments](#initialize-and-place-drop-in-within-your-application), and (3) [handle the `onSuccess` event](#the-onsuccess-event-returns-the-source). {% hint style="info" %} You can also [allow customers to save their payment information in checkout flows](#optional.-allowing-the-customer-to-save-their-payment-details). {% endhint %} ### Finalize the checkout Before interacting with Drop-in payments, your integration should obtain the customer's billing information and use it to set the [checkout's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)`billTo`. For more details, refer to [Billing address requirements](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/providing-address-information#billing-address-requirements) on the [Providing address information](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/providing-address-information) page. The checkout's `totalAmount` should also be finalized. So, when applicable, make sure you've set the checkout's [`shipFrom`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/providing-address-information#ship-from-requirements), [`shipTo`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/providing-address-information#ship-to-requirements), `shippingDiscount`, [`shippingChoice`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/shipping-choice), [`taxIdentifiers[]`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/tax-identifiers) and any other data that may affect `totalAmount`. ### Configure and mount Drop-in payments Retrieve the checkout's [`payment.session.id`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts#payment-session-identifier) and use it to set [`sessionId`](#drop-in-options) in the [Drop-in payments' configuration object](#configuring-drop-in-payments). In that same object, you should also set: * [`flow`](#flow) to `checkout` * [`showComplianceSection`](#show-compliance-section) to `true` * [`showTermsOfSaleDisclosure`](#show-terms-of-sale-disclosure) to `true` ```javascript ... 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](#step-6-allow-the-shopper-to-interact-with-hydrate) and [mount](#step-7-mount-drop-in-payments-on-a-checkout-or-account-management-page) methods are invoked, Drop-in payments open on the experience page containing the container element. For more details on this process, refer to the [Getting started](#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 handle all these redirects. ### Handle the `onSuccess` event If customers supply the required information, click the [configurable button](#customizing-the-text-of-the-drop-in-button), and payment is successfully authorized, you should handle [`onSuccess`](#onsuccess) by passing `source.id` to your backend and use your [secret API key](https://app.gitbook.com/s/ZrhMyLX5esFYS64lNWVW/digital-river-api-reference-guide/api-structure#confidential-keys) to [associate the source with the checkout](https://docs.digitalriver.com/digital-river-api/payment-sources/using-the-source-identifier#attaching-sources-to-checkouts). In the following example, the `data` object of `onSuccess` contains a [`source`](https://docs.digitalriver.com/digital-river-api/payments/payment-sources) whose [`state`](https://docs.digitalriver.com/digital-river-api/payment-sources#source-state) is `chargeable`. Since `readyForStorage` is `false`, this source can only be used once (i.e., it can't generate multiple [charges](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/charges)). ```javascript { "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": "test224234234324@test.com", "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](#using-drop-in-payments-within-a-checkout-flow), you can also allow customers to save their payment details for use in future transactions by enabling [`showSavePaymentAgreement`](#show-save-payment-agreement). This feature ensures that a customer's payment details are collected in a [PSD2 and SCA-compliant](https://docs.digitalriver.com/digital-river-api/payments/psd2-and-sca) manner. ```javascript ... 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](https://docs.digitalriver.com/digital-river-api/payments/supported-payment-methods) 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](#customizing-the-text-of-the-drop-in-button), Drop-in payments perform any required authentications and, assuming that process is successful, the `data` object of [`onSuccess`](#onsuccess) contains a [source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources) that is `readyForStorage`. In this case, handle `onSuccess` by passing `source.id` to your backend and use your [secret API key](https://app.gitbook.com/s/ZrhMyLX5esFYS64lNWVW/digital-river-api-reference-guide/api-structure#confidential-keys) to [associate the source with the customer](https://docs.digitalriver.com/digital-river-api/payment-sources/using-the-source-identifier#attaching-sources-to-customers) before you [associate the source with the checkout](https://docs.digitalriver.com/digital-river-api/payment-sources/using-the-source-identifier#attaching-sources-to-checkouts). ## Using Drop-in payments in account management settings Outside of [checkout flows](#using-drop-in-payments-within-a-checkout-flow), you can use [Drop-in payments](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in) to collect a customer's payment information and then determine whether the resulting [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)should be saved to the [customer's record](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers). To do this, you'll need to: * [Build the configuration object](#build-the-configuration-object) * [Create and mount Drop-in payments](#initialize-and-place-drop-in-within-your-application-1) * [Handle `onSuccess`](#handle-onsuccess) ### Build the configuration object In the [configuration object](#configuring-drop-in-payments), set [`flow`](#flow) to `managePaymentMethods`. This informs Digital River that you're collecting payment information in an account management setting. In this type of `flow`: * Drop-in payments currently support [credit cards](#credit-card) and the [PayPal Billing Agreement](https://docs.digitalriver.com/digital-river-api/payments/supported-payment-methods/paypal-billing-agreement). To ensure that customers are only presented with these options, add `creditCard` and/or `payPalBilling` to your [`enabledPaymentMethods`](#filtering-payment-methods-shown-in-drop-in) list in [`paymentMethodConfiguration`](#configuring-payment-methods-within-drop-in). * There's no [payment session](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/payment-sessions) to reference, so you shouldn't define [`sessionId`](#drop-in-options). Instead, you need to pass the billing information you collect from customers in [`billingAddress`](#billing-address). * If customers are replacing an active subscription's recurring payment method, make sure you set [`usage`](#specifying-a-sources-future-use) to `subscription` and [`showTermsofSaleDisclosure`](#show-terms-of-sale-disclosure) 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 [`showSavePaymentAgreement`](#show-save-payment-agreement) or [`showComplianceSection`](#show-compliance-section). {% hint style="info" %} If you set `showSavePaymentAgreement` to `false` or `showComplianceSection` to `true`, then Digital River overrides the values you pass. {% endhint %} {% tabs %} {% tab title="Account management flow" %} ```javascript ... let configuration = { "options": { "flow": "managePaymentMethods", "usage": "subscription", "showTermsofSaleDisclosure": true }, "billingAddress": { "firstName": "John", "lastName": "Doe", "email": "test224234234324@test.com", "organization": "Digital River", "phoneNumber": "952-253-1234", "address": { "line1": "10380 Bren Road W", "city": "Minnetonka", "state": "MN", "postalCode": "55343", "country": "US" } }, onSuccess: function(data) {}, onError: function(data) {}, onReady: function(data) {}, onCancel: function(data) {}, }; ... ``` {% endtab %} {% endtabs %} ### Create and mount Drop-in payments Once you invoke the [create](#step-6-allow-the-shopper-to-interact-with-hydrate) and [mount](#step-7-mount-drop-in-payments-on-a-checkout-or-account-management-page) functions, Drop-in payments open on your designated account management page. For details, refer to the [Getting started](#getting-started) 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 [SCA](https://docs.digitalriver.com/digital-river-api/payments/psd2-and-sca), a process handled by Drop-in payments. ### Handle `onSuccess` If Digital River successfully creates a [source](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources), the `data` object of [`onSuccess`](#onsuccess) contains a [source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources) that is `readyForStorage`. Handle this event by sending `source.id` to your backend and use your [secret API key ](https://app.gitbook.com/s/ZrhMyLX5esFYS64lNWVW/digital-river-api-reference-guide/api-structure#confidential-keys)to [associate the source with the customer](https://docs.digitalriver.com/digital-river-api/payment-sources/using-the-source-identifier#attaching-sources-to-customers). ## Configuring Drop-in payments The [`createDropIn()`](#step-6-allow-the-shopper-to-interact-with-hydrate) method requires a configuration object. You can use this object to: * [Pass a payment session identifier](#drop-in-options) * [Define key options](#drop-in-options-1) * [Customize payment methods](#configuring-payment-methods-within-drop-in) * [Configure how you handle events](#drop-in-events) * [Send the customer's billing address](#billing-address) ```javascript ... 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": "test224234234324@test.com", "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` references a [payment session](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/payment-sessions). ```javascript ... let configuration = { "sessionId": "d5437992-c2d3-4cc9-9be5-c49a9ed68bbb", ... } ... ``` If [`options.flow`](#flow) is `checkout`, then you should retrieve the [checkout's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)[`payment.session.id`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts#payment-session-identifier) 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`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/providing-address-information#billing-address-requirements). {% hint style="info" %} In [checkout flows](#using-drop-in-payments-within-a-checkout-flow), Digital River recommends that, before calling [`createDropin()`](#step-6-allow-the-shopper-to-interact-with-hydrate), you pass the customer's billing information in the [checkout's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts) `billTo`. Doing so lets you use the returned tax data to present customers with finalized tax amounts before moving into the payment collection stage. {% endhint %} If you set [`options.flow`](#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`](#billing-address). ### Options The `options` object allows you to: * [Define a flow](#flow) * [Enable save payment agreements](#show-save-payment-agreement) * [Show compliance information](#show-compliance-section) * [Define a payment's intended use](#specifying-a-sources-future-use) * [Enable terms of sale agreements](#show-terms-of-sale-disclosure) * [Add disclosures](#add-disclosures) * [Disable automatic redirects](#dropinviadigitalriver.js-disablingredirectswithindropin) * [Customize button text](#customizing-the-text-of-the-drop-in-button) * [Expand first payment method](#expand-first-payment-method) ```javascript ... 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](#using-drop-in-payments-within-a-checkout-flow), set `flow` to `checkout` (*default*). If you're [using Drop-in payments in an account management flow](#using-drop-in-to-collect-payment-details-on-a-my-account-page), 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. #### Show save payment agreement The `options.showSavePaymentAgreement` attribute determines whether customers are given the option to save a selected payment method to their account. {% hint style="info" %} You only need to set this flag when [`options.flow`](#flow) is `checkout`. If `options.flow` is `managePaymentMethods`, then the save payment agreement is automatically displayed. {% endhint %} If `showSavePaymentAgreement` is `true`, and the selected [payment method supports reusability](https://docs.digitalriver.com/digital-river-api/payments/supported-payment-methods), 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 [SCA](https://docs.digitalriver.com/digital-river-api/payments/psd2-and-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 display compliance information. If `true` (*default*), then Drop-in payments display to a [selling entity](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/selling-entities)-specific compliance section. The information in this section is localized based on how you [initialize DigitalRiver.js](#step-3-initialize-digitalriver-js-with-your-public-key). {% hint style="info" %} Making this compliance information available to customers is critical to accessing Digital River's merchant-of-record business model. {% endhint %} 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. {% hint style="info" %} These settings don't change the text of the Google Pay and PayPal buttons. For information on styling these buttons, refer to [Payment method configurations](#configuring-payment-methods-within-drop-in). {% endhint %} The button's text is localized based on the `locale` you pass when [initializing DigitalRiver.js](#step-3-initialize-digitalriver-js-with-your-public-key). | Value | Output (locale of en-US) | | :------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | `continue` (default) | ![](https://334437993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LqH4RJfLVLuHPXuJyTZ%2Fuploads%2FXy3emwEZ2dqworV9bYu1%2Fcontinue%20button.png?alt=media\&token=18482d0e-defe-413f-90cc-3009bad2b25e) | | `payNow` | ![](https://334437993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LqH4RJfLVLuHPXuJyTZ%2Fuploads%2FQXzwrb7VDRPojKq718vy%2Fpay%20now%20button.png?alt=media\&token=0c837e31-cecb-4ac9-82fa-278bf956ffb3) | | `buyNow` | ![](https://334437993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LqH4RJfLVLuHPXuJyTZ%2Fuploads%2FLAUhgIETvTfL3F4d2XeV%2Fbuy%20now%20button.png?alt=media\&token=c6ff9ab4-9231-483a-98ba-2932fa0d09a8) | | `completeOrder` | ![](https://334437993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LqH4RJfLVLuHPXuJyTZ%2Fuploads%2Fd5QcGuJOYQ0s02IfAf0l%2Fcomplete%20order%20button.png?alt=media\&token=1afadf9b-1bcc-4ab5-8290-f1ee714fec47) | | `submitOrder` | ![](https://334437993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LqH4RJfLVLuHPXuJyTZ%2Fuploads%2FsC7E5ZKSIzNi036FZf4p%2Fsubmit%20order%20button.png?alt=media\&token=8f635826-8289-4fe5-b833-79f11498aede) | You also can personalize the text by setting `button.type` to `custom` and `button.buttonText` to the characters you want to display.
#### Specifying a source's future use Set `options.usage` to indicate how the [payment source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources) 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 [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)is to be used for [recurring transactions](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscriptions), made at regular intervals, for a product or a service. * `convenience`: This value applies mainly to saved payment [sources ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)used for [one-off transactions](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/building-you-workflows#one-off). 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 [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)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 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. {% hint style="warning" %} The terms are localized based on how you [initialize DigitalRiver.js](#step-3-initialize-digitalriver-js-with-your-public-key). {% endhint %} The terms depend on whether customers make a one-time purchase or [buy a subscription product](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscriptions/digital-river-coordinated-subscriptions#acquiring-payment). {% tabs %} {% tab title="One-time purchase" %} ![](https://334437993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LqH4RJfLVLuHPXuJyTZ%2Fuploads%2FgKRP5Vv8EO3dJFmNAMAb%2Fone%20time%20purchase%20terms%20of%20sale.png?alt=media\&token=3ba7e34b-8733-44f4-9c84-b49d76c2555f) {% endtab %} {% tab title="Subscription acqusition" %} ![](https://334437993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LqH4RJfLVLuHPXuJyTZ%2Fuploads%2FKnF3OhwCSwjmKqlSmeYz%2Fsub%20terms%20of%20sale.png?alt=media\&token=ac833954-d493-48d5-aeff-dd57c07dc22b) {% endtab %} {% endtabs %} 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`](#show-terms-of-sale-disclosure) 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. ```javascript ... let configuration = { ... "options": { ... "showTermsOfSaleDisclosure": true, ... "consents": { "companyName": "Cool Company", "eula": { "url": "https: //myecommercesite.com/eula" }, "termsOfUse": { "url": "https: //myecommercesite.com/termsOfUse" } } }, ... } ... ``` Once you [create](#step-6-allow-the-shopper-to-interact-with-hydrate) and [mount](#step-7-mount-drop-in-payments-on-a-checkout-or-account-management-page) Drop-in payments, your `consents` are appended to Digital River's disclosures.
#### Disabling redirects In [`options`](#drop-in-options-1), `redirect` allows you to configure how [sources ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)with a [`flow`](https://docs.digitalriver.com/digital-river-api/payment-sources#authentication-flow) of `redirect` are handled. 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. ```javascript "options": { "redirect": { "disableAutomaticRedirects": true, "returnUrl": "https://mywebsite.com/paymentCallBack.html", "cancelUrl": "https://mywebsite.com/paymentCallBack.html" } } ``` With this configuration, if customers select a redirect payment method, then [`onSuccess`](#onsuccess) returns a [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)whose [`state`](https://docs.digitalriver.com/digital-river-api/payment-sources#source-state) is `pending_redirect`. At this point, you can [associate the source with the checkout](https://docs.digitalriver.com/digital-river-api/payment-sources/using-the-source-identifier#attaching-sources-to-checkouts) and allow customers to review the transaction's details. If they decide to purchase, [create the order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier) 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 [order's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)[`state`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/payment-sessions#session-state) and the [payment session's](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/payment-sessions) [`state`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/payment-sessions#session-state). Use these values to determine whether to (1) display the order confirmation page (i.e., the "thank you" page) or (2) recreate the [checkout ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)and redo the payment collection stage. For details, refer to [Handling redirect payment methods](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/building-you-workflows/handling-redirect-payment-methods). 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. ```javascript "options": { "redirect": { "disableAutomaticRedirects": false } } ``` With this configuration, once customers select a payment method, DigitalRiver.js creates a [source](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources), checks its [`flow`](https://docs.digitalriver.com/digital-river-api/payment-sources#authentication-flow), 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 [`onSuccess`](#onsuccess) returns a [source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources) whose [`state`](https://docs.digitalriver.com/digital-river-api/payment-sources#source-state) is `chargeable`. #### Expand the 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. {% tabs %} {% tab title="Expanded" %} If `expandFirstPaymentMethod` is `true`(*default*) then the first displayed payment method is expanded. ![](https://334437993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LqH4RJfLVLuHPXuJyTZ%2Fuploads%2FFV0YPMsN7MzUwAbM4B5U%2Fexpanded.png?alt=media\&token=3ce53fc1-9bbe-4d2f-9791-687da7224b11) {% endtab %} {% tab title="Collapsed" %} If `expandFirstPaymentMethod` is `false`, then the first displayed payment method is collapsed. ![](https://334437993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LqH4RJfLVLuHPXuJyTZ%2Fuploads%2FyqikbwNg1VEQp69Wpje6%2Fimage.png?alt=media\&token=55d24a2c-a8d5-45e8-a900-2e6225b84302) {% endtab %} {% endtabs %} ### Payment method configurations The [configuration object's](#configuring-drop-in-payments) `paymentMethodConfiguration` allows you to customize payment methods. ```javascript ... 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" }, }, enabledPaymentMethods: ['creditCard'], disabledPaymentMethods: ['klarna'] }, ... }; digitalriver.createDropin(configuration).mount("dropin"); ``` #### Style Drop-in payments use [elements](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/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](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements#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](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements#styling-an-element-container). * `mask`: Indicates whether data entered in the card number and 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. * `style:` For details, refer to [Styling an element container](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements#styling-an-element-container). * `placeholderText`: The placeholder that appears in the online banking selector. #### Google Pay For details on `googlePay.style`, refer to [Google Pay element styles and customization](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements/google-pay-elements#google-pay-element-styles-and-customization). #### Apple Pay For details on `applePay.style`, refer to [Apple Pay styles and customization](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements/apple-pay-elements#apple-pay-element-styles-and-customization). #### PayPal For details on `payPal.style`, refer to [PayPal element style options](https://docs.digitalriver.com/digital-river-api/developer-resources/reference/elements/paypal-elements#paypal-element-style-options). #### Enable and disable payment methods 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. ### Drop-in payment events The [Drop-in payments' configuration object](#configuring-drop-in-payments) supports the following events: * [**onSuccess**](#onsuccess)**:** Occurs when a [source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources) is successfully created * [**onError**](#onerror)**:** Occurs when there's a validation error * [**onCancel**](#oncancel)**:** Occurs when a payment method is cancelled * [**onReady**](#onready)**:** Occurs when Drop-in payments are ready to accept input These events provide real-time updates on the status of payment methods. ```javascript ... let configuration = { ... onSuccess: function(data) {}, onError: function(data) {}, onReady: function(data) {}, onCancel: function(data) {} ... } ... ``` #### `onSuccess` If Digital River creates a [source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources), you receive the `onSuccess` event. The event's `data` contains the [source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources). It also contains `readyForStorage` and `supportsStorage` booleans. If `readyForStorage` is `true` then (1) customers approved saving the source to their account and (2) Digital River has performed any required [SCA](https://docs.digitalriver.com/digital-river-api/payments/psd2-and-sca). {% hint style="info" %} A `readyForStorage` value of `true` doesn't indicate that customers can reuse that same [source ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/sources)in future transactions. To accomplish that, you must [associate the source with the customer](https://docs.digitalriver.com/digital-river-api/payment-sources/using-the-source-identifier#attaching-sources-to-customers). This request flips the source's [`reusable`](https://docs.digitalriver.com/digital-river-api/payment-sources#reusable-or-single-use) value to `true`. {% endhint %} The `supportsStorage` value indicates whether the [source supports reusability](https://docs.digitalriver.com/digital-river-api/payment-sources#reusable-or-single-use). If you set [`showTermsOfSaleDisclosure`](#show-terms-of-sale-disclosure) 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 [`consents`](#add-disclosures) in the [configuration object](#configuring-drop-in-payments) contains a `eula.url` and `termsOfUse.url`. When these variables are `true`, it signifies customers were presented with that specific disclosure and actively accepted it. ```javascript { "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": "test@digitalriver.com", "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: * [Handle `onSuccess`](#the-onsuccess-event-returns-the-source) in the [Using Drop-in payments in checkouts](#using-drop-in-payments-within-a-checkout-flow) section * [Handle `onSuccess`](#undefined) in the [Using Drop-in payments in an account management portal](#using-drop-in-to-collect-payment-details-on-a-my-account-page) section #### `onError` If 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`. ```json { "type": "validation_error", "errors": [ { "code": "invalid_card_number", "message": "Please enter a valid card number" }, { "code": "invalid_expiration_date", "message": "Please enter a valid expiration year" }, { "code": "incomplete_security_code", "message": "Please enter a valid card security code" } ] } ``` #### `onCancel` You 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`. ```javascript { "paymentMethod": "googlePay" } ``` #### `onReady` You 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. ```javascript { "paymentMethodTypes": [ "applePay", "creditCard", "directDebit", "googlePay", "wireTransfer" ] } ``` ### Billing address You can use `billingAddress` to pass a customer's billing information. For details on when to use this object, refer to the [Payment session identifier](#drop-in-options) in the [Configuring Drop-in payments](#configuring-drop-in-payments) section. ```javascript ... let configuration = { ... "billingAddress": { "firstName": "John", "lastName": "Doe", "email": "test224234234324@test.com", "organization": "Digital River", "phoneNumber": "952-253-1234", "address": { "line1": "10380 Bren Road W", "city": "Minnetonka", "state": "MN", "postalCode": "55343", "country": "US" } } } ... ```
FieldRequired or OptionalDescription
billingAddressRequiredThe customer's billing address.
billingAddress.firstNameRequiredThe customer's first name.
billingAddress.lastNameRequiredThe customer's last name.
billingAddress.emailRequiredThe customer's email address.
billingAddress.organizationOptionalThe business customer's organization.
billingAddress.phoneNumberRequiredThe customer's phone number.
billingAddress.address.line1RequiredThe first line of the address.
billingAddress.address.line2OptionalThe second line of the address
billingAddress.address.cityOptionalCity or town.
billingAddress.address.stateOptionalThe state, county, province, or region.
billingAddress.address.postalCodeRequiredZIP or postal code.
billingAddress.address.countryRequiredA two-letter Alpha-2 country code as described in the ISO 3166 international standard.
billingAddress.address.additional AddressInfoOptionalAdditional address information that may be useful or required for some addresses.
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/drop-in/drop-in-integration-guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.