Automatic fulfillment via 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.

How it Works

Main Scenario

• The customer successfully pays for their order

• Your web service receives a request for a product license. The request may contain additional order/product/customer data

• Your web service generates a license based on the received data and responds to the request (synchronous interaction)

• Next, the license will be:

• Saved into the order (this can be re-sent to the customer if necessary)

  • Sent to the customer by email

  • (Optional) Shown to the customer on the order page

• On our end, the system executes standard processing of successful order fulfillment

Disable Emails with Licenses

Sending the customer an email containing a license can be disabled. In this case:

• Your web service receives a request to generate a license and must return a success response (HTTP/1.1 200 OK)

• On our end, the system executes standard processing of successful order fulfillment

• You must send the license to the customer yourself (no license will be stored on our end)

Error Processing

If an error occurs while interacting with your web service, it can be considered temporary or fatal:

• The following cases are considered temporary errors:

  • Your web service is unavailable

  • Your web service returns a response that matches the temporary error pattern in the web service settings

  In these cases, repeated requests are automatically sent to your web service:

  • Number of retries: 4

  • Frequency of attempts: in 1 minute, in 30 minutes, in 2 hours, in 24 hours from the moment of order payment

• The following situations are considered fatal errors:

  • Your web service returns a response that matches the fatal error pattern in the web service settings

Request Settings for Your Web Service

Main Settings

Request Signature

Every request to your web service contains a signature in the request header. Use signature verification to confirm that the request is sent by us.

Signature Format:

• Hash from string listing:

  • secret key - value is set on our end in web service settings

  • values of all parameters in request, sorted alphabetically by parameter name

• Value separator: ;

• Generation algorithm: SHA-512

Example of signature generation for data:

• Secret key = secret0!

• Request parameters (GET method): ?Order=19583505&ID=19583478&Quantity=1

Signature generation:

• Arrange parameters by name (alphabetically): ID, Order Quantity

• Make parameter values string: 19583478;19583505;1

• Add secret key to string: secret0!;19583478;19583505;1

• Get SHA-512 from string: secret0!;19583478;19583505;1

Final signature value in request header:

• signature: "f9ed72bc7006a047f15a7cb62556342bff5463defd14f3b0dabdcebf757b33620eb8a4a0d08c512fcda20de926e37819865ea5f511070ab130d374dd1820ded5"

Request Parameters

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

• Request format for POST method: JSON

• Encoding: UTF-8

See Parameters 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: 

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: 

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

Request Response

Your web service must respond to our request as follows:

• If the request is successfully processed, the response must contain:

  • HTTP/1.1 200 OK

  • Product license in email body 
    May be missing if our emails with licenses are disabled

• In case of unsuccessful processing of the request:

  • HTTP status different from successful processing status

  • (Optional) Error text - web service settings allow you to set the texts of temporary and fatal errors for flexible handling of these issues. More details on web service settings

Customer Emails with Licenses

After a license has been received from your web service, the system generates an email containing this license and sends it to the customer. The emails can be disabled. In such a case, you must deliver licenses to customers yourself.

Scenarios:

• We send emails containing licenses (recommended)

• You send emails containing licenses

We Send Emails Containing Licenses (recommended)

In this scenario, we receive a license from your web service, and then we generate an email containing this license and send it to the customer. In addition, the system executes standard processing of successful order fulfillment on our end.

You have the control over the text block that allows you to insert the license into the email. You can customize it through:

• Merchant Portal - to get a license through the web service; this text is used as the default text for all products 

• Product API - to get a license using any generation method; if this text is provided, it is used instead of the default text; configured individually for a specific product and each interface language

• Our support team on request

How to customize the text:

• Make sure to use tag {KEY} - licenses received from your web service substitute for this tag

• You can use additional substitution tags to add order/product/customer data to the email

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. See an email example. If you want to edit any parts of the template that are managed on our end, contact our support team

You Send Emails Containing Licenses

You can disable our emails with licenses sent to customers in the web service settings via the Merchant Portal or by contacting our support team.

In this case:

• Your web service must return HTTP/1.1 200 OK

• On our end, the system executes standard processing of successful order fulfillment

• License must be sent to customers on your end

Set Up

Connecting a web service to products depends on how these products are managed:

• Merchant Portal – set up fulfillment through the Merchant Portal; you can set up one common web service for all your products

• Product API – contact our support team to set up fulfillment; you can set up an individual web service for each checkout currency

• Dynamic Product Checkout API:

  • If an original product is created through the Merchant Portal, set up fulfillment through the Merchant Portal too (standard method)

  • Otherwise, contact our support team

Other methods to manage products - contact our support team to set up fulfillment.

Test

Purchase in Test Environment

The Merchant Portal allows you to purchase in a test environment without paying for the order with actual money.

For this purpose:

• Switch the portal to Test Mode

• Create at least one product
  You can also use the Product API connected via API Keys, or create a product that you will use as an original product to work with the Dynamic Product Checkout API

• Set up fulfillment via a web service to your products (for all product creation methods)

• Add a product to the checkout page via a checkout link
  You can create the checkout link manually, get it using the Merchant Portal or the Dynamic Product Checkout API (based on your work scenario)

• Make a purchase through the checkout page:

  • Enter customer data, provide your email as customer email to receive an email containing a license later

  • Confirm acceptance of the terms of sale (if required) and click Continue to confirm the creation of your order

• Pay for the order using test payment methods

• After that, the system will make a request to your web service to get a license

• If you get the license successfully:

  • (Optional) You will see the license on the paid order page

  • (Optional) You will receive an email containing the license to the email address provided from customer data

  • (Optional) Your web service will receive a webhook on successful fulfillment (product.delivered)

  • In the ESupport portal, the additional status of the order will change to Delivered (you can go to the ESupport portal by clicking Orders in the Merchant Portal)

• If an error occurs, no additional action is provided. If you have received no email containing the license:

  • Check your spam or junk folder in your email application - the email may have ended up there

  • Check your web service interaction logs to determine why the license has not been sent in response to our request

  • If necessary, contact our support team to check the logs on our end

• If you make a purchase in test mode, no further action is required

• If your web service issues a valid license (not a test one), annul it on your end

Purchase in Production Environment

If you want to test license fulfillment in Sales Mode:

• Disable Test Mode when using the Merchant Portal

• Create at least one product
  You can also use the Product API connected via API Keys, or create a product that you will use as an original product to work with the Dynamic Product Checkout API

• Set up fulfillment via a web service to your products (based on the product creation method you use)

• Add a product to the checkout page via a checkout link
  You can create the checkout link manually, get it using the Merchant Portal or the Dynamic Product Checkout API (based on your work scenario)

• Make a purchase through the checkout page:

  • Enter customer data, provide your email as customer email to receive an email containing a license later

  • Confirm acceptance of the terms of sale (if required) and click Continue to confirm the creation of your order

• Pay for the order with actual money or contact our support team to change the status of your order manually

• After that, the system will make a request to your web service to get a license

• If you get the license successfully:

  • (Optional) You will see the license on the paid order page

  • (Optional) You will receive an email containing the license to the email address provided from customer data

  • (Optional) Your web service will receive a webhook on successful fulfillment (product.delivered)

  • In the ESupport, the additional status of the order will change to Delivered (you can go to the ESupport portal by clicking Orders in the Merchant Portal)

• If an error occurs, no additional action is provided. If you have received no email containing the license:

  • Check your spam or junk folder in your email application - the email may have ended up there

  • Check your web service interaction logs to determine why the license has not been sent in response to our request

  • If necessary, contact our support team to check the logs on our end

• Go to the ESupport portal and submit a refund request for your order. As the reason for your order to have been created, write "Test order" and describe how you have paid for the order (with actual money or with the help of our support team)

Test Request (no order creation)

If fulfillment has been connected via the Merchant Portal, you can make a test request to your web service. No purchase through the checkout page is required.

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.

For this purpose:

• Create a Mock Server, for example, with Postman (see instructions on Postman website)

• When created, you will receive the URL of the web service

• Use this URL when setting up a connection to the web service

• Initiate a test request or make a test purchase

• Check the test web service (on the website where you created it). You will be able to see the content of the received request

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 through the Merchant Portal.

This is our web service that issues test licenses upon request. More details on how to use it.

Noventiq Checkout