Understand the Digital River API structure.
All Digital River API requests are sent to
Digital River uses your account's API keys to authenticate API requests. If you fail to include your key in a request, or send an outdated or incorrect key, we return an error. You can always access your keys in Dashboard.
Your confidential (secret) API key allows you to send an API request to Digital River without restriction. Keep these secret keys confidential and only store them on your servers. Don't use your confidential key for everything. Instead, consider using restricted keys when you want to limit access to your environment.
If you want more security, you can create restricted API keys. A restricted key reduces risk when using or building services. It provides the minimum level of access and permissions a service needs to access specific resources in the Digital River API. Use restricted keys when you want to limit access for services that interact with the Digital River API. You can name a restricted key and assign it to the service you want.
In the test environment, you can test Digital River's features without affecting live data. The production environment allows you to perform actions that affect live data.
In API responses, the
liveModeboolean attribute indicates whether you are in the test or production environment.
The test and production environments behave similarly with the following exceptions:
- You can only use test payment information in the test environment. Card networks and payment providers do not process payments in a test environment.
- In the test environment, Digital River retries webhooks three times over a few hours (as opposed to 72 hours for the production environment) when it does not receive a successful acknowledgment.
These request headers aid Digital River in performing internal troubleshooting and call debugging. Additionally, all of these headers will eventually be available to clients in call logs. They will also be searchable on Dashboard. So, in the future, you'll be able to use these headers to search your own logs.
upstream-idrequest header should represent the unique identifier of the upstream request. This identifier should be __generated by the upstream application.
upstream-application-idrequest header should be an identifier generated by the upstream application that identifies all the calls made by that application. You should use the following format to pass the application name and its version:
<application>/<version>. For example, the header value might be
By providing this identifier, you allow Digital River to filter call logs by application.
In a request, the
upstream-session-idheader should denote the identifier of a browser session. More specifically, this value identifies a single customer session in the upstream application, thereby allowing us to track that customer's path through the Digital River APIs.
forwardedrequest header can designate one or more IP address. This header is primarily used to capture a customer's IP address (in this case, the customer represents the end user of the upstream application). If you use
forwardedto pass more than one IP address, then the value farthest to the right should denote the customer's IP address. In the following example,
for=198.51.100.17is the customer's IP address.
forwarded: for=192.0.2.43, for=198.51.100.17,
In every API response, date-time representations follow this ISO-8601 standard. You rarely have to include dates and times in API requests, but when you do, they must also observe this same standard.
The following are the specific date-time rules we use:
- Dates and times are arranged so the largest temporal term (the year) is placed to the left and each successively smaller term is placed to the right of the previous term. In other words, the values are ordered from the largest to smallest unit of time: year, month, day, hour, minute, and second.
- Each date and time value has a fixed number of digits that are padded with leading zeros.
- The separator used between date values (year, month, and day) is the hyphen, while the colon is used as the separator between time values (hours, minutes, and seconds).
- All numeric values placed to the right of
- Since the letter
Zis the zone designator for zero UTC offset, we add it (without a space) after the time values.