Nexway Connect
Documentation.
Foreword
Nexway Connect makes it possible to sell thousands of software products and video games in a digital store.
This document aims to provide a good understanding of the value of Nexway Connect and how to best use it to grow your online sales. Business owners and developers are the typical audience for this documentation.
Nexway Connect provides a standard interface for collecting product catalog data (Product Feed) and for managing purchase orders (REST API). Nexway manages the complexity of the business relationship with the Publisher and the End-user product fulfillment.
For more technical documentation, please refer to https://apidoc.nexway.store/docs/nx-connect-api-docs/docs/_main.md.
Was this helpful?
Terminology
• Publisher
Company publishing software, video games, or providing digital services.
• Merchant
Company selling software or games to consumers (B2C) or to companies (B2B). A merchant can be a classic online store or any company that wants to offer and sell digital products (software, video games, and/or digital services) to its audience or customers (end-users).
• End-user
Person or entity purchasing a video game, a software product, or a digital service for their own use.
• Nexway Catalog
Very large catalog of products (software, video games, digital services) that merchants can sell via Nexway.
• Product feed
The subset of the Nexway product catalog that a Merchant wants to offer their customers (end-users).
• Order
An electronic document that gathers the information related to the purchase of a software product, video game, or digital service.
• Fulfillment
All the actions required to provide the customer access to the software or the games purchased (download link, activation or license code, etc.).
Introducing Nexway Connect
Through Nexway Connect, Nexway allows Merchants (resellers) to access a very large catalog of software and video games to add to their online business. Nexway provides a standard interface to collect product catalog data and to submit purchase orders.
Nexway manages the complexity of business relationship between the publisher and the end-user product fulfillment.
Thanks to this solution, you as a Merchant can add thousands of software products and games to your digital store.
A Digital content scenario can be split in 4 steps:
Thanks to Nexway’s online user Interface (Cocoon), you can adapt the format of the flow (XML, CSV, etc.) and select the subset of the Nexway Connect catalog you want to sell in your own store.
2. Integrating the product feed into your product database
A web programmatic interface (HTTP Get) allows you to automate downloading your product feed to integrate it into your store’s product catalog. The product feed contains all the information required by your store (product description, images, pricing, promotions, etc). You can choose to get the full content of your subset or only the latest changes.
3. Managing orders
Connect your order management system to Nexway’s order system via a standard REST API to enable purchase of products in the Nexway Connect catalog.
4. Monitoring your business
Follow and monitor your business activity through Nexway’s online user interface, and access sales reports to track the performance of your business.
Configuring your Product Feed
Use the credentials sent to you by the Nexway Customer Success team (via the email address [email protected]) to connect to Cocoon (preproduction: Cocoon UAT; production: Cocoon Production) to define your product feeds. For each product feed, you can define:
• Product list (categories, publishers, geos, etc.)
Step 1: Define a product feed format
Each feed format is named and allows you to define feed such format parameters as:
• Output format: CSV or XML (the Excel icon will set the output to Excel compliant)
• For CSV format: Selecting fields and order them by clicking on the check-box and dragging and dropping them into the field list
Step 2: Define a product list
You can define your product list by using product defines a segment of the Nexway Catalog using the filtering criteria below:
• Provider
• Top-selling: Products flagged as “Top Selling” in the catalog
• New product: Products flagged as “New” in the catalog
• Limit: Maximum number of products in the product feed
• Territory: Point of sale, product language, product description language
• Categories: List of product categories
• Publisher: List of publishers
• SKU: Product reference code or name
Step 3: Test your product feed
Once created, the product list activates the product feed, which you can test through the Cocoon interface.
The parameters provided via the URL are:
• Secret (mandatory): Alphanumeric (8-10) key sent (Cocoon)
• Provider (mandatory): Product list
• Config (mandatory): Feed format
Note: For security reasons, the IP address used on your side to access the product feed needs to be registered with and authorized by Nexway.
Categories and operating system
Products in the Nexway Catalog are classified in categories and subcategories (for example, Software/Antivirus&Security, CoreGames/Arcade, etc.) and are offered in a predefined operating system. Both the categories and the operating system are constantly enriched. We recommend that you update the list of categories and the operating system on a regular basis.
Product feed download time
The Nexway Catalog is updated every day at 5:30am CET at the latest. You should schedule the download, product feed, and update of your product catalog for after 5:30am CET.
Keep in mind that some products may be removed from the product feed for certain reasons (for example, end of lifetime, out of stock, etc.).
Information to present to your customer
To optimize your business, we recommend displaying the following information to your customer:
• Publisher
• Product language
• Long description
• Packshot
• Screenshots
For Core Games, you should also highlight:
For Software, you should also highlight:
• License duration
• Number of licenses (per-computer, per-user, etc.)
Promotion management
The product feed provides information about the active promotion of a given product during a period.
Pre-order products
Some products can be ordered before they are available for delivery. They are identified as such in the product feed and the order must be submitted to Nexway only when the product is available (after the end of the pre-order phase). It is up to you, the Merchant, to process the purchase when required and to send the order request to Nexway when the product is available for delivery (and thus no longer in the pre-order phase).
Note:
• For some publishers, the order request can be submitted to Nexway before the end of the pre-order phase. In such case, Nexway will communicate to you the date on which you can start to submit the order request.
Electronic product delivery
Nexway Connect supports three delivery modes:
• Download links: Web URL to get the product files. In some cases, the download link references the Nexway Download Manager (a tool to optimize product file reception).
• Serial number only
Serial number required to activate the product (Steam, for example)
• Digital locker (Microsoft only)
Using a Nexway Order Number, the customer connects to Nexway Digital Locker (a Web interface managed by Nexway) to get download links and serial numbers for the product(s) purchased.
Microsoft Products
In the case of Microsoft products, if the Download DVD option is available, this option must be proposed in the cart.
Casual Games
Most of the casual games are available for trial. In this case, the end-user can either:
• Download a trial version to try the game before buying it (try and buy mode)
Both the “buy and down” version and the “try and buy” version are the same product.
The end-user can choose between “play” or “buy” when starting the Casual Game:
• Buy: Launches a web browser with a URL that contants the following elements:
• prodRef = Nexway Product reference
The related product is added to the cart so that the end-user can proceed to purchase.
A template example of such a URL: https://my.domain.com/my_cart.html?prodRef={_PRODUCT_REF}
Ubisoft Products
Follow the instructions below to implement Ubisoft’s new SKA process, which uses a License Activation Portal (LAP).
Identification
You can use DRM data to identify Ubisoft products if you are using catalog version 2.4 or higher:
2. Check that the drm ID value is “Uplay (Ubisoft).”
Note: To identify Ubisoft products when using earlier versions of the catalog, you must verify the following in the product feed API:
2. The value for “digitalLocker” in the deliveryMode node is 1.
Fulfillment
Ubisoft products are activated via a License Activation Portal (LAP), a web interface through which your end-users connect using their Nexway order number and their email address. This means that you as a Nexway customer (Connect partner) must:
• Use the real email addresses that your end-users use to place orders, rather than any aliases (“email 1,” “email 2,” etc.).
• Send the Nexway order number to the end-user.
• Display the remark element of the createOrderResponse resource in the data you send to the end-user. This “remark” contains the following instructions that the end-user needs to access the LAP URL:
b. Enter your Nexway order number, your email address, and the required captcha.
c. Log in using your Uplay account credentials.
d. Click on the “Redeem” button. After redemption is confirmed, the Uplay interface automatically activates your game.
Managing orders
• Submitting orders
List of services
Through Nexway API you can access the following API services:
• Get cross-selling, upselling, and options information
• Get product stock information
• Get order data
• Cancel an order
• Extend download time
• Get order download information
If you have any subscription products available, you can also use the following additional API services:
• Cancel subscription
Submitting orders
Step 1: Check product stock (mandatory)
Nexway highly recommends checking your product stock before adding a product to the customer cart (getStockStatus API).
If no stock is available, the order is refused.
Step 2: Propose cross-selling, upselling, and options for a selected product (optional)
Optionally, you can get a list of products and options to be added to the cart in addition to the initial product selected (getCrossUpSell API).
Available options:
By default, end-user can download their products during 21 days after the purchase. This option allows the end-user to download a new copy of their product as many times as they want during the download time period.
• Backup DVD
A backup DVD of the products purchased will be sent to the end-user.
Step 3: Process the payment in your system (mandatory)
Leverage your own payment system to process the payment of the purchase by the end-user.
Step 4: Create the order (mandatory)
Once the payment has been accepted, you must submit an order to Nexway that provides the information about the product purchased (createOrder API).
Depending on the API return code, the order is accepted or not. A subscriptionID will also be returned if the product is a subscription product.
Note: The real end-user email is requested in the order submission. For security reasons, some publishers send the information to the end-user directly in order to deliver and unlock the product.
Step 5: Share delivery information with the end-user (mandatory)
You must send to or share the following information with the end-user:
• Serial number: The product’s unique serial number (provided by the publisher)
• Download information: Instructions to help the end-user download and activate the product
Canceling orders
When canceling an order:
• You will have to refund the end-user
Managing subscription product orders
List of subscription services
Subscription products allow you to renew a license or service with customer at the end of every license period. Renewal happens by default upon expiry, unless you tell Nexway to cancel the subscription.
If you have any subscription products available, you can access the following additional API services:
Submitting subscription orders
1. Check product stock (mandatory)
Nexway highly recommends checking product stock before you add a product to the customer cart (getStockStatus API).
In case no stock is available, the order is refused.
2. Propose cross-selling, upselling, and options for a selected product (optional)
Optionally, you can get a list of product and options to add to the cart along with the initial product selected (getCrossUpSell API).
The following options are available:
By default, the end-user can download their products for 21 days after the purchase. Thanks to this option, the end-user can download a new copy of their product as many times as they want during the download time period.
• Backup DVD
A backup DVD of the products purchased will be sent to the end-user.
3. Process the payment on your system (mandatory)
Leverage your own payment system to process the end-user’s payment for their purchases.
4. Create the order (mandatory)
Once the payment has been accepted, you must submit the order to Nexway providing information about the product being purchased (createOrder API).
Depending on the API return code, the order is accepted or not. If accepted, a subscription ID is also returned.
Note: The real end-user email is requested in the order submission. For security reasons, some publishers send the information required to deliver and unlock the product directly to the end-user.
5. Share the delivery information with the end-user
Three types of information must be sent to or shared with the end-user:
• Serial Number: Unique product serial number provided by the publisher
• Download information: Useful instructions to help the end-user to acquire and activate the product
Renewing subscriptions
Subscriptions will renew automatically upon expiry, unless cancellation is requested (see cancellation process below).
1. Process the payment on your system (mandatory)
Process the payment on your system before the expiration date.
2. Check that the subscription was created
Check the “Get Subscription Status” API on regular basis (we recommend doing so once every 4 hours) with our subscriptionID, as well as watching for an incremental change in the partner order number generation.
The partner order number is composed of your original partner order number (transmitted in step 1.4) and subscription generation, delimited with dash sign, for example:
• Partner order number after first renewal: PARTNER689-1
• Partner order number after second renewal: PARTNER689-2
• (And so on.…)
3. Get delivery information
When you see a change in the generated number, use your partner order number to call the “Get order data” API to get the order delivery information (such as the license number and activation key).
4. Share the delivery information with the end-user
Canceling subscriptions
An end-user may wish to end (cancel) a subscription.
When cancelling a subscription through the “Cancel subscription” API:
• The license remains active until the expiration date.
• No renewal will take place upon expiry.
Canceling subscription orders
When you cancel an order containing a subscription product:
• You will have to refund the end user.
• No renewal occurs upon expiry.
Monitoring your business
You can monitor your business through our Cocoon interface and track your orders, turnover, and margin. Nexway delivers official reports about your business on a monthly basis.
Testing your implementation
Nexway provides a testing environment (staging environment) to allow you to develop and test your integration.
Once your implementation is ready to go live, you need to inform Nexway and we will check with you that the following test scenarios are correctly implemented:
Catalog management
• getOperatingSystems: Display all the OS supported by Nexway (optional)
Order management
• getCrossUpSell (optional): Get cross-sell and upsell for a product
• createOrder: Create a new order entry
• getOrder: Get order data when a customer encounters an issue (for example, an invalid download link)
Customer support
• getOrder: Get order data
• updateDownloadTime: Extend the download time for an order (optional)
Note: The testing environment (staging) is reset every month (first Sunday of the month).
Nexway Documentation & Support
Documentation
Nexway provides additional documentation to help you implement the Connect solution:
• Product feed documentation reference: apidoc.nexway.store
• FAQ : Frequently Asked Questions (FAQ)
In case you have questions about leveraging Nexway Connect and you don’t see an answer in the Connect documentation, the FAQs, or the {+}API Documentation, you can also contact Nexway directly. Your feedback about our documentation is greatly appreciated.
Support
Technical issues and implementation
Contact the Nexway customer success team at [email protected]
Orders and deliverables
Use your dedicated email (sent to you with your credentials) and provide such information as:
• End-user email
Day-to-day content
For all information about releases, promotions, missing products, and so on, get in touch with [email protected]
Frequently Asked Questions (FAQ)
Table of Contents
• What kind of link do you get with “getDownloadInfo”?
• Which IPs can be whitelisted?
• Why are all my previously-defined product feeds not listed anymore?
• What should I do if I see “Invalid” in the province field?
• What should I do if I receive an error 3011 (XML) message?
• What if I receive a “date is not valid” error?
• What are the different prices available in the product feed?
• Which price must be displayed on the website?
• How do I add a new data column in my CSV product feed?
• A direct download link is missing / Download Manager doesn’t retrieve all the files.
• There’s no serial number listed for the product.
• The download link is http://xxxxdigitallockerxx/xxx and no serial number is displayed. What’s wrong?
Product Feed
How do I set the catalog language in Cocoon?
There are two language types in the catalogue: the master language and the description language.
The best configuration for the feed is:
• Select the description language: Language of the point of sale (ex: FR)
What kind of link do you get with “getDownloadInfo”?
Only direct URL information is provided by getDownloadInfo (no information in the case of DownloadManager).
Which IPs can be whitelisted?
We whitelist only fixed IP addresses (no domain names nor dynamic IPs).
Why are all my previously-defined product feeds not listed anymore?
Every first Sunday of each month, the test environment is reset, which is why you can’t find your product feeds anymore.
What should I do if I see “Invalid” in the province field?
You will have to provide province (or state) data if the country is the US, CA, BR or AU (USA, Canada, Brazil, or Australia, respectively). You must enter the province or state data in ISO 3166-2 format: {+}https://en.wikipedia.org/wiki/ISO_3166-2+
What should I do if I receive an error 3011 (XML) message?
This sometimes happens in the test environment for the simple reason that we do not include all license files on the platform. You won’t see this error on the production site. Just try again with a different product.
What if I receive a “date is not valid” error?
You must enter the order date ousing the ISO 8601 format (ex : 2004-02-12T15:19:21+00:00).
What are the different prices available in the product feed?
• Public price is the recommended price suggested by the publisher.
• Sale price is the current Nexway price (or Partner price, if modified in Cocoon).
Which price must be displayed on the website?
You are free to use the sale price or to set your own price with respect to your margin.
How do I add a new data column in my CSV product feed?
Available fields are present in the format feed configuration via Cocoon.
Order Issues
There’s no download link in the “createOrder” API return.
Some products don’t have download links but only serial numbers.
A direct download link is missing / Download Manager doesn’t retrieve all the files.
Contact customer support level 2.
There’s no serial number listed for the product.
Some products don’t have a serial number.
The download link is http://xxxxdigitallockerxx/xxx and no serial number is displayed. What’s wrong?
Not an issue: Microsoft products are delivered this way.