How to register an order

In this article we will explain the basics on how to use our API for register an order, step by step.

Step 1: Identify payer and receiver

The first step is to identify the payer and the receiver of the order. A payer is a person or a company who is responsible for paying the bill. We are for example using the payer's address to send an invoice. A receiver is a person or a company who receives the product(s) specified in an order. We are using the receivers address to distribute the product(s) specified in an order.

The system will automatically recognize that the payer is also the receiver if the receiver object is not defined.

Step 2: Choose payment method

The second step is to choose a payment method. We provide a number of payment methods. Payment provider configuration is needed to use any of the available payment methods, excluding free and invoice. In order to set up this configuration please contact Mediaconnect support.

After you have chosen a payment method, you need to know if the order should be a recurring payment and the order is prepaid or not. Not all of the payment methods support recurring payment and/or prepayment.

Enter payment information for prepaid order

You need only to enter payment information for prepaid order if the field prepaid = true. We need more information about the payment for a prepaid order. Please define the payment information object to the corresponding payment method object, for example paymentInfoPayex object for paymentMethod creditcardPayex in Register order / Register order - client mode API endpoints.

For more information about the field paymentmethod, please see our API documentation.

Step 3: Choose product specifier

The third step is to choose a product specification type. This field is required and located under orderLines object in Register order / Register order - client mode The field productSpecType describes what type of product(s) that are used in the order. Since we need more information about an order, we have decided to split product specification types into:

• coupon: The way you buy a subscription product and describe it's lifecycle (including price model).
• product: It is anything related to news and books that can be offered to the market, e.g. a book.
• issue: A single copy of a periodical e.g. a magazine.
• article: A specific article on a website.

Required fields for a specific productSpecType

The required fields for a specific productSpecType are described in the table below. The required fields are located under orderLine object in Register order / Register order - client mode API endpoints.

How to grant temporary access

After placing an order, it will be processed in the backend system. This might take some time due to various error conditions and delays. It is possible to provide a temporary grant associated with the order, in order to handle access for the end user until the order has been completely processed. In such cases the order request must contain a product (in allowAccessProduct field) and a number of seconds (in allowAccessSeconds field) for subscription products (productSpecType = coupon). If the order is for issue products (productSpecType = issue), the specified issue code in product field must exist for the given product code specified in allowAccessProduct. To grant temporary access base on category type, you have to specify categorytype in allowAccessCategoryType.

Step 4: Send order

Register order / Register order - client mode API endpoints contains more than 160 fields, and most of them are straight forward to understand. It is not necessary to set a value on every single field in the request when you are sending an order by using these endpoints. When you have set a value for the necessary fields for the order, then you can register the order by sending a request to Register order or Register order - client mode. If everything goes successfully, you will get an orderId in the response. This orderId is needed to fulfill (complete) the order by using the Fulfillment API or Fulfillment URL.

Step 5: Choose to complete your order by fulfillment API or fulfillment URL

There are two alternatives to fulfill an order. Simplified, we can say that you should use fulfillment API if the order is prepaid and fulfillment URL if the order is not prepaid.

Whether you should choose fulfillment API or fulfillment URL depends also on whether the payment method that are used on the order are supported by API or URL, see the table below.

Remember that if you are using McPay to perform payment, the order will be prepaid, and you should use the fulfillment API (e.g. if you have made a payment with vippsRecurring by McPay).

The instruction about how to fulfill (complete) an order is described in two separate articles. You may find them in right side of the menu, under the title "related article".