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:
Payment Create
Payment Update
Customer Update
Payment
Product
Cart/Order
Line Item
Customer
Shipping Method
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:
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:
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:
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.
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.
product
Any value
Passing additional payment information to and from Digital River
Fields
drEccn
enum
SameForAll
true
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
Merchant Center / PIM
drPartNumber
text
Unique
false
Part number
Merchant Center / PIM
drSkuGroupId
text or enum
SameForAll
false
Merchant Center / PIM
Product
This table lists the default type and field values for the Product resource.
payment
drPaymentFields
Passing additional payment information to and from Digital River
Fields
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.
cart
drCartFields
Passing additional cart and order information to and from Digital River
Fields
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.
line-item
drLineItemFields
Map commercetools line items to Digital River line items
Fields
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
customer
drCustomerFields
Used to pass additional customer information to Digital River
Fields
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.
shipping-method
drShippingMethodFields
Used to pass additional shipping method information to Digital River.
Fields
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:
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:
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:
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
Last updated