Create an Instore Order

To create an order, do a rest POST HTTP call to the "/api/v1/orders" endpoint. The body needs to contain information about the order, the customer's mobile phone number, and some merchant settings

info

• Each call to the Instore API must contain a unique order number for the specific merchant.
• Quantity, UnitPrice, DiscountPercent and VatPercent for each order row is expected to be given in minor currency. Eg. send 1000 to set a value of 10
• The vat percent must be valid for the country of the order

Tagging an Order

When an order is created, meta data about the order can be passed in the "tags" property. Providing tags enables new filtering possibilities for reports and statistics.

Example of tags that can be used:

• Merchant branch/franchise
• Store name and location
• Cash register ID and logged on user

If using tags in an hierarchal organization, it is recommended to provide a tag for the leaf node - i.e., the store, as well as tags for each parent up to the root node, i.e., "Solna, Stockholm, SE' if these are regions in the merchant's organization.

Endpoint

Method: POST

/api/v1/orders

Request

Request Model

Name	Description	Type	Additional Information
merchantOrderNumber	A string that identifies the order in the merchant’s systems. The merchantOrderNumber is unique per order. If using Vipps payment method, allowed values are any combination of: A-Z, a-z, 0-9, - and _ (underscore). Example for Vipps: abc-12d-efg-123	String	Max length: 32
countryCode		String
currency		String
mobilePhoneNumber		String
tags		Array of String
orderItems	The total cost of the order rows in the cart needs to be equal or higher than 0 but the cart must not be empty.	Order Items	Free order items/rows, like gift cards, can have a value of 0, denoting no cost
callbackUri	To receive a callback when an order status changes, you need a web server receiving HTTP POST calls.
termsUri	URI to a page with webshop terms.	String	Must be a valid URI Must be accessible by end customer Max length: 500
deferredDelivery	To flag an order with deferred delivery, set the "deferredDelivery" property to true (default: false) when creating the order.	Boolean	More Information
minutesUntilLinkExpires		Int32
presetValues		Collection of PresetValue
requireElectronicIdAuthentication		Boolean
merchantName		String

required field

Request Samples

JSON

application/json

{
  "orderItems": [
    {
      "articleNumber": "abc123",
      "name": "Headphones",
      "quantity": 100,
      "unitPrice": 100,
      "discountPercent": 0,
      "discountAmount": 0,
      "vatPercent": 2500,
      "unit": "st",
      "rowNumber": 1,
      "merchantData": "Size: M"
    }
  ],
  "callbackUri": "https://domain/order/[merchantOrderNumber]/callback",
  "termsUri": "http://domain/terms",
  "deferredDelivery": false,
  "minutesUntilLinkExpires": 20,
  "requireElectronicIdAuthentication": true,
  "merchantName": "string",
  "currency": "SEK",
  "countryCode": "SE",
  "mobilePhoneNumber": "+46700000000",
  "merchantOrderNumber": "234234234-2",
  "tags": []
}

CreateInstoreOrder.cs

//Code sample

Code Snippets

CreateOrderSample.cs

namespace Instore
{
    using APIPortal_CodeSamples;
    using Microsoft.Extensions.DependencyInjection;
    using System.Net.Http.Headers;
    using System.Text;
    using System.Text.Json;

    public class CreateOrderSample
    {
        public static async Task CreateInstoreOrder()
        {
            var services = new ServiceCollection();
            services.AddHttpClient("MyApiClient", client =>
            {
                client.BaseAddress = new Uri("https://webpayinstoreapistage.svea.com");
            });

            var serviceProvider = services.BuildServiceProvider();
            var httpClientFactory = serviceProvider.GetRequiredService<IHttpClientFactory>();
            var httpClient = httpClientFactory.CreateClient("MyApiClient");

            InstoreCreateOrderRequestModel createOrdeRequest = InstoreOrderMockRequest.CreateBaseMockRequest();
            var jsonString = JsonSerializer.Serialize(createOrdeRequest);

            var createOrderRequestJson = new StringContent(
                jsonString,
                Encoding.UTF8,
                "application/json");
            // Add authorization header
            Authentication.BasicAuthenticationToken(out byte[] token);
            httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(token));

            var apiUrl = "/api/v1/orders";

            try
            {
                HttpResponseMessage response = await httpClient.PostAsync(apiUrl, createOrderRequestJson);

                // Check if the request was successful
                if (response.IsSuccessStatusCode)
                {
                    string responseData = await response.Content.ReadAsStringAsync();
                    Console.WriteLine("Response: " + responseData);
                }
                else
                {
                    Console.WriteLine("Failed to retrieve data. Status code: " + response.StatusCode);
                }
            }
            catch (HttpRequestException ex)
            {
                Console.WriteLine("Error: " + ex.Message);
            }
        }
    }

    public class InstoreOrderMockRequest
    {
        public static InstoreCreateOrderRequestModel CreateBaseMockRequest() => new()
        {
            MerchantOrderNumber = Guid.NewGuid().ToString().Replace("-", ""),
            CountryCode = "SE",
            Currency = "SEK",
            MobilePhoneNumber = "+46700000000",
            OrderItems = new List<OrderRow>() {
                    new OrderRow {
                        ArticleNumber = "123-456-789",
                        Name="Article1",
                        Quantity=500,
                        UnitPrice=100,
                        Unit="st",
                        RowNumber = 1
                    },
                    new OrderRow {
                        ArticleNumber="123-asd-fgh",
                        Name="Article2",
                        Quantity=500,
                        UnitPrice=100,
                        Unit="st",
                        RowNumber =2
                    },
                },
            CallbackUri = "https://domain/order/[merchantOrderNumber]/callback",
            TermsUri = "http://domain/terms",
            MinutesUntilLinkExpires = 20,
            RequireElectronicIdAuthentication = true,
            MerchantName = "Demo Merchant"
        };
    }

    public class InstoreCreateOrderRequestModel
    {
        public string MerchantOrderNumber { get; set; } = string.Empty;
        public string CountryCode { get; set; } = string.Empty;
        public string Currency { get; set; } = string.Empty;
        public string MobilePhoneNumber { get; set; } = string.Empty;
        public string[] Tags { get; set; }
        public List<OrderRow> OrderItems { get; set; } = new List<OrderRow>();

        public string CallbackUri { get; set; } = " string.Empty";
        public string TermsUri { get; set; } = string.Empty;
        public bool DeferredDelivery { get; set; } = false;
        public int MinutesUntilLinkExpires { get; set; } = 20;
        public string MerchantName { get; set; } = string.Empty;
        public bool RequireElectronicIdAuthentication { get; set; }
    }
    public class OrderRow
    {
        public string? ArticleNumber { get; set; }
        public string Name { get; set; } = string.Empty;
        public long Quantity { get; set; }
        public long UnitPrice { get; set; }
        public long DiscountPercent { get; set; }
        public long DiscountAmount { get; set; }
        public long VatPercent { get; set; }
        public string Unit { get; set; } = string.Empty;
        public int RowNumber { get; set; }
        public string? MerchantData { get; set; }
    }
}

Response

Response Model

Name	Description	Type	Additional Information
smsSentSuccessfully	Whether the Instore link was send to customer successfully	Boolean
merchantOrderNumber	Order No from Merchant system	String
instoreUiUri	Instore URL generated	String
orderStatus	Status of the order	String
paymentOrderId	Checkout Order Id which identifies an Order , which can be used for managing Orders	String
orderItems		Cart

Response Sample

application/json

{
  "smsSentSuccessfully": true,
  "merchantOrderNumber": "234234234-3",
  "instoreUiUri": "https://instorestage.svea.com/dxqbvg",
  "orderStatus": "Active",
  "paymentMethodType": null,
  "campaignCode": null,
  "paymentType": null,
  "paymentOrderId": 9252643,
  "customerInformation": {
    "shippingAddress": null,
    "billingAddress": null,
    "emailAddress": null,
    "mobilePhoneNumber": null
  },
  "tags": [],
  "orderItems": [
    {
      "articleNumber": "abc123",
      "name": "Headphones",
      "quantity": 100,
      "unitPrice": 100,
      "discountPercent": 0,
      "discountAmount": 0,
      "vatPercent": 2500,
      "unit": "st",
      "rowNumber": 1,
      "merchantData": "Size: M"
    }
  ]
}