Drop-in payments integration guide

Learn how to integrate Drop-in payments

This page explains how to get started integrating Drop-in payments into both checkout flows and account management flows.

We recommend also using the Drop-in payments builder and the Building payment workflows page to learn how to integrate our supported payment methods into your app or website.

Getting started

Follow these steps to set up Drop-in payments:‌

• Step 1: Include DigitalRiver.js

• Step 2: Include the base CSS file

• Step 3: Initialize DigitalRiver.js with your public key

• Step 4: Create a Drop-in payments container

• Step 5: Create a Drop-in payments configuration object

• Step 6: Use the configuration object to create an instance of Drop-in

• Step 7: Mount Drop-in payments on a checkout or account management page

• Step 8: Enable the payment method in Digital River 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 or account management pages):

<script type="text/javascript" src="https://js.digitalriverws.com/v1/DigitalRiver.js"></script>

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.

 <link rel="stylesheet" href="https://js.digitalriverws.com/v1/css/DigitalRiver.css" type="text/css"/>

Step 3: Initialize DigitalRiver.js with your public key

Initialize the DigitalRiver.js library with your public API key. If you provide locale, then Drop-in payments are localized based on that value.

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.

<div id="drop-in"></div>

Step 5: Create a Drop-in payments configuration object

Create a configuration object. For details, refer to Configuring Drop-in payments.

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 to createDropin().

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:

dropin.mount("drop-in");

Once invoked, mount() displays Drop-in payments in the designated container.

Step 8: Enable the payment method in Digital River Dashboard

Sign in to Digital River Dashboard and enable payment methods.

Using Drop-in payments in checkouts

To use Drop-in payments in checkout flows, you'll need to (1) finalize your checkout, (2) configure and mount Drop-in payments, and (3) handle the onSuccess event.

You can also allow customers to save their payment information in checkout flows.

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 billTo.

For more details, refer to Billing address requirements on the Providing address information page.

The checkout's totalAmount should also be finalized. So, when applicable, make sure you've set the checkout's shipFrom, shipTo, shippingDiscount, shippingChoice, taxIdentifiers[] and any other data that may affect totalAmount.

Configure and mount Drop-in payments

Retrieve the checkout's payment.session.id and use it to set sessionId in the Drop-in payments' configuration object. In that same object, you should also set:

• flow to checkout

• showComplianceSection to true

• showTermsOfSaleDisclosure to true

...                     
let configuration = {
    "sessionId": "7637affb-cb4a-4d9a-815c-d4e6e393e28f",
    "options": {
        "button": {
            "type": "submitOrder"
        },
        "flow": "checkout",
        "showComplianceSection": true,
        "showTermsOfSaleDisclosure": true
    }, 
    onSuccess: function(data) {}, 
    onError: function(data) {}, 
    onReady: function(data) {}, 
    onCancel: function(data) {}
}
                                    
let dropin = digitalriverpayments.createDropin(configuration);
dropin.mount("drop-in-container");

Once the create and mount methods are invoked, Drop-in payments open on the experience page containing the container element. For more details on this process, refer to the Getting started section.

Customers then select how they want to pay.

Depending on which payment method customers select, they may be redirected to a third-party payment authorization site. Drop-in payments handle all these redirects.

Handle the onSuccess event

If customers supply the required information, click the configurable button, and payment is successfully authorized, you should handle onSuccess by passing source.id to your backend and use your secret API key to associate the source with the checkout.

In the following example, the data object of onSuccess contains a source whose state is chargeable. Since readyForStorage is false, this source can only be used once (i.e., it can't generate multiple charges).

{
    "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": "[e-mail]",
            "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, you can also allow customers to save their payment details for use in future transactions by enabling showSavePaymentAgreement.

This feature ensures that a customer's payment details are collected in a PSD2 and SCA-compliant manner.

...                    
let configuration = {
    "sessionId": "d5437992-c2d3-4cc9-9be5-c49a9ed68bbb",
    "options": {
        "flow": "checkout",
        "showSavePaymentAgreement": true
    }
    onSuccess: function(data) {}, 
    onError: function(data) {}, 
    onReady: function(data) {}, 
    onCancel: function(data) {}
}
                                    
let dropin = digitalriverpayments.createDropin(configuration);
dropin.mount("drop-in-container");

When you enable this feature, each displayed reusable payment method is accompanied by a box that customers must check if they want that payment information saved to their account.

If customers check the box and click the configurable button, Drop-in payments perform any required authentications and, assuming that process is successful, the data object of onSuccess contains a source that is readyForStorage.

In this case, handle onSuccess by passing source.id to your backend and use your secret API key to associate the source with the customer before you associate the source with the checkout.

Using Drop-in payments in account management settings

Outside of checkout flows, you can use Drop-in payments to collect a customer's payment information and then determine whether the resulting source should be saved to the customer's record. To do this, you'll need to:

• Build the configuration object

• Create and mount Drop-in payments

• Handle onSuccess

Build the configuration object

In the configuration object, set 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 and the PayPal Billing Agreement. To ensure that customers are only presented with these options, add creditCard and/or payPalBilling to your enabledPaymentMethods list in paymentMethodConfiguration.

• There's no payment session to reference, so you shouldn't define sessionId. Instead, you need to pass the billing information you collect from customers in billingAddress.

• If customers are replacing an active subscription's recurring payment method, make sure you set usage to subscription and showTermsofSaleDisclosure to true. This prompts Drop-in payments to display a recurring billing agreement and forces customers to accept it.

• 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 or showComplianceSection.

If you set showSavePaymentAgreement to false or showComplianceSection to true, then Digital River overrides the values you pass.

Account management flow

...
let configuration = {
    "options": {
        "flow": "managePaymentMethods",
        "usage": "subscription",
        "showTermsofSaleDisclosure": true
    },
    "billingAddress": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "[e-mail]",
        "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) {},
};
...

Create and mount Drop-in payments

Once you invoke the create and mount functions, Drop-in payments open on your designated account management page. For details, refer to the 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, a process handled by Drop-in payments.

Handle onSuccess

If Digital River successfully creates a source, the data object of onSuccess contains a source that is readyForStorage. Handle this event by sending source.id to your backend and use your secret API key to associate the source with the customer.

Configuring Drop-in payments

The createDropIn() method requires a configuration object. You can use this object to:

• Pass a payment session identifier

• Define key options

• Customize payment methods

• Configure how you handle events

• Send the customer's billing address

...
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": "[e-mail]",
        "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.

...
let configuration = {
    "sessionId": "d5437992-c2d3-4cc9-9be5-c49a9ed68bbb",
    ...
}
...

If options.flow is checkout, then you should retrieve the checkout's payment.session.id and use it to set sessionId. DigitalRiver.js then uses that identifier to look up the payment session and retrieve the customer's billing address that you assigned to the checkout's billTo.

In checkout flows, Digital River recommends that, before calling createDropin(), you pass the customer's billing information in the checkout's 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 options.flow to managePaymentMethods, then you don't need to pass a sessionId. But, as a result, you're required to send a customer's billing information in billingAddress.

Options

The options object allows you to:

• Define a flow

• Enable save payment agreements

• Show compliance information

• Define a payment's intended use

• Enable terms of sale agreements

• Add disclosures

• Disable automatic redirects

• Customize button text

• Expand first payment method

...
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, set flow to checkout (default).

If you're using Drop-in payments in an account management flow, then set flow to managePaymentMethods. This setting informs Digital River that you're collecting and saving a customer's payment information for 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.

You only need to set this flag when options.flow is checkout. If options.flow is managePaymentMethods, then the save payment agreement is automatically displayed.

If showSavePaymentAgreement is true, and the selected payment method supports reusability, 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.

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-specific compliance section. The information in this section is localized based on how you initialize DigitalRiver.js.

Making this compliance information available to customers is critical to accessing Digital River's merchant-of-record business model.

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.

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.

The button's text is localized based on the locale you pass when initializing DigitalRiver.js.

Value	Output (locale of en-US)
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.

Specifying a source's future use

Set options.usage to indicate how the payment source 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 is to be used for recurring transactions, made at regular intervals, for a product or a service.
• convenience: This value applies mainly to saved payment sources used for one-off transactions. 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.

The terms are localized based on how you initialize DigitalRiver.js.

The terms depend on whether customers make a one-time purchase or buy a subscription product.

One-time purchase

Subscription acqusition

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 must be true.

If you pass consents, then companyName is required. You're not required to provide either eula or termsOfUse, but if you do, you must specify a url that links to the relevant document.

...
let configuration = {
    ...
    "options": {
        ...
        "showTermsOfSaleDisclosure": true,
        ...
        "consents": {
            "companyName": "Cool Company",
            "eula": {
                "url": "https: //myecommercesite.com/eula"
            },
            "termsOfUse": {
                "url": "https: //myecommercesite.com/termsOfUse"
            }
        }
    },
    ...
}
...

Once you create and mount Drop-in payments, your consents are appended to Digital River's disclosures.

Disabling redirects

In options, redirect allows you to configure how sources with a 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.

"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 returns a source whose state is pending_redirect.

At this point, you can associate the source with the checkout and allow customers to review the transaction's details. If they decide to purchase, create the order 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 state and the payment session's 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 and redo the payment collection stage.

For details, refer to 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.

"options": {
    "redirect": {
        "disableAutomaticRedirects": false  
    }
}

With this configuration, once customers select a payment method, DigitalRiver.js creates a source, checks its 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 returns a source whose 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.

Expanded

If expandFirstPaymentMethod is true(default) then the first displayed payment method is expanded.

Collapsed

If expandFirstPaymentMethod is false, then the first displayed payment method is collapsed.

Payment method configurations

The configuration object's paymentMethodConfiguration allows you to customize payment methods.

...
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 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.

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.

• 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.

• 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.

Apple Pay

For details on applePay.style, refer to Apple Pay styles and customization.

PayPal

For details on payPal.style, refer to 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 supports the following events:

• onSuccess: Occurs when a source is successfully created

• onError: Occurs when there's a validation error

• onCancel: Occurs when a payment method is cancelled

• onReady: Occurs when Drop-in payments are ready to accept input

These events provide real-time updates on the status of payment methods.

...
let configuration = {
    ... 
    onSuccess: function(data) {}, 
    onError: function(data) {}, 
    onReady: function(data) {}, 
    onCancel: function(data) {}    
    ...
}
...

onSuccess

If Digital River creates a source, you receive the onSuccess event.

The event's data contains the source.

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.

A readyForStorage value of true doesn't indicate that customers can reuse that same source in future transactions. To accomplish that, you must associate the source with the customer. This request flips the source's reusable value to true.

The supportsStorage value indicates whether the source supports reusability.

If you set showTermsOfSaleDisclosure 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 in the configuration object 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.

{
    "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": "[e-mail]",
            "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 in the Using Drop-in payments in checkouts section

• Handle onSuccess in the Using Drop-in payments in an account management portal 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.

{
    "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.

{
    "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.

{
     "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 in the Configuring Drop-in payments section.

...
let configuration = {
    ...
    "billingAddress": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "[e-mail]",
        "organization": "Digital River",
        "phoneNumber": "952-253-1234",
        "address": {
            "line1": "10380 Bren Road W",
            "city": "Minnetonka",
            "state": "MN",
            "postalCode": "55343",
            "country": "US"
        }
    }
}
...

Field	Required or Optional	Description
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 international standard.
billingAddress.address.additional AddressInfo	Optional	Additional address information that may be useful or required for some addresses.