Web service

Overview

A web service is a license generation method allowing you to fulfill orders by delivering products to customers electronically.

With this delivery method, a web service must be developed on your end. Upon request from our end, this web service will generate a license for a product and return it in response. We will send the received license to the customer by email.

Supported:

Data transfer method: POST or GET
License format: text
If a license is a file, it must be stored on your end and be available via a link. As a license, you transfer a link to a file with a license.

Interaction security is ensured by verifying a signature in the header of each request.

Set Up First Fulfillment

Basic Settings

If you have not previously set up fulfillment for your products:

Open the Merchant Portal and log in
Go to Products / Overview
You must have at least one product created for the fulfillment option to be available. In this case, after the search form, you will see the fulfillment setup section
Click Set up in the fulfillment section
Select the following License generation method - Web service (or Test web service if you are working in test mode)
Enter your Web service URL – this is the address of the web service on your end that will receive requests to generate a license. The URL must be accessible over HTTPS
Select a Data transfer method:
- GET - parameters will be transferred to your web service in the URL having the following form:
  http://[your-web-service-endpoint-url]?=[parameter1_name]=[parameter1_value]&[parameter2_name]=[parameter2_value]
- POST - parameters will be transferred in the request body in format JSON
Enter a Secret key - this value will be used when generating a signature of a request to the web service
Select what License quantity must be delivered for your product in an order:
- 1 license per unit - when ordering several units of the same product, you must send the same number of licenses to the customer (e.g., if an order contains 5 units of one product, you must send 5 licenses). If this option is selected, we will send a separate request to get a license for each unit of the same product in one order. All received licenses will be sent to the customer in one email
- 1 license per product - you must send one license for a product, regardless of the number of product units purchased (e.g., if an order contains 5 units of one product, you must send only one common license)
Set up customer emails containing licenses
(Optional) Use parameters to add order/product/customer data to the request
You can test sending a request before saving the web service
Click Save

Customer Emails with Licenses

When setting up fulfillment through a web service, you can also set up the emails that will contain licenses sent to customers.

You have two options available:

We send emails containing licenses (recommended)

In this case:

We get a license from your web service and store it on our end. Later, we can use this to resend the license to the customer (e.g., if the customer contacts our support team with such a request)
The system generates an email and includes the license in it (you can manage the text that is used to insert the license into the email) and sends the email to the customer
The system processes successful product fulfillment using the standard method

To connect this option on the page where you set up fulfillment via your web service:

Enable the following option Send email with license to customers
Enter a text into the field named Section with license to be sent to customer by email. This text will be used to insert the license received from your web service:
- For the license to be substituted into the text, you must use tag {KEY}
- You can use additional substitution tags to add order/product/customer data
- View an example of a customer email containing a license. Note that the text you provide will be added into the email template containing our greeting, signature and order details, so you do not need to include this data into the section with a license

Additionally:
You can use the Product API to configure this text individually for a specific product and each interface language.

You send emails containing licenses

In this case:

We only send a request for a license to your web service
Your web service must return HTTP/1.1 200 OK in response to a request for a license. When a correct response is received:
- The response is not stored as a license on our end
- We send no emails containing licenses to the customer. Please note that you must send the email to the customer yourself. On the order page, the customer sees that the email containing their license has been sent
- The system processes successful product fulfillment using the standard method
You send an email containing a license

To connect this option on the page where you set up fulfillment via your web service:

Disable the following option: Send email with license to customers

Request Parameters

You can manage data transferred in a request to your web service. By default, the request does not contain any data.

To manage the parameters of the request on the page where you set up fulfillment via your web service:

Click + Add if you want to add a parameter to the request
A form must open. It has two fields: parameter name and parameter value
Select a parameter value in the second field. This is the order or product property that will be transferred to your web service
Modify the name of the parameter in the first field if necessary

Parameter Reference

Example

For example:

Your web service is available at: https://you-company.com/license
You want to send the data in the request:
- Order ID
- Product ID
- Quantity of the product in the order
- Order currency
- The value of the additional parameter Referer1
The customer paid for order No. 19583505 for 1 piece of product with the identifier 19583478 (currency: USD, Referer1: 123)

In this case:

When using the GET method:
- We will send a request to get a license from your web service to:

CODE

https://you-company.com/license?Order=19583505&ID=19583478&Quantity=1&Currency=USD&Referer1=123

When using the POST method:
- We will send a request to get a license from your web service to: https://you-company.com/license
- The request body will contain parameter:

CODE

{
  "Order": "19583505",
  "ID": "19583478",
  "Quantity": "1",
  "Currency": "USD",
  "Referer1": "123"
}

Modify Settings

If you have already set up fulfillment for your products and want to modify your settings:

Open the Merchant Portal and log in
Go to Products / Overview
You must have at least one product created for the fulfillment option to be available. In this case, after the search form, you will see the fulfillment setup section
Click Edit in the fulfillment section
Edit the values of the fields:
- If you previously used a different license generation method and want to switch to using a web service, select Web service (or Test web service if you are working in test mode) in the field related
- Further configuration is made the same way as when setting up the web service for the first time

Please note that modifying your fulfillment settings will affect all your products; i.e. your products created earlier, and new ones will use fulfillment via your web service.

Work with Your Web Service

More details on:

How to secure interaction with signature verification
How your web service must respond to the request transferred to get a license
How errors of interaction with the web service are handled

Test

After you have provided the required data to set up your web service, you can test your settings. In this case, you do not have to save any changes to the web service settings.

Test Request to Your Web Service

With this feature, you can send a request to your web service without having to purchase a product through a checkout page.

For this purpose:

On the page where you set up fulfillment via your web service, click Test
The system automatically makes a request to your web service based on the current fulfillment settings. If the request contains parameters, test values are inserted into them
You must see the information about the completed request and the received response of your web service in the modal window

When a test request is executed, no additional actions are taken to process product fulfillment (no customer email with a license and no webhook notification are sent). Only the request is sent.

Test Purchase

More details on:

Web Service Emulator on Your End

If you have not yet developed a web service and want to see a sample request on your end, you can use a mock web service. You must set up a test web service that will receive requests on a special web tool. More details on how to use it.

Web Service Emulator on Our End

If you want to test fulfillment processing (e.g., how a webhook or an email with a license are received, etc.), but you do not have a web service yet and do not want to set up an emulator on your end, you can connect our web service emulator. This is our web service that issues test licenses upon request. More details on how to use it.

Noventiq Merchant Portal

Merchant Portal	https://merchants.noventiq.com/
Support	merchants.help@noventiq.com