The confidential (secret) API keys allow 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.
Your account's API version determines the structure of events generated by API requests. It also determines the requests allowed by an API and the responses generated.
A version contains breaking changes that require you to change your workflow. The version's are dated and our implementation allows you to remain on your current version until you're ready to update to the latest version.
Ensure that your API keys are configured for the version expected by your code. In other words, when your code is deployed from test to production, the version on the keys should match the code version.
You can choose from the following options when updating and managing your API versions:
We recommend that you update and test a new API version in your test environment before you update the API version in the production environment. Your production environment can remain on the production version until you are ready to upgrade to the latest version. This allows you to continue using your API keys associated with your production environment while testing a new version in your test environment. When you finish testing, you can update your production environment.
We recommend that you create a restricted API key when you want to limit an application, batch job, or partner to a specific API version. You can also use it to allow your teams to choose when they want to upgrade their API version. You can create, edit, delete, and rotate restricted keys.
You can create a webhook and assign it to a specific version. This allows you to send a specific notification to a team or partner.
You can test a single API request without upgrading your API key. Select a version of the library to change the API version used and create a webhook endpoint with the same API version as the
DigitalRiver.API_VERSION property in the library. Use the Release notes to find the API version you need and view all breaking changes.
To set an API version with a specific request, send the version number in the header:
Digital River often makes non-breaking changes to our API request and response content. As a result, we recommend your integration conform to the tolerant reader principle. Specifically, this means that you should:
Be aware that new elements can be added to responses at any time.
Build your code to extract only the attributes needed when reading responses and ignore everything else.
Avoid coding with a specific order of fields in mind.
Assume that ids are alphanumeric strings, which potentially contain special characters, and they have variable lengths.
Expect changes to the length and value of error messages and other strings that don’t represent an enumeration, type, or code.
Anticipate the addition of new optional request and query parameters.
To improve fraud detection, you should provide an IP address when creating a checkout, invoice, or order.
When working with Digital River to debug calls, please provide the
x-dr-requestid value returned in HTTP response headers. Alternatively, you can generate your own request identifier. If you do so, we'd prefer you use
request-correlation-id as the HTTP header name.
Attempt to minimize HTTP
400 Bad Request and
409 Conflict error types by adding appropriate validation checks before a request is submitted.
GET requests, we encourage making concurrent calls.
Avoid making changes to the same resource in multiple calls. Instead, bundle changes in a single call.
Avoid making concurrent mutation calls to the same resource.
liveMode flag contained in API responses to validate that you are pointing to the correct environment.
The webhook end point must be able to handle concurrent webhook callback requests.
Webhook events may be delivered multiple times. So be sure you can process the delivery of duplicate events.
Your webhook endpoint must respond to callback requests in a timely manner. A response time greater than 3000 milliseconds is considered a timeout. We expect you to immediately acknowledge the callback request by sending an appropriate HTTP
2XX response code. Once this acknowledgment is sent, you can then asynchronously process the webhook event on your end.