Authorize a payment

Learn to authorize a payment.

The Digital River Drop-in Checkout feature is used to authorize a payment handled. Use the following steps to set up a cart and then hand it over to Digital River for payment authorization:

Prepare your cart

1. Make sure your cart locale and country are set. The connector passes the {cart.locale}_{cart.country}value to Digital River to be used for the locale when creating a Drop-in Checkout session.

2. Set thecustomerEmailfield on the cart to the customer's email address.

3. Set the value of custom.fields.drWarehouse to a reference pointing to the warehouse that this order will ship from. This step is optional if your cart contains only digital products. The typeId for this reference is key-value-document and the id is the id of the warehouse that has been set when saving it. If you have only one warehouse location, this can be hardcoded. Otherwise, you are responsible for determining the value to use.

4. Optionally, set the custom field drBusinessCustomer. When this is set to true,the Digital River customerType field is set to business when creating the checkout session. When it is false or not set the customerType field is set to individual.

5. You can optionally set the shipping addresses on the cart. The mapping of commercetools address fields to Digital River fields is as follows:

   commercetools field	Digital River field to map to	Notes
   firstName and lastName	name	Concatenated with space separator
   streetName	address.line1
   additionalStreetInfo	address.line2
   city	address.city
   postalCode	address.postal_code
   country	address.country
   region or state	address.state	Source depends on value of connector.mapping.address-state-from which defaults to REGION but can be set to STATE
   phone	phone
   email	email
   company	company

Create a commercetools payment

You must next create a commercetools payment and populate the following:

Property	Value	Required	Notes
customerId	Reference to commercetools customer	See notes	Required for non-guest checkout. If using MyPayments API this will automatically be set to the logged in customer. One of customerId or anonymousId must be populated
anonymousId	Id for tracking guest checkout	See notes	Required for guest checkout. If using MyPayments API this will automatically be set. One of customerId or anonymousId must be populated
paymentMethodInfo.paymentInterface	DigitalRiver	Yes	This triggers creation of the drop-in checkout session
custom.fields.drClientIpAddress	IP address of the client device. For browsers you may need to the public-ip npm package to determine this	Yes	Required for fraud checking.

The payment object that is returned contains the following additional fields:

Property	Value
custom.fields.drCheckoutSessionId	The Digital River checkout session id

Complete the payment authorization process

Finally, use the following steps to complete the payment authorization process:

1. Add the payment to the cart.

2. Create the Drop-in Checkout modal.

   1. To do this, You need your Digital River public API key. This is configured in the Digital River > API Keys section of the commercetools Merchant Center. It can be retrieved using the custom objects API with container digital_river and key public_api_key.

   2. Load the checkout library from https://checkout.digitalriverws.com/v1/DigitalRiverCheckout.js.

   3. Render the Drop-in Checkout modal. The following Javascript provides an example of how this is done:

const drCheckout = new window.DigitalRiverCheckout(apiKey);  

const config = {
    options: {},
    onReady: function () {
      // handle onReady callback if required
    },
    onAddressComplete: function (address) {
      // handle onAddressComplete callback if required
    },
    onDeliveryComplete: function (shippingMethod) {
      // handle onAddressComplete callback if required
    },
    onCheckoutComplete: function (order) {
      // if you don't want to display the Digital River confirmation call
      // drCheckout.closeModal(this);
      // and handle displaying your own confirmation
    },
    onClose: function () {
      // handle onClose callback if required
    },
    onError: function (error) {
      // handle onError callback if required
    }
  };

  drCheckout.createModal(pay.custom.fields.drCheckoutSessionId, config);

When the user successfully completes a payment, the connector receives an order.created webhook and calls commercetools to create an order for you from the cart.

In locations where your prices are tax exclusive, Digital River calculates the appropriate tax for you and updates the commercetools cart and order. The amount on the final order, therefore, may not match the amount on the cart before the checkout.

The creation of the order occurs asynchronously so if you need the order to display a confirmation page you need to poll for it using the cart ID until it is available.