Digital Rights Details

You can create keys and then associate them with products to deliver and manage Digital Rights. You can create as many keys as needed to satisfy your Digital Rights requirements.

You can create a custom integration to request a key (serial number or unlock code) when a shopper orders a product.

Event
Type
Get Key Request
Webhook

Get Key Request

The Digital Right process is a request/response based process used for retrieving external digital rights. The process requests a serial number or unlock code when a purchase occurs. A key request integration sends a request for a key (serial number of unlock code) when a shopper purchases a product set up to use the integration.


Notification–Global Commerce generates a Get Key Request and sends the request to your endpoint.

Required Response to Notification–Your endpoint must synchronously respond with a Get Key Response.

Digital Rights Request Example

<ns1:GetKeyRequest xmlns:ns1="http://integration.digitalriver.com/DigitalRight/1.0">
 <orderID xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">123456789</orderID>
 <submissionDate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:dateTime">2014-09-24T15:50:12.252Z</submissionDate>
 <orderExternalReferenceID xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string" xsi:nil="true"/>
 <orderLineItemID xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">213456789</orderLineItemID>
 <quantity xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:int">1</quantity>
 <preOrder xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="soapenc:boolean">false</preOrder>
 <productKey xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns2="http://integration.digitalriver.com/Common/1.0" xsi:type="ns2:ProductKey">
  <productID xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">312456789</productID>
  <externalReferenceID xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">4123456789</externalReferenceID>
  <companyID xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">companyID</companyID>
  <locale xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">en_US</locale>
 </productKey>
 <userKey xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns3="http://integration.digitalriver.com/Common/1.0" xsi:type="ns3:UserKey">
  <userID xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">512346789</userID>
  <externalReferenceID>2269079261</externalReferenceID>
  <companyID xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">companyID</companyID>
  <loginID xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">test@example.com</loginID>
  <siteID xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">siteID</siteID>
 </userKey>
 <billingAddress xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns4="http://integration.digitalriver.com/Common/1.0" xsi:type="ns4:AddressInfo">
  <addressID xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">612345789</addressID>
  <city xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">City</city>
  <countryA2 xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string" xsi:nil="true"/>
  <country xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">US</country>
  <countryName xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">United States</countryName>
  <line1 xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">123 Example Street</line1>
  <line2 xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string" xsi:nil="true"/>
  <line3 xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string" xsi:nil="true"/>
  <locationCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string" xsi:nil="true"/>
  <name1 xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">FirstName</name1>
  <name2 xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">LastName</name2>
  <phoneNumber xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">(123) 456-7890</phoneNumber>
  <postalCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">12345</postalCode>
  <state xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">MN</state>
  <email xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">test2@email.com</email>
  <faxPhone xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string" xsi:nil="true"/>
  <companyName xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">Company Name</companyName>
  <phoneNumber2 xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string" xsi:nil="true"/>
  <countyName xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string" xsi:nil="true"/>
  <extendedAttributes xsi:type="ns4:ExtendedAttributesInfoArray">
   <item xsi:type="ns4:ExtendedAttributesInfo">
    <name xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">ExtendedAttributeName</name>
    <value xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">value</value>
    <valueDataType xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">string</valueDataType>
   </item>
  </extendedAttributes>
 </billingAddress>
 <shippingAddress xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns5="http://integration.digitalriver.com/Common/1.0" xsi:type="ns5:AddressInfo">
  <addressID xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">612345789</addressID>
  <city xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">City</city>
  <countryA2 xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string" xsi:nil="true"/>
  <country xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">US</country>
  <countryName xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">United States</countryName>
  <line1 xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">123 Example Street</line1>
  <line2 xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string" xsi:nil="true"/>
  <line3 xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string" xsi:nil="true"/>
  <locationCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string" xsi:nil="true"/>
  <name1 xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">FirstName</name1>
  <name2 xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">LastName</name2>
  <phoneNumber xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">(123) 456-7890</phoneNumber>
  <postalCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">12345</postalCode>
  <state xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">MN</state>
  <email xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">test2@email.com</email>
  <faxPhone xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string" xsi:nil="true"/>
  <companyName xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">Company Name</companyName>
  <phoneNumber2 xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string" xsi:nil="true"/>
  <countyName xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string" xsi:nil="true"/>
  <extendedAttributes xsi:type="ns5:ExtendedAttributesInfoArray"/>
 </shippingAddress>
 <extendedAttributes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns6="http://integration.digitalriver.com/Common/1.0" xsi:type="ns6:ExtendedAttributesInfoArray">
  <item xsi:type="ns6:ExtendedAttributesInfo">
   <name xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">ExtendedAttributeName</name>
   <value xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">value</value>
   <valueDataType xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">string</valueDataType>
  </item>
 </extendedAttributes>
 <orderPricing xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns7="http://integration.digitalriver.com/commonRequisition/1.0" xsi:type="ns7:OrderPriceInfo">
  <total xmlns:ns8="http://integration.digitalriver.com/Common/1.0" xsi:type="ns8:MoneyInfo">
   <currencyCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">USD</currencyCode>
   <amount xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:decimal">11.11</amount>
  </total>
  <subtotal xmlns:ns9="http://integration.digitalriver.com/Common/1.0" xsi:type="ns9:MoneyInfo">
   <currencyCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">USD</currencyCode>
   <amount xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:decimal">11.11</amount>
  </subtotal>
  <tax xmlns:ns10="http://integration.digitalriver.com/Common/1.0" xsi:type="ns10:MoneyInfo">
   <currencyCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">USD</currencyCode>
   <amount xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:decimal">0.00</amount>
  </tax>
  
  
  <shipping xmlns:ns13="http://integration.digitalriver.com/Common/1.0" xsi:type="ns13:MoneyInfo">
   <currencyCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">USD</currencyCode>
   <amount xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:decimal">0.00</amount>
  </shipping>
  <incentive xmlns:ns14="http://integration.digitalriver.com/Common/1.0" xsi:type="ns14:MoneyInfo">
   <currencyCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">USD</currencyCode>
   <amount xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:decimal">0.00</amount>
  </incentive>
  <shippingIncentive xmlns:ns15="http://integration.digitalriver.com/Common/1.0" xsi:type="ns15:MoneyInfo">
   <currencyCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">USD</currencyCode>
   <amount xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:decimal">0.00</amount>
  </shippingIncentive>
  <nonTaxableFees xmlns:ns16="http://integration.digitalriver.com/Common/1.0" xsi:type="ns16:MoneyInfo" xsi:nil="true"/>
  <taxableFees xmlns:ns17="http://integration.digitalriver.com/Common/1.0" xsi:type="ns17:MoneyInfo" xsi:nil="true"/>
  <taxOnTaxableFees xmlns:ns18="http://integration.digitalriver.com/Common/1.0" xsi:type="ns18:MoneyInfo" xsi:nil="true"/>
  <exchangeRate xmlns:ns19="http://integration.digitalriver.com/Common/1.0" xsi:type="ns19:MoneyInfo">
   <currencyCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">USD</currencyCode>
   <amount xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:decimal">1</amount>
  </exchangeRate>
 </orderPricing>
 <lineItemPricing xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns20="http://integration.digitalriver.com/commonRequisition/1.0" xsi:type="ns20:LineItemPriceInfo">
  <unitPrice xmlns:ns21="http://integration.digitalriver.com/Common/1.0" xsi:type="ns21:MoneyInfo">
   <currencyCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">USD</currencyCode>
   <amount xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:decimal">11.11</amount>
  </unitPrice>
  <listPrice xmlns:ns22="http://integration.digitalriver.com/Common/1.0" xsi:type="ns22:MoneyInfo">
   <currencyCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">USD</currencyCode>
   <amount xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:decimal">11.11</amount>
  </listPrice>
  
  <pricePerQty xmlns:ns24="http://integration.digitalriver.com/Common/1.0" xsi:type="ns24:MoneyInfo">
   <currencyCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">USD</currencyCode>
   <amount xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:decimal">11.11</amount>
  </pricePerQty>
  <tax xmlns:ns25="http://integration.digitalriver.com/Common/1.0" xsi:type="ns25:MoneyInfo">
   <currencyCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">USD</currencyCode>
   <amount xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:decimal">0.00</amount>
  </tax>
  
  
  <shipping xmlns:ns28="http://integration.digitalriver.com/Common/1.0" xsi:type="ns28:MoneyInfo">
   <currencyCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">USD</currencyCode>
   <amount xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:decimal">0.00</amount>
  </shipping>
  <handling xmlns:ns29="http://integration.digitalriver.com/Common/1.0" xsi:type="ns29:MoneyInfo">
   <currencyCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">USD</currencyCode>
   <amount xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:decimal">0.00</amount>
  </handling>
  <incentive xmlns:ns30="http://integration.digitalriver.com/Common/1.0" xsi:type="ns30:MoneyInfo">
   <currencyCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">USD</currencyCode>
   <amount xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:decimal">0.00</amount>
  </incentive>
  <reqLevelIncentivePerQuantity xmlns:ns31="http://integration.digitalriver.com/Common/1.0" xsi:type="ns31:MoneyInfo">
   <currencyCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">USD</currencyCode>
   <amount xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:decimal">0.00</amount>
  </reqLevelIncentivePerQuantity>
  <lineItemLevelIncentivePerQuantity xmlns:ns32="http://integration.digitalriver.com/Common/1.0" xsi:type="ns32:MoneyInfo">
   <currencyCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">USD</currencyCode>
   <amount xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:decimal">0.00</amount>
  </lineItemLevelIncentivePerQuantity>
  <taxableFees xmlns:ns33="http://integration.digitalriver.com/Common/1.0" xsi:type="ns33:MoneyInfo">
   <currencyCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">USD</currencyCode>
   <amount xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:decimal">0.00</amount>
  </taxableFees>
  <taxOnTaxableFees xmlns:ns34="http://integration.digitalriver.com/Common/1.0" xsi:type="ns34:MoneyInfo">
   <currencyCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">USD</currencyCode>
   <amount xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:decimal">0.00</amount>
  </taxOnTaxableFees>
  <nonTaxableFees xmlns:ns35="http://integration.digitalriver.com/Common/1.0" xsi:type="ns35:MoneyInfo">
   <currencyCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">USD</currencyCode>
   <amount xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:decimal">0.00</amount>
  </nonTaxableFees>
  <recurringFee xmlns:ns36="http://integration.digitalriver.com/Common/1.0" xsi:type="ns36:MoneyInfo">
   <currencyCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">USD</currencyCode>
   <amount xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:decimal">0.00</amount>
  </recurringFee>
  <shippingBeforeDiscount xmlns:ns37="http://integration.digitalriver.com/Common/1.0" xsi:type="ns37:MoneyInfo">
   <currencyCode xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">USD</currencyCode>
   <amount xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:decimal">0.00</amount>
  </shippingBeforeDiscount>
  
 </lineItemPricing>
 <productAttributes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns38="http://integration.digitalriver.com/Common/1.0" xsi:type="ns38:ExtendedAttributesInfoArray">
  <item xsi:type="ns38:ExtendedAttributesInfo">
   <name xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">ExtendedAttributeName</name>
   <value xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">value</value>
   <valueDataType xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:type="xsd:string">string</valueDataType>
  </item>
 </productAttributes>
 
</ns1:GetKeyRequest>

Successful Digital Rights Response Example

A successful Digital Rights request results in a response that contains a non-null, non-empty key element.

<getKeyResponse>
   <key>
      <item>
         <key>ABC123</key>
         <keyType>SERIAL_NUMBER</keyType>
      </item>
   </key>
</getKeyResponse>

Note that the item element is unbounded. That means you can send multiple keys in a response (in response to the quantity element in this getKeyRequest).

In a successful scenario such as this, the returnCodeisAutoRetryiable, and returnMessage elements are ignored. These elements come into play in an unsuccessful scenario.

Unsuccessful Digital Rights Response Example

An unsuccessful response occurs when the key element is missing or empty. In this situation, Digital River will try to fix the issue causing the non-successful response by using the returnCodeisAutoRetriable, and returnMessage elements and try again.

If the isAutoRetriable flag is set to false, the returnCode element must contain a non-0 response. In addition, the returnMessage element should explain what the value in returnCode means and contain an explanation of what is wrong with the request and, if possible, how to fix it.

<getKeyResponse>
   <returnCode>1</returnCode>
   <isAutoRetriable>false</isAutoRetriable>
   <returnMessage>Unrecognized orderExternalReferenceID - please supply correct value</returnMessage>
</getKeyResponse>

When an unsuccessful Digital Rights response occurs:

  • The consumer is not charged for the line item. In fact, the consumer will not be charged until the consumer receives a serial number, unlock code, or download URL.
  • The line item goes into a "failed digital rights" state. When this happens, the line item appears on the globalCommerce Integration Exception screen.
  • Using the details provided in the returnMessage element, you can use the globalCommerce Integration Exception screen to fix the issue and resubmit the line item.

If the isAutoRetriable element is set to true, Digital River automatically retries the request every hour for 21 days. If there is no action after 21 days, the system "forgets" the order.

When you receive an unsuccessful response or experience communication issues (such as failed transports), the shopping process behaves as follows:

  • The consumer does not receive the Digital Right (serial number, unlock code, or download URL). Instead, the consumer is instructed to wait for an email that will contain the Digital Right.
  • When the Digital Right is fulfilled, the consumer will receive the email.
  • The consumer is charged until the Digital Right is fulfilled.