# Drop-in payments integration guide This page explains how to [get started](#getting-started) integrating [Drop-in payments](/commerce-api/payments/payments-solutions/drop-in.md) into both [cart flows](#using-drop-in-payments-within-your-cart-flow) and [account management flows](#using-drop-in-payments-to-collect-payment-details-on-a-my-account-page). ## Getting started You can set up Drop-in payments in seven steps:‌ * [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](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#step-3-initialize-digitalriver-js-with-your-public-key) * [Step 4: Create 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 payments](#step-6-allow-the-shopper-to-interact-with-hydrate) * [Step 7: Mount Drop-in payments on a checkouts or account management page](#step-7-place-drop-in-payments-on-your-cart-or-shopper-page) ### Step 1: Include DigitalRiver.js Include the following script on the pages where you want Drop-in payments to appear (for example, the cart or My Account page): {% code overflow="wrap" %} ```javascript ``` {% endcode %} ### 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 the styles, override the CSS file with your own. {% code overflow="wrap" %} ```javascript ``` {% endcode %} ### Step 3: Initialize DigitalRiver.js with your public key [Initialize the DigitalRiver.js library](/commerce-api/resources/reference/digital-river-publishable-api-key.md) with your [public API key](https://docs.digitalriver.com/commerce-api-references/commerce-api-reference-guide/api-structure/api-keys#public-keys). If you provide a `locale`, Drop-in payments is localized based on that value. {% code overflow="wrap" %} ```javascript let digitalriver = new DigitalRiver("YOUR_PUBLIC_API_KEY", { "locale": "en-US" }); ``` {% endcode %} ### Step 4: Create a Drop-in payments container Create a container element on the page where you want the Drop-in payments to appear. {% code overflow="wrap" %} ```javascript
``` {% endcode %} ### 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: "YOUR_SESSION_IDENTIFIER", billingAddress: { firstName: "John", lastName: "Doe", email: "test@digitalriver.com", 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

|

The payment session identifier returned by Digital River.

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 | [Drop-in payments configuration options](#drop-in-payments-options). | | `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 | A two-letter Alpha-2 country code as described in the [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) international standard. | | `billingAddress.address.additional AddressInfo` | Optional | Additional address information that may be useful or required for some addresses. | | `paymentMethodConfiguration` | Optional | Additional configuration details. | | [`onSuccess`](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#onsuccess) | ​Content | The function called when the shopper has authorized payment and a payment source has been successfully created. Returns a `Source` object. | | [`onCancel`](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#oncancel) | ​Content | The function called when the shopper cancels the payment process before authorizing payment. | | [`onError`](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#onerror) | ​Content | The function called when an error has occurred. | | [`onReady`](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#onready) | ​Content | The function called when Drop-in payments is ready for user interaction. | ### 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](#step-5-configure-hydrate) to `createDropin()`. {% code overflow="wrap" %} ```javascript let dropin = digitalriver.createDropin(configuration); ``` {% endcode %} ### Step 7: Mount Drop-in payments on your cart or account management page Add the following statement to the appropriate cart 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). ## Using Drop-in payments in a cart ### Finalize your cart Create a cart and provide the necessary information for a final total for all amounts, including taxes, shipping, duties, and fees. ### Initialize and place Drop-in payments within your application Customers select how they want to pay from the experience page where you added the Drop-in payments container. Drop-in payments provide what is needed, including redirects to return a payment source that can be used in downstream API calls with the Commerce API. ![](/files/-M8uqxwlAKen8DMmZsYu) #### The customer provides payment details The customer may be redirected to authorize their payment. #### The onSuccess event returns the source The following source object contains the customer's payment details for a one-time charge. ```json { "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": "test@digitalriver.com", "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 } ``` ## Optional. Allowing the customer to save their payment details During the [cart flow](#using-drop-in-payments-within-your-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](/commerce-api/payments/psd2-and-sca.md) manner. ```json let configuration = { sessionId: "YOUR_SESSION_IDENTIFIER", options: { showSavePaymentAgreement: true }, billingAddress: { firstName: "John", lastName: "Doe", email: "test@digitalriver.com", 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](/commerce-api/payments/supported-payment-methods.md) is accompanied by a box that customers must check if they want that payment information saved to their account.
If the customers select the checkbox and click the [configurable button](#customizing-the-text-of-the-drop-in-payments-button), Drop-in payments performs the required authentication and, assuming that process is successful, the `data` object of [onSuccess ](#onsuccess)contains a source that is `readyForStorage`. In this case, handle `onSuccess` by passing the `source.id`. Use your secret API key to your back end to [associate the source with the customer](/commerce-api/payments/sources.md#attaching-a-payment-method-to-a-customer-or-payment-option) before you [associate the source with the cart](/commerce-api/payments/sources.md#attaching-a-payment-method-to-an-order-or-cart). ## Using Drop-in payments in an account management portal If your integration allows customers to save payment methods outside of a [cart flow](#using-drop-in-payments-in-a-cart), 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`. The `managePaymentMethods` informs Digital River that you're collecting and saving payment information in an account management setting. Because this is a `managePaymentMethods` flow, and there's no [payment session](/commerce-api/shopper-apis/cart/payment-sessions.md) to reference, you need to use the configuration object's `billingAddress` to pass the billing information you collect from customers. There's no need to enable `showComplianceSection`, [`showTermsOfSaleDisclosure`](#show-terms-of-sale-disclosure), and [`showSavePaymentAgreement`](#show-save-payment-agreement) since those features only need to be turned on in [cart flows](#using-drop-in-payments-in-a-cart). ```json let configuration = { options: { flow: "managePaymentMethods" } billingAddress: { firstName: "John", lastName: "Doe", email: "test@digitalriver.com", 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) { } } ``` ### Configure and mount Drop-in payments 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 container element's experience page. For more details on this process, refer to the [Getting started](#getting-started) section. Customers then select the payment method to add to their account and agree to specific storage terms. They may also be required to complete [SCA](/commerce-api/payments/psd2-and-sca.md), a process that Drop-in payments handles. ### Handle `onSuccess` If Digital River successfully creates a payment source, the `data` object of [`onSuccess`](#onsuccess) contains a [source](/commerce-api/payments/sources.md) that is `readyForStorage`. Handle the event by sending `source.id` to your back end and using your [secret API key](https://docs.digitalriver.com/commerce-api-references/commerce-api-reference-guide/api-structure/api-keys#confidential-keys) to [associate the source with the customer](/commerce-api/payments/sources.md#attaching-a-payment-method-to-a-customer-or-payment-option). #### The Customer provides payment details To collect 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. ![](/files/-MH7-vwVwn5HLEDOxTEn) #### The onSuccess event returns the source 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. {% hint style="warning" %} The `readyForStorage` identifier signifies the creation of the source with the intention of storage, and any necessary authentications have occurred. Attach the source to a Shopper by calling the appropriate API with your secret key to reuse the source. {% endhint %} ```json { "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": "test@digitalriver.com", "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 } ``` ## Drop-in options 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. | Use this option to [customize the text of the Drop-in button](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#customizing-the-text-of-the-drop-in-button). | | | `usage` |

subscription

convenience

unscheduled

| Use this option to [specify the future use of a source](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#properly-identifying-future-usage-of-created-sources). | | | `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](#dropinviadigitalriver.js-disablingredirectswithindropin). | | ### 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. | {% tabs %} {% tab title="Redirect code example" %} ```json "options": { "redirect": { "disableAutomaticRedirects": true, "returnUrl": "https://www.yourwebsite.com/return", "cancelUrl": "https://www.yourwebsite.com/cancel" } } ``` {% endtab %} {% endtabs %} ### Customizing the text of the Drop-in payments button 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](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#step-3-initialize-digitalriver-js-with-your-public-key). | 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"
}
}

| ### Specifying a source's future use Set `options.usage` to indicate how the [payment source](/commerce-api/payments/sources.md) 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`. When creating a source using Drop-in payments, you should identify the types of future transactions the source will use to increase the probability of approval... The `usage` value you select should be the one that most closely corresponds to your business model. The available options are [subscription](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#subscription), [convenience](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#convenience), and [unscheduled](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#unscheduled). * `subscription`: The source is to be used for [recurring transactions](/commerce-api/payments/sources.md#reusable-or-single-use), made at regular intervals, for a product or a service. * `convenience`: Applies mainly to saved payment sources that are used for [one-off transactions](/commerce-api/payments/building-your-workflows.md#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 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. {% tabs %} {% tab title="One-time purchase" %}
{% endtab %} {% tab title="Subscription acqusition" %}
{% 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 The `options.redirect` object specifies the options you want to use to turn off 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. 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. | ```javascript "options": { "redirect": { "disableAutomaticRedirects": true, "returnUrl": "https://www.yourwebsite.com/return", "cancelUrl": "https://www.yourwebsite.com/cancel" } } ``` #### Expand first payment method When Drop-in payments loads `options.expandFirstPaymentMethod` determines whether the first payment method in the accordion control element is expanded or collapsed. {% tabs %} {% tab title="Expanded" %} If `expandFirstPaymentMethod` is `true`(*default*) then the first displayed payment method is expanded.
{% endtab %} {% tab title="Collapsed" %} If `expandFirstPaymentMethod` is `false`, then the first displayed payment method is collapsed. ![](/files/PtKsAGIz2e8LCXKZql1C) {% endtab %} {% endtabs %} Set `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. ## Configuring payment methods within Drop-in payments Drop-in payments use DigitalRiver.js elements to capture secure payment details. Drop-in payments come with a predefined style that should meet most use cases. If you would like to customize the look and feel, you should familiarize yourself with the [Styling an element container](/commerce-api/resources/reference/elements.md#styling-an-element-container) in the [DigitalRiver.js](/commerce-api/payments/payments-solutions/digitalriver.js.md) documentation. Here is an example of customizing several payment methods: ```javascript 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: "test@digitalriver.com", 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'); ``` ### Drop-in payments specific configurations 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` | A Style object created following the [Styling an element container](/commerce-api/resources/reference/elements.md#styling-an-element-container) instructions. | | | `mask` | Indicates whether the card number and card security code fields will automatically mask the input details after successful validation. | | onlineBanking | `style` | A Style object created following the [Styling an element container](/commerce-api/resources/reference/elements.md#styling-an-element-container) instructions. | | | `placeholderText` | The placeholder text appears in the online banking selector. | | googlePay | `style` | A Style object created following the [Google Pay element styles and customization](/commerce-api/resources/reference/elements/google-pay-elements.md#google-pay-element-styles-and-customization) instructions. | | applePay | `style` | A Style object created following the [Apple Pay styles and customization](/commerce-api/resources/reference/elements/apple-pay-elements.md#apply-pay-element-styles-and-customization) instructions. | | payPal | `style` | A Style object created following the [PayPal element style option](/commerce-api/resources/reference/elements/paypal-elements.md#paypal-element-style-options) instructions. | ### Filtering payment methods shown in Drop-in payments In the Drop-in payments configuration, you can add a list of enabled payment methods, disabled payment methods, or both. If the list of enabled or disabled payment methods is absent, Drop-in payments display all the payment methods available for the payment session. The enabled list will not add unavailable payment methods for the payment session. ```json paymentMethodConfiguration: { enabledPaymentMethods: ['msts', 'creditCard'], disabledPaymentMethods: ['klarna'] }, ``` ## Drop-in payments events Learn how to receive real-time updates on the state of your payment methods in Drop-in Payment. Drop-in Payment supports the following events: * [**onSuccess**](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#onsuccess)–This occurs whenever a source is successfully created. * [**onError**](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#onerror)–This occurs whenever there is a validation error. * [**onCancel**](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#oncancel)–This occurs whenever a payment method is cancelled. * [**onReady**](/commerce-api/payments/payments-solutions/drop-in/drop-in-integration-guide.md#onready)–This occurs whenever Drop-in payments have successfully mounted. ### onSuccess You will receive an event when your customer provides the necessary details for payment and follows any necessary redirects. ```javascript { "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": "test224234234324@test.com", "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 } ``` ```json { "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": "test224234234324@test.com", "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.

| ### onError If an error occurs, you receive the `onError` event. The event's `data` object identifies the `paymentMethod` associated with the error. Handle this error by instructing customers to provide a new method of payment. ```json { "paymentMethod": "googlePay" } ``` ### onCancel You receive the `onCancel` event when customers cancel the payment process (for example, during the redirect phase) before authorizing payment. The event's `data` object identifies which `paymentMethod` was cancelled. ```json { "paymentMethod": "googlePay" } ``` ### onReady When ready, Drop-in payments will emit an event that contains a `"paymentMethodTypes"` array of available payment methods. ```json { "paymentMethodTypes": [ "applePay", "creditCard", "directDebit", "googlePay", "wireTransfer" ] } ``` --- # 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/commerce-api/payments/payments-solutions/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.