Digital River API reference
Last updated
Digital River API reference
Last updated
The Digital River API Reference is a detailed guide that helps developers integrate Digital River's backend services into their applications. It covers a wide array of functionalities, including payments, taxes, fraud detection, and compliance. The reference provides information on the available endpoints, required parameters, and expected response structures, making it easier for developers to make requests and handle responses in both production and test environments.
The Digital River API speaks exclusively in JSON. You should always set the content-type header to application/json to ensure the API accepts and processes your requests.
All Digital River API requests are sent to https://api.digitalriver.com. It is where your requests are processed.
If you have commerce technology, the Digital River API allows you to integrate our backend payments, tax, fraud, and compliance services.
The Digital River API is a RESTful API. That means Digital River designed it to allow you to retrieve, create, update, and delete objects using the HTTP verbs GET, POST, and DELETE.
You can use the Digital River API in a test environment when you do not want to interact with financial institutions. The API key you use to authenticate a request determines whether the request is in the production or test environments.
Digital River simplifies online commerce by offering a comprehensive suite of products designed to manage payments, risks, and more. Developers can seamlessly integrate these solutions into their applications through our Digital River API, ensuring a smooth transaction process for businesses and consumers. In this section, we'll explore the various offerings available through Digital River, focusing on enhancing your payment capabilities and safeguarding against risks.
Explore Digital River's API suite for Global Seller Services.
Explore options to enable payment methods.
Before making Digital River API requests, you must create a test account in the . The page displays your public and secret keys. For additional information, check out our guide.
The Digital River API authenticates requests using API keys.
Digital River provides secret keys (tokens) for production and test environments in the Digital River API. Each secret key uses a prefix. Use the sk_test_ prefix for test environment secret keys and the sk_ prefix for production environment secret keys. You can use restricted API keys to apply additional restrictions to access and permissions.
Important: Limit access to your API keys to those who need them. Do not store them in a version control system.
When you assign your API key to DigitalRiver.apiKey, the Java library automatically sends your API key in each request.
You must send all API requests over HTTPS. Calls sent over plain HTTP will fail, and this could lead to security vulnerabilities and potential data breaches. Sending an API request without authentication also automatically fails.
The Digital River API uses your account's API keys to authenticate your API requests. Digital River returns an error if you do not include your key when you send an API request or use an incorrect or outdated key.
Your account provides separate keys for testing and for running live transactions. Digital River returns an error if you do not include your key when you send an API request or use an incorrect or outdated key.
Refer to Creating a webhook for more information on creating and managing webhooks.
The metadata parameter is a key feature that allows you to store additional, structured information on an object. This information can be used to provide context or additional details about the object. You can use the metadata parameter to attach key-value data to the following Digital River resources: SKUs, Checkouts, Orders, Customers, Returns, Refunds, and Fulfillments.
For example, you can store your user's full name and ID on a Digital River Customer object. Digital River does not use the metadata. Your users will only see this data if you show it to them.
Do not store data identifying a person, their card information, and so on as metadata.
The metadata parameter supports up to 20 keys. Each key name can be up to 40 characters long, and the values can be up to 500.
All API resources that return lists support bulk fetches. For example, you can use the limit, startingAfter and endingBefore parameters to list orders, customers, and SKUs. The startingBefore and endingAfter parameters use an object ID value to determine the starting point, and the objects appear in the response in reverse chronological order. To return objects listed before the named object, use the endingBefore parameter. To return objects listed after the named object, use the startingAfter parameter. If you provide both parameters, the request uses only the endingBefore parameter.
Parameters are essential components used in API requests to filter and manipulate data. They allow you to specify criteria for retrieving or interacting with resources, ensuring you get precisely the information you need. This section will explore the common parameters available for various operations, focusing on pagination and metadata handling.
limit
This parameter specifies the maximum number of objects returned. You can specify a value between 1 and 100.
startingAfter
This cursor identifies the pagination starting point in the list based on the object ID. For example, if you send a list request and receive 100 customers ending with xyz, your subsequent calls can include startingAfter=xyz to fetch the next page of the list.
endingBefore
This cursor identifies the pagination starting point in the list based on the object ID. For example, if you send a list request and receive 100 objects beginning with xyz, your subsequent call can include endingBefore=xyz to fetch the previous page of the list.
When an API request is made, the server returns a response that includes several attributes detailing the fetched data. Understanding these attributes is crucial to efficiently managing paginated data. Below are the primary attributes included in a typical list response:
data
This array contains response elements. Any request parameter can paginate the response elements.
hasMore
When true, more elements are available after this set. When false, this set marks the end of the list.
A request identifier is associated with each API request. It appears in the response headers under x-dr-requestid. Request identifiers also appear in the URLs of each request log in your Dashboard.
Contact us if you have a question about a specific request. Include the request identifier to ensure a quick solution.
API versioning is critical to ensuring compatibility and stability for the Digital River API applications. By specifying the API version, you control the structure and behavior of the responses your application receives. This allows for seamless integration and consistent performance, even as the API evolves and new features are introduced. It's important to stay informed about updates and manage your API versions proactively to avoid potential disruptions.
Note the following information:
Your account's API version dictates the format of events produced by API requests. We timestamped versions that include significant changes. Each version is dated.
You can test a single API request without upgrading your API key. To specify an API version for a particular request, include a DigitalRiver-Version header, for example:
digitalriver-version=2020-09-30.
Understanding HTTP response status codes is essential for effectively interacting with the Digital River API. These codes provide insight into the outcome of your API requests, allowing you to diagnose issues and handle them appropriately. They are standardized, making developing and debugging API integrations easier by providing clear indicators of success or failure.
These codes indicate whether an API request succeeded or failed. HTTP status codes group responses into the following classes:
The 2xx range indicates success.
The 4xx range indicates an error that failed based on the provided information (for example, you omitted a parameter or a charge failed).
The 5xx range indicates an error with Digital River's servers.
You can programmatically handle some 4xx errors, including an error code that briefly explains the error reported (for example, include an error code when you decline a card).
Understanding the various error types that might arise when interacting with the Digital River API is crucial for effective error handling and debugging. Each error type indicates a specific issue that can occur during an API request, providing detailed insights that help identify and rectify problems efficiently. By categorizing these errors, developers can implement appropriate measures to address them, ensuring smoother API integrations and enhanced user experiences. Below is a comprehensive list of error types you may encounter, along with their descriptions and recommended actions.
bad_request
The server could not process the request due to a client error (for example, malformed request syntax). Correct the problem and try again.
not_found
The server can’t find the requested resource. There is no indication whether the condition is temporary or permanent.
request_timeout
The request timed out because the client did not produce it within the expected time frame, which the server was prepared to wait. Resend the request without modifications at any later time.
internal_server_error
The server encountered an unexpected problem that prevented it from fulfilling the request.
unauthorized
The request requires user authentication. Resend the request with valid user authentication.
too_many_requests
The user sent too many requests in a given time (“rate limiting”). The response should explain the condition in detail and may include a Retry-After header indicating how long to wait before sending a new request.
conflict
There is a request conflict with the current state of the server. Conflicts, such as a 409 response, are most likely to occur in response to a PUT request. For instance, when you attempt to upload a file that is older than the one already on the server, a version control conflict may arise.
validation_error
Our client-side libraries trigger errors when fields fail to validate (for example, when a card number or expiration date is invalid or incomplete). Used by: DigitalRiver.js
no_network
There is no network coverage or cellular data connection.
The following table contains a list of API error codes.
Do not share the error code with customers. Doing so may aid fraudulent and malicious actors.
account_closed
Stop all billing as this account is closed.
already_exists
The item you tried to create already exists.
amount_too_large
The given amount is too large. Provide a smaller amount and try again.
api_key_expired
The API key has expired.
card_expired
The card has expired. Provide valid card information and try again.
card_limit_exceeded
The transaction exceeds the card limit amount.
card_type_block
The merchant has blocked this card type.
card_velocity_exceeded
The transaction exceeds the card velocity amount.
charge_expired
The charge has expired. Provide valid charge information and try again.
charge_not_capturable
The system could not capture the charge.
country_restricted
A customer provided a restricted country. Make sure that customers can only sign up from supported countries.
create-order-failed
The order did not include the required details. As a result, the request to create the order failed.
currency_unsupported
The currency provided is not supported. Provide a supported currency and try again.
declined
The card issuing bank declined the card for an unknown reason.
do_not_honor
The card issuing bank has declined this payment.
email_invalid
The email address is invalid. Provide a valid email address and try again.
failed-request
The request failed to charge the source.
fraud
The issuing bank has identified the transaction as fraudulent.
fraud_block
Digital River has identified the transaction as fraudulent.
invalid_address
The address does not match the card network's records.
invalid_amount
The card network does not accept the amount.
invalid_boolean
The boolean value is invalid. Provide a valid boolean value and try again.
invalid_card_bin
The card's Bank Identification Number (BIN) is invalid.
invalid_card_number
The card number entered is invalid.
invalid_currency
This currency is not supported.
invalid_empty
The empty value is invalid. Provide a valid value and try again.
invalid_expiration_date
The card is expired, or the expiration date is invalid. This validation message indicates that the expiration date did not meet basic validation requirements (for example, it is in the past, the month is incorrect, the year is missing, and so on).
invalid_format
The format of your request is invalid.
invalid_integer
The integer value is valid. Provide a value integer value and try again.
invalid_metadata_key
The metadata key is invalid. Provide a value metadata key and try again.
invalid_metadata_value
The value provided for the metadata was invalid.
invalid_parameter
The parameter is invalid. Check our API Reference to see which values are valid, and try again.
invalid_pin
The customer entered an invalid or incorrect PIN. Make sure that the customer enters a valid PIN.
invalid_quantity_amount
The quantity provided in the request was invalid. Check our API Reference to determine a valid quantity and try again.
invalid_security_code
The customer entered an invalid or incorrect security code. Make sure that the customer enters a valid PIN.
invalid_shipping_choice
The shipping choice is invalid. Provide a valid shipping choice and try again.
invalid_string_blank
The string value is blank. Provide a valid string value and try again.
invalid_string_empty
The string value is empty. Provide a valid string value and try again.
invalid_transaction_type
The transaction type is invalid.
issuer_invalid_card
The card does not exist with the issuer.
issuer_not_found
The card issuer does not exist.
issuer_unavailable
The request could not reach the card issuing bank.
insufficient_funds
The card needs more funds to complete the purchase.
limit_exceeded
The transaction amount exceeds your assigned limit.
lost_stolen_card
The issuing bank has marked this card as lost or stolen.
method_not_allowed
The method is not allowed. Provide a valid method value and try again.
mid_limit_exceeded
The transaction amount exceeds the limit assigned for this MID.
missing_parameter
A parameter is missing. Check our API Reference to see which values are required and try again.
no_response
The payment processor did not respond.
not_found
The request could not find the item.
order_already_complete
The specified order (orderId) is already complete.
order_submit_failed
The payment session status is invalid.
out_of_inventory
The item is not in inventory.
payment_authorization_failed
The payment authorization failed.
pin_try_exceeded
The customer exceeded the bank's maximum number of allowed PIN retries.
plan_not_active
The plan is not in an active state.
postal_code_invalid
The postal code is invalid. Enter a valid postal code and try again.
restricted_card
If a shopper's card is not activated, there are unusual transactions, late payments, or they've exceeded their credit limit, the card network might suspend or restrict it. The shopper should contact their credit card issuer to determine why their card has been suspended or restricted.
restricted_update
You cannot include additional data with this update request
sku_inactive
The given SKU is inactive. Provide an active SKU and try again.
source_expired
The source provided has expired. Check Sources to see which sources have not expired and try again.
source_not_chargeable
The source provided is not chargeable. Check Sources to see which sources are chargeable and try again.
source_not_found
The request could not find the source you specified.
source_status_invalid_for_session
The source status is invalid for this session.
stop_recurring
The cardholder has requested a stop to all recurring and installment charges.
tax_id_invalid
The tax identifier is not valid. Correct the tax identifier and try again.
too_many_metadata_pairs
The request contained too many metadata pairs.
unknown_error
An unknown error has occurred.
unknown_parameter
The request contains an unknown parameter. Check our API Reference to see which values are required and try again.
voice_authorization_required
The request request requires voice authorization before it can be authorized.
You can download the 2021-12-13.json file to access the comprehensive details and specifications for the Digital River APIs. This file contains all the necessary information to integrate and manage the APIs effectively in your environment.
Click the 2021-12-13.json file link below to initiate the download.
Save the 2021-12-13.json file to your preferred directory on your machine.
For more information, see in the documentation.
Webhooks allow developers to be notified, in near real-time, when specific events occur within the Digital River system. By registering webhook URLs, you can set up your application to receive an Event object whenever such events happen. This Event object contains important details about the event, including its type and associated data. Webhook events are sent via HTTP POST requests to the endpoints specified in your account's settings on the Digital River Dashboard. You can configure multiple endpoints to receive notifications for a single event.
To view the webhook events, sign in to the Digital River Dashboard and click Event logs. The display the event type, ID, and timestamp.
All requests will use the version specified in your account's API settings. This version only changes if you upgrade to the most recent API version. For more information, see .
Developers can modify the API version used and create a webhook endpoint with the same API version. This is done by selecting a library version that aligns with the DigitalRiver.API_VERSION property in the library. The provide the necessary API version and detail all breaking changes, giving you full control over the process. See for more information.