User guide

Learn how to use the Salesforce B2C LINK Cartridge.

Product management

Product management consists of two aspects. First, the required product attributes must be configured for each product/SKU. Next, the products must be synced to Digital River. This section details those steps.

Before Digital River can process the SKUs, you must complete all of the products with both the Tax Class and the Digital River custom attributes and send them to Digital River. This data is necessary for valid tax calculations. The absence of these attributes will result in errors when you run the SKU export job.

Digital River needs the optional Harmonized System (HS) Code property for duty calculation.

Note: If your Digital River account is configured for Landed Costs, you will need to configure the Harmonized System (HS) Code on applicable products. This cartridge code processes duty and appears to customers as a separate total price component without any additional site configuration. To avoid duty inclusion, leave HS Code attributes blank or contact your Digital River representative.

Note: If the tax code is a digital code, ensure that the Tax Codes for Digital Products (drDigitalProductTaxCodes) list is stored as the site preference to identify the digital products. After importing the metadata, the default tax codes are populated and can be used out of the box. No additional configuration is needed.

Verify the default list by selecting Sites, then select Your Site, select Site Preferences, then select Custom Preferences. Select Digital River in the Custom Site Preferences Groups and scroll down to the Tax Codes for Digital Products (drDigitalProductTaxCodes) preference.

After setting the Tax Class on the product, ensure that the SKU creation job is run. Ensure that the DR Digital Product field appears in the product’s attributes and is set to Yes for digital products.

Product sync jobs

After you configure the products, you need to sync the data to Digital River. The cartridge provides the following jobs to sync products. We recommend that you schedule these jobs to run regularly.

  • The DigitalRiver_DeltaSkuUpdate job will iterate through all products but send SKU data only for those products that haven’t been sent to Digital River or were modified afterward. We recommend you use this job for product data export.

  • The DigitalRiver_DeltaSkuUpdateOnButton is provided for exclusive occasions when there is a necessity to grant a merchant representative the possibility to request products export to Digital River without providing authority to manage jobs. Schedule this job to check periodically whether a merchant representative requested a SKU. If such was requested, an update will be made (same as the DigitalRiver_DeltaSkuUpdate job does). A merchant can force a product sync using the "Request Delta SKU Update" option in the Merchant Tools / Digital River. See Digital River Merchant Tools available in Business Manager for more details.

  • The DigitalRiver_FullSkuUpdate job will iterate through all products and send SKU data for all products regardless of whether or not they have been updated to Digital River. We recommend you use this job for product data export.

  • The DigitalRiver_FullSkuUpdateOnButton is provided for exclusive occasions when there is a necessity to grant a merchant representative the possibility to request an all products export regardless of whether or not they have been updated to Digital River without providing authority to manage jobs. Schedule this job to check periodically whether a merchant representative requested a SKU. If such was requested, an update will be made (same as the DigitalRiver_FullSkuUpdate job does). A merchant can force a product sync using the "Request All SKU Update" option in the Merchant Tools / Digital River. See Digital River Merchant Tools available in Business Manager for more details.

  • The LINK Cartridge adds the drExportedDate attribute to the product. The SKU update jobs update this attribute each time the jobs run.

Digital River merchant tools available in Business Manager

Merchant tools

We added new Business Manager menu options under Merchant Tools.

  • Request SKUs update—Click the Request SKUs update link under Digital River. You'll see the following options:

    • Request delta SKUs update—Click this button to launch the Digital River SKUs update with the next run of DigitalRiver_DeltaSkuUpdateOnButton job. The button will show the corresponding text indicating that you can launch the job or that the job is running.

    • Request all SKUs update—Click this button to launch the Digital River SKUs update with the next run of DigitalRiver_FullSkuUpdateOnButton job.

Note: Clicking Request delta SKUs update or Request all SKUs update will not launch the job immediately, but it will raise a flag that must perform an update with the next run ofDigitalRiver_DeltaSkuUpdateOnButton. If you haven't scheduled the job (in advance) in the Business Manager or (as an administrator) launched the job manually, clicking the button will have no impact at all.

  • Digital River Service Tester—Click the Digital River Service Tester link under Digital River and then click Test Services to test Digital River service availability. Test Services will make calls to the indicated web services and evaluate the response codes.

Checkout information

When a customer purchases a product, the Checkout page displays the shipping, payment, and order summary information.

Order summary

The Order Summary on the Checkout page displays the subtotal, shipping fee, sales tax, total fees (if applicable), and amount total for the order.

If landed cost is enabled, the Order Summary will also include the duty and Importer of Record (IOR) tax if applicable to the order.

Note: When a Tax Identifier is applied causing a Tax Discount, the “Price includes VAT” message in the Order Summary is removed and replaced with the message “X.XX VAT exempted from order.” The former "Total Tax" text in the summary has been replaced by "Price includes VAT" underneath the total price.

Regulatory fees

The creation and management of regulatory fees are outside the scope of the LINK Cartridge. Work with your Digital River Project Manager to set up regulatory fees. Once the fees are configured, the LINK Cartridge displays any applicable fees in the Order Summary when the shopper goes to the Checkout page.

The total fees are added to the purchase order as an adjustment.

Fees will be stored in the Product Line Item objects in the following fields: Fee (drFeeAmount), Fee Tax (drFeeTaxAmount), and Fee Details (drFeeDetails). The Fee Details field contains a JSON array that includes the details of all fees applied to the line item.

Payment

The customer can update or add a billing address, add their email address, and include a phone number. For US-based purchases, the customer can also state whether or not the purchase is tax-exempt.

Updating or adding a new billing address

To update the billing address, click Update Address and complete the fields. To add a new billing address, click Add New, complete the fields, and click Save.

Adding a tax identifier

For non-US countries, the customer can choose to add one or more Global Tax Identifiers in the Billing section.

The shopper can add and remove tax identifiers and remove from the Checkout page by completing the form and clicking Apply.

Adding new tax certificates (US TEMS)

The Digital River Salesforce B2C LINK Cartridge supports tax-exempt purchases on US storefronts. Authenticated US shoppers can add one or more tax certificates from their My Account page during checkout by selecting Yes for Tax Exempt Purchase. To add the tax certificate, click Add New Tax Certificate, complete the fields, upload the new tax certificate, and click Save. See the detailed steps below for more information.

Tax Exempt Purchase only appears if it is enabled in Site Preferences and if this is a US purchase. Specify the logic the cartridge uses to determine if the purchase is a US purchase and this section should be displayed.

The following list shows Digital River's Tax Certificate validation process once a shopper uploads a tax certificate.

  1. Validation of the tax certificate is a manual process done by Digital River employees. It is not a real-time determination.

  2. Pending that validation, the customer can place their order and that order will be treated as if there was a valid certificate (that is, tax-free).

  3. If the shopper’s certificate fails validation, when that shopper places another order, their order will not be tax-free.

To add view existing certificates and add a new tax certificate from the My Account page:

  1. Sign in to the storefront.

  2. Go to My Account and scroll down to Tax Certificates.

  3. Click View. The Tax Certificates page appears and displays all existing certificates.

  4. To add a new certificate, click Add New.

  5. Complete the fields and upload the certificate from the Add New Certificate page.

  6. Click Save. To view taxes at the line-item level of an order. See Searching for an order. The saved tax certificates will be available on the billing page in the Billing Address section:

Retrieving a stored payment method

A shopper can now retrieve their stored credit card when they go to checkout. Stored cards are authenticated using Strong Customer Authentication as required.

Thank you page

The Thank you page displays the receipt for the order and the order information. The system will then send a confirmation email to the customer's billing email. You can use the value for the Order Number to search for the order in Salesforce.

Order information

The Digital_River_Dropin payment processor provides the following order information in Business Manager:

  • To search for an order:

    1. Return to Salesforce.

    2. Click the Merchant Tools tab, and then click Orders under Ordering.

    3. Enter the order number in the Order Number field and click find.

    4. In the search results, click the link for the order you want to view under Number. The Details for Order page appears.

    5. To view taxes and fees at the line-item level, click the Shipment link, click the link for the product under Product ID, click the Attributes tab. Digital River attributes including taxes, duties, and fees are shown in the Digital River section.

  • Select Merchant Tools, select Orders, choose an order, and click Payments.

    • Payment type (creditCard, PayPal, and so on) is mentioned.

    • Hyperlink to order on Digital River Dashboard.

  • Select Merchant Tools, select Orders, choose an order, and click Notes. The following occurs

    • A Digital River create order response is being saved in order notes.

    • If the order is tax inclusive and promotions have been applied, you may see a note added to the order reflecting the original promotions applied. See this section for more details

Order state management

Digital River provides a range of order statuses to track order payment. Each order has a Digital River order status which reflects the current order position within the order cycle:

  • accepted—order has passed checks and is ready for fulfillment

  • in_review—order is on fraud review and can’t be fulfilled yet

  • pending_payment—order has delayed payment and can’t be fulfilled yet

  • blocked—order is blocked and must be cancelled

  • fulfilled—order is fulfilled and is waiting for payment capture

  • complete—order is fulfilled and has been paid

Digital River order status determines further order processing. Also, each order has a Digital River fraud status which shows the state of the order's fraud check:

  • passed—order has passed the fraud check

  • review_opened—order is on fraud review

  • blocked—order has not passed fraud check

Digital River fraud status doesn’t have a direct impact on order processing and is provided for user reference.

To see Digital River order and fraud states, select Merchant Tools, then select Ordering, and click Orders. Select the order number and choose the Attributes tab.

Initial Digital River status values are set after order placement and they define order processing scenarios.

Digital River order status

Order processing scenario

accepted

order will be processed

pending_payment

in_review

order will be put on hold until status changes to "accepted" or "blocked"

blocked

order will be cancelled

Order status management jobs

After the order is placed, the status update is handled through jobs that can be run or scheduled in the Business Manager. We recommend that you schedule these jobs on a regular basis.

  • The /DigitalRiver_fulfillOrders/ job processes all orders that were shipped or cancelled but still have Digital River order status of “accepted.” For each order, fulfillment is sent to Digital River. After all orders are processed their statuses are updated through a separate Digital River call. See the Order cancellation/fulfillment section for more details.

  • The DigitalRiver_updateCompletedOrders job queries all orders that were shipped or cancelled but still have a Digital River order status of “accepted” and updates their status through a Digital River call. Unlike “DigitalRiver_fulfillOrders” this job doesn’t send fulfillments to Digital River and is applicable only in combination with other integrations when drOrderHelper.notifyOrderFulfillment or drOrderHelper.notifyOrderCancellation functions are injected into scripts responsible for shipping management/order cancellation.

Important: Neither DigitalRiver_fulfillOrders nor DigitalRiver_updateCompletedOrders cancel orders or update shipping in the order management system, but only notify Digital River when the order or line item has been shipped or cancelled. Once notified, Digital River will capture the payment or cancel the charge. You can manage order shipping or cancellation in Business Manager or by other integrations, but it’s not within the scope of this cartridge functionality.

  • The DigitalRiver_updatePendingOrders job updates the state for all orders that have pending statuses (in_review, pending_payment, fulfilled) that wait for resolution on the DigitalRiver side.

In the following table, you can see all the statuses that you can expect to receive from Digital River and their impact on orders in SFCC for each respective state:

Storefront functionality

The DigitalRiver.js library replaces the Salesforce built-in payment method forms and also renders Digital River Drop-in payment integration to fulfill the payment process. The payment methods will display on the billing page. The payment methods that display depend on the configuration of your LINK cartridge key by Digital River. Visit our Drop-in documentation for an updated listing of payment methods available.

Payment methods

The customer can choose any available payment method. A registered customer can also save a credit card in their wallet. To do this, you need to set the Yes, please save this account and payment information for future purchases check box. The saved payment method will be visible on the My Account page.

Adding a new payment method

When the customer clicks the Add New link in the My Account section, the Drop-in form with the specific configuration will appear. The form allows the customer to add a new payment method within Drop-in and create a new source.

The saved cards will be available in the list of saved cards on the billing page. You can choose any card from the list to pay for purchases in the future.

Order cancellation/fulfillment

Though order and line-level fulfillment or cancellation within SFCC or an order management system are not within the scope of the current cartridge, it’s necessary to notify Digital River each time such an event occurs. Once notified, Digital River will capture the payment or cancel the charge. You can do this in two ways:

  1. If URL endpoints or third-party integration perform order fulfillment/cancellation, you can inject the drOrderHelper module in the code to send fulfillments to Digital River. To do so, import the module:

var drOrderHelper = require('*/cartridge/scripts/digitalRiver/drOrderHelper');

And use one of two functions that will create fulfillments at Digital River.

drOrderHelper

drOrderHelper.notifyOrderFulfillment(order, items);
drOrderHelper.notifyOrderCancellation(order, items);

Functions accept two arguments:

  • order—The updated order number or actual order object.​

  • items—Array of order product line items or order line items IDs that should be fulfilled. This parameter is provided for partial fulfillment/cancellation.

Note: At this time, partial line item fulfillments and cancellations are not supported.

Functions return the Result of the Digital River call.

Refunding an order

Refunds are handled through the Digital River dashboard. From Salesforce, you can get to the order record in the Digital River dashboard by navigating to the Order record and clicking the Payment tab. A link to the dashboard is provided in the Payment Method section.

Before you can refund an order, the order must be fulfilled and shipped.

  1. Sign in to Salesforce.

  2. Click Merchant Tools and then click Orders. The Orders page appears.

  3. Click Find.

  4. On the Orders page, click the order number link under the Number column. The Details for order page appears.

  5. Click the Attributes tab and scroll down to Digital River Attributes where the webhook displays the retrieved information. The Digital River Order Status should be fulfilled.

  6. Click the General tab, and then click the Shipping Status link. The Shipping Status should be Shipped. Note: If you changed the Digital River Order Status to Fulfilled or Shipping Status to Shipped, click Administration and then click Jobs. From the Jobs page, scroll click DigitalRiver_fulfillOrders, and then click Run Jobs. This will send the fulfillment request to Digital River.

  7. Click the Payment tab and click the Digital River logo under Payment Method to go to the Order details page for this order on the Digital River Dashboard. Note that you may need to enter your user credentials to access the Order details page.

  8. From the Order details page, scroll down to Refunds, click Create refund, complete the fields, and then click Review and submit.

  9. Click Submit to complete the task.

Tax inclusive sites, promotions, and tax identifiers

This section focuses on setting up a workaround for a promotions issue involving tax identifiers resulting in a tax exemption.

A tax identifier that is applied during a checkout can sometimes result in a tax exemption for the shopper. If this is the case, the gross price needs to be reduced by the value of the tax (known as a Tax Discount) in order to synchronize the position price on both platforms (that is, SFCC and Digital River).

On the Salesforce Commerce Cloud (SFCC) platform for the gross taxation sites (tax inclusive sites), the following approach is implemented to calculate this price. The formula is Net Price = Gross price - Tax. When the tax changes, the Net price is recalculated, but the Gross price remains constant.

Sometimes this situation can lead to incorrect promotional prices calculations. This topic describes the approach used in the cartridge to fix this issue so that it correctly exempts tax when applicable while not changing the value of applied promotions.

To synchronize prices on both platforms, the following general approach is used:

  • The total tax discount is handled by the cartridge code and stored as a non-basket item.

  • Whenever you need to display the total to a customer, the tax discount is subtracted from the order total.

  • On the last step of the checkout, just before order creation, the following occurs:

    • Absolute discount values are calculated on the last step of the checkout, just before the order is created from the basket

    • All price adjustments that were added by the SFCC Promotion Engine are removed and replaced with one custom priceAdjustment with type amountOff on both the Order and Line Item level.

    • The line item level price adjustment, with the tax discount amount, is added to each line item.

Make code changes to process the price/tax calculation

These modifications are added to the cartridge to address this issue. They have been added to the cartridge to further improve the OOTB (out-of-the-box) order creation and checkout experience.

The following specific code changes have been made to handle the price/tax calculation process:

  1. Replaced the product line item price adjustments and shipment line item price adjustments with one amountOff adjustment.

  2. Created an amountOff price adjustment and set the amount to the sum of all discounts that were applied to the item during checkout.

  3. Removed all system price adjustments generated by the Promotion engine during the checkout (Applied promotion information is stored in the order notes).

  4. Created a custom tax discount adjustment for each product line item and for shipping line items, with the amount of the line item tax discount.

  5. Added to the order notes descriptions of all removed discounts. The description includes the product ID, the name of the promotion, and the amount of the promotion discount.

  6. Kept the Tax Discount as a non-basket item during checkout. It is subtracted from the SFCC basket total to display the correct value to the customer and also send the correct value to the DropIn.

Understand Basket to Order transition UI changes

You will see the following visual differences between basket and order screens once promotions have been replaced and tax discounts added.

Order review page

At this stage, the Tax Discount has not been applied to the basket and the SFCC system Line Item level promotions are in place. In this UI example, the sum of Subtotal and Shipping is greater than the Total, this is explained by the text <amount> VAT exempted from order beneath the Total.

Thank you page

At this stage, the Line item tax discount has been applied to the product causing a decrease in price. Also, the line Shipping Discount appears. This is a SFRA standard to reflect any type of price adjustment applied to the Shipping Line item.

In this UI example, the sum of Subtotal, Shipping, and Shipping Discount is equal to the Total which is expected. To notify customers about the reason that the prices were changed, you add the text Prices reflect VAT exemption below the order Total.

Last updated