Configure commercetools

Learn how to configure commercetools for use in the Digital River commercetools integration.

You need to complete some basic configuration tasks for commercetools to interact successfully with Digital River. Make sure that you have configured Digital River before you complete the configuration procedures in this topic.

To integrate with Digital River, the commercetools integration requires some configuration. This task requires making changes to some configuration settings and adding some customizations. These changes are made in the following areas:

• API Extension Setup

  • Payment Create

  • Payment Update

  • Customer Update

• Google Cloud Subscription Setup

• Resource Customizations

  • Payment

  • Product

  • Cart/Order

  • Line Item

  • Customer

  • Shipping Method

• Pricing

• Terraform scripts

Refer to the commercetools documentation on how to apply these specific changes and customizations or see the Terraform section below. The information that follows goes over each specific area and describes the changes that must be made.

API Extension setup

This section explains the settings needed for the API Extension area features to run successfully in the integration.

Payment Create

This feature creates a Digital River drop-in checkout session when a payment is initialized in commercetools. Use the following configuration settings:

Property	Value	Note
key	dr-payment-create
type	HTTP	Only HTTP destinations are supported
url	{baseUrl}/api/v1/payments/create	The baseUrl will be defined by where you deploy the plugin. You should front the plugin with HTTPS in production
actions	Create
resourceTypeId	payment
timeoutInMs	2000	May be increased if required, commercetools now supports up to 5000ms for payment extensions

Payment Update

This feature is used to update Digital River when a payment is updated in commercetools. Updates may consist of, for example, a refund of a payment when a Refund transaction is added to the commercetools payment. Use the following configuration settings:

Property	Value	Note
key	dr-payment-update
type	HTTP	Only HTTP destinations are supported
url	{baseUrl}/api/v1/payments/update	The baseUrl will be defined by where you deploy the reference application. You should front the plugin with HTTPS in production
actions	Update
resourceTypeId	payment
timeoutInMs	2000	May be increased if required, commercetools now supports up to 5000ms for payment extensions

Customer Update

This feature is used to update Digital River when a customer is updated in commercetools. Updates may consist of

• Setting email and default shipping address on the Digital River customer

• Attaching a tax certificate to the Digital River customer

• Attaching a payment source to the Digital River customer

Use the following configuration settings:

Property	Value	Note
key	dr-customer-update
type	HTTP	Only HTTP destinations are supported
url	{baseUrl}/api/v1/customers/update	The baseUrl will be defined by where you deploy the reference application. You should front the plugin with HTTPS in production
actions	Update
resourceTypeId	customer
timeoutInMs	2000

For production use, it is recommended to set the authentication.type and authentication.headerValue properties to send a basic auth header in the requests from commercetools. These headers must be present and validated before the request is passed to the integration.

Google Subscription setup (for gCloud deployments)

This section explains the settings needed for subscriptions in gCloud deployments to run successfully in the integration. A subscription is required to synchronize product updates from commercetools to Digital River.

Property	Value	Note
key	product_sync_subscription
type	GoogleCloudPubSub
projectId	Your Google Cloud project id.
topic	commercetools_product_publish	May be changed, but must match value used in deployment.
resourceTypeId	product
types	ProductPublished, ProductUnpublished

Resource customizations

This section explains customizations that need to be done to specific resource values in order for the integration to run successfully.

The integration software relies on a number of custom fields being available on various resources. Most of these are values that are set for you to read if needed. You may need, however, to change some of these to different values before you can begin a checkout (see below).

The names of the custom type and fields are configurable. The tables below list the default values for the various resources. If you are already using custom types for any of these resources, you need to add the fields to your type and set the type key in the integration configuration so that the integration can write to these fields.

Payment

This table lists the default type and field values for the Payment resource.

Type	Key	Purpose
product	Any value	Passing additional payment information to and from Digital River

Fields

Field	Type	Constraint	Required	Description	Source
drEccn	enum	SameForAll	true	Export control classification number. Value must be in Digital River appoved list	Merchant Center / PIM
drCountryOfOrigin	enum or lenum	SameForAll	true	Country of origin for product. Use an lenum if you need i18n support in the Merchant Center	Merchant Center / PIM
drTaxCode	enum	SameForAll	true	Tax code. See Digital River tax codes	Merchant Center / PIM
drPartNumber	text	Unique	false	Part number	Merchant Center / PIM
drSkuGroupId	text or enum	SameForAll	false	Sku group id. Only required if you are using sku groups. You may want to use an enum that specifies your valid sku group ids	Merchant Center / PIM

Product

This table lists the default type and field values for the Product resource.

Type	Key	Purpose
payment	drPaymentFields	Passing additional payment information to and from Digital River

Fields

Field	Type	Description	Source
drClientIpAddress	String	Set to the IP address of the browser making payment	Implementation
drCheckoutSessionId	String	Drop in checkout session id, used to render checkout	Connector

Cart/order

This table lists the default type and field values for the Cart/Order resource.

Type	Key	Purpose
cart	drCartFields	Passing additional cart and order information to and from Digital River

Fields

Field	Type	Description	Source
drOrderId	String	Id of the order created in Digital River, set once checkout is complete. Used by the integration to look up the commercetools order	Integration
drOrderState	String	State of the order in Digital River, set once checkout is complete and updated as webhooks are received	Integration
drFraudState	String	Fraud state of the order in Digital River, set once checkout is complete and updated as webhooks are received	Integration
drWarehouse	key-value-document reference	Id of the warehouse to be used as the shipFrom address in Digital River. Must be set on the cart before commencing checkout	Implementation
drInvoiceUrls	Strings	URL(s) for the Digital River invoice(s) for the order. Set after an order is marked as fulfilled	Integration
drCreditNotes	Strings	URL(s) for the Digital River credit notes(s) for the order. Set after a refund is processed	Integration
drBusinessCustomer	Boolean	Flag indicating if the customerType should be set to business when creating checkout session	Implementation

Line item

This table lists the default type and field values for the Line Item resource.

Type	Key	Purpose
line-item	drLineItemFields	Map commercetools line items to Digital River line items

Fields

Field	Type	Description	Source
drLineItemId	String	Id of the line item created in Digital River, set once checkout is complete. Used by the integration when processing fulfillments and cancels	Integration

Customer

Type	Key	Purpose
customer	drCustomerFields	Used to pass additional customer information to Digital River

Fields

Field	Type	Description	Source
drTaxCertificateAuthority	String	Name of the tax certificate authority. Used when adding a tax certificate.	Implementation
drTaxCertificateStartDate	Date	Start date of tax certificate validity. Used when adding a tax certificate.	Implementation
drTaxCertificateEndDate	Date	End date of tax certificate validity. Used when adding a tax certificate.	Implementation
drTaxCertificateFileName	String	File name certificate authority. Used when adding a tax certificate.	Implementation
drTaxCertificateFileContents	String	Contents of the tax certificate, Base64 encoded. Used when adding a tax certificate. Cleared once processed.	Both
drTaxCertificateFileId	String	File id of the tax certificate. Set once processing is complete.	Integration
drAttachSource	String	Id of a payment source to attach (save) to the customer.	Implementation
drDetachSource	String	Id of a payment source to detach from the customer.	Implementation
drSources	Set	Strings containing JSON representation of saved payment sources	Integration
drBusinessCustomer	Boolean	When true sets DR customerType to business, otherwise individual	Implementation

Shipping method

This table lists the default type and field values for the Shipping Method resource.

Type	Key	Purpose
shipping-method	drShippingMethodFields	Used to pass additional shipping method information to Digital River.

Fields

Field	Type	Description	Source
drServiceLevel	String	Value to be passed to Digital River along with other shipping method data.	Implementation

Pricing

Digital River handles the calculation of taxes so you do not need to configure multiple rates on your tax categories unless you have a requirement to display taxes before the checkout.

You can simply use a single rate per country with an amount of 0.0 and includedInPrice set to Trueor False, depending on how you want Digital River to perform the tax calculation for you.

Where you sell into multiple countries, you can set includedInPrice differently for each country. It is not possible, however, to check out multiple products that have differing values for includedInPrice.

Terraform scripts

Terraform scripts can be used to configure your commercetools project. To use the scripts, you need a commercetools API key with the following scopes:

Scope
manage_types
manage_products
manage_subscriptions
manage_project_settings
manage_extensions
manage_api_clients
manage_shipping_methods
manage_orders

Google Cloud scripts

The following Google Cloud Terraform scripts can be used to configure your commercetools project:

Resource	Terraform script
API Client	api_client.tf
API Extensions	api_extensions.tf
Subscription	subscription.tf
Payment	payment.tf
Product	product.tf
Cart/Order	cart_order.tf
Line Item	cart_order.tf
Customer	customer.tf
Shipping Method	shipping_method.tf

To use these scripts, you need to set the following Terraform variables:

Variable	Value	Notes
api_url	API URL for your commercetools project	e.g. https://api.europe-west1.gcp.commercetools.com
auth_url	Auth URL for your commercetools project	e.g. https://auth.europe-west1.gcp.commercetools.com
client_id	Client id of the API key with the above scopes
client_secret	Client secret of the API key with the above scopes
payment_create_url	{base_url}/api/v1/payments/create
payment_update_url	{base_url}/api/v1/payments/update
customer_update_url	{base_url}/api/v1/customers/update
project_key	Your commercetools project key
scopes	Space separated list of scopes above with project key	e.g. manage_types:your-project-key manage_products:your-project-key...
product_sync_topic	commercetools_product_publish	Unless changed. Must match value in deployment
google_cloud_project	Project connector is deployed to	Used for topic/subscription configuration for gCloud deployments