Skip to main content

Create a checkout order

Creating an order in checkout is very simple. After you have your checkout merchantId and checkout merchant secret setup, all you need to do is make a request for order creation.

tip

Make sure your request contains correct authentication headers and that you're using Checkout API URI.

Use this request to create a Checkout order. The response contains the necessary data to embed the Checkout widget on your site.

caution

Quantity, UnitPrice, DiscountPercent, DiscountAmount and VatPercent for each order row expected to be given in minor units.

info

HTTP status code 201 indicates that a new Checkout order was created.
HTTP status code 200 indicates that an existing Checkout order was found with the provided clientOrderNumber.

info

To be able to create an order with zero value amount, merchants have to have this feature enabled. Please contact your sales contact for more information.

Endpoint​

Method: POST
/api/orders

Request​

Body Parameters​

CreateOrderModel

NameDescriptionTypeAdditional Information
countryCodeString
currencyString
localeLocale for the orderStringSupported: sv-se, da-dk, de-de, en-us, fi-fi, nn-no.
clientOrderNumberA string that identifies the order in the merchant’s systems. The ClientOrderNumber is unique per order. Attempting to create a new order with a previously used ClientOrderNumber will result in the create method returning the already existing order instead. 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-123StringMax length: 32
merchantSettingsMerchantSettings
cartThe total cost of the order rows in the cart needs to be equal or higher than 0 but the cart must not be empty.CartFree order items/rows, like gift cards, can have a value of 0, denoting no cost
presetValuesCollection of PresetValue
identityFlagsIdentityFlags
requireElectronicIdAuthenticationBoolean
partnerKeyProvided by Svea to select partners.Guid
merchantDataMetadata visible to the storeStringMax length: 6000
Cleaned up from Checkout database after 45 days.
shippingInformationShipping information needed for the shipping checkout. Only applicable if merchant has shipping enabled.ShippingInformation (order)In order to have the shipping checkout 'enableShipping' should be set to true
validationOrder validations such as minimum age requirement should be fulfilled here. (It's nullable it means you do not need to provide anything in case the age limit is not required)OrderValidationApply it in order to have order validation such as minimum age / Nullable
recurring newIndicates if the order is recurring order and will create a recurring token when order is finalized. Only applicable if merchant has recurring orders enabled.
Please check Recurring Order for more details		Boolean / NullIn order to create recurring order this field should be set to true
required field

Response​

Order

NameDescriptionTypeAdditional Information
OrderIdThe id of the Order, needed to get and update order in the Checkout APIInt64
ClientOrderNumberString
GuiContains the Snippet that is used to embed the Checkout UI on your siteGui
StatusThe current status of the orderCheckoutOrderStatus
CartOrder rows.Cart
CurrencyCurrency as defined by ISO 4217String
LocaleThe locale of the Checkout, e.g. sv-SE.String
CustomerCustomer informationCustomer
CountryCodeDefined by two-letter ISO 3166-1 alpha-2, e.g. SE, NO, FI, DKString
EmailAddressCustomer's email addressString
PhoneNumberCustomer's phone numberString
ShippingAddressCustomer's shipping address.Address
BillingAddressCustomer's billing address.Address
PaymentTypeThe payment method that the customer used to finish the purchase. Only set when order status is Final
  • INVOICE
  • ADMININVOICE
  • ACCOUNT
  • PAYMENTPLAN
  • ZEROSUM
  • SVEACARDPAY
  • SVEACARDPAY_PF
  • TRUSTLY
  • SWISH
  • SWISH_PF
  • VIPPS
  • LEASING
  • LEASINGMANUAL
  • MOBILEPAY
String
PaymentThe payment method that the customer used to finish the purchase. Only set when order status is FinalPaymentInfo
SveaWillBuyOrderTrue = Svea will buy this invoice.
False = Svea will not buy this invoice.
null = Selected payment method is not Invoice.		Boolean
MerchantSettingsMerchantSettings
IdentityFlagsIdentityFlags
CustomerReferenceB2B Customer referenceString
PeppolIdA company’s ID in the PEPPOL network, which allows the company to receive PEPPOL invoices. A PEPPOL ID can be entered when placing a B2B order using the payment method invoice.String
MerchantDataMetadata visible to the storeStringCleaned up from Checkout database after 45 days.
ShippingInformationThe returned Shipping information from a previously created/updated order. After the order is finalized and the shipping is created we will include a couple more properties in the ShippingInformation on Order level associated with the Shipping Provider.GetOrderShippingInformation
Recurring newIndicates if the order is recurring order and will create a recurring token when order is finalized. Only applicable if merchant has recurring orders enabled.Boolean / Null
RecurringToken newRecurring token to be used for subsequent recurring orders. Only available when order is finalized. Only applicable if merchant has recurring orders enabled.String / Null
BillingReferencesA collection of B2B billing references.BillingReferenceApplicable for B2B orders

Checkout Shipping​

info

Checkout supports shipping. To enable the Shipping Checkout some additional information needs to be provided when creating an order. Merchant also needs to have nShift configured in order to utilize the Shipping checkout. See further details in the create order model CreateOrderModel how a successful request can be made. Currently not usable together if order has recurring flag set to true

Recurring Orders​

info

To enable the use of Recurring Orders merchants need to have this feature activated. Please contact your sales contact for more information.

The feature will enable subscriptions and other recurring purchases through Checkout. Recurring orders are based on a unique token that is created when the first purchase is finalized. The token represents the customer and their chosen payment method which are used to initiate additional purchases.

For information about how to create recurring orders, see Creating a recurring order

Displaying the Checkout on your site​

When an order is created using the CreateOrder endpoint, the response contains a code snippet that can be embedded on a page of your choice.

Snippet:​

App.tsx
import { useCallback, useEffect, useRef, useState } from "react";
import "./App.css";
import axios from "axios";

export interface CreateOrderResponse {
  OrderId: number;
  Gui: Gui;
}

export interface Gui {
  Snippet: string;
}

export const createCheckoutOrder = async () => {
  // Replace "your-service.com/create-order" with your service
  return axios.post<CreateOrderResponse>("your-service.com/create-order");
};

function App() {
  const divRef = useRef<HTMLDivElement>(null);
  const [checkoutSnippet, setCheckoutOrderSnippet] = useState<string>("");

  const loadCheckoutOrder = useCallback(async () => {
    const order = await createCheckoutOrder();
    if (order.data?.Gui?.Snippet) {
      setCheckoutOrderSnippet(order.data?.Gui?.Snippet);
    }
  }, [setCheckoutOrderSnippet]);

  useEffect(() => {
    loadCheckoutOrder();
  }, [loadCheckoutOrder]);

  // Since a custom script needs to be executed we must add the snippet via contextual fragment
  useEffect(() => {
    const fragment = document
      .createRange()
      .createContextualFragment(checkoutSnippet);
    divRef.current!.replaceChildren(fragment);
  }, [checkoutSnippet]);

  return (
    <>
      <div>
        <h1>Awesome E-Shop</h1>
        <div ref={divRef} />
      </div>
    </>
  );
}

export default App;

Result​

Below is the result of successfully displaying the Svea Checkout widget on the website:

Receiving callbacks from Checkout​

At certain points in an order's lifecycle, we will attempt to call endpoints on your side using the PushUri and CheckoutValidationCallBackUri. You provide these URI:s in the MerchantSettings when you call CreateOrder.

Valid callback URIs​

Make sure that the URIs you provide are:

  • Valid and accepted in your systems
  • Can be resolved from outside your network
caution

Be aware that the CheckoutValidationCallBackUri can be called multiple times for a single order.

Domain registrations​

To be able to receive callbacks we require you to give us your domain names that will be used for callback and validation URIs. On initial contact with Svea you will be asked to provide domain names that you're will use. Any additional domain names should be reported to Webpay Support at support-webpay@svea.com. There is a set of invalid domain names that we don't allow to be used:

  • *.local
  • *.localhost
  • *.example.com
  • *.domain.com
  • *.test
  • *.loc
  • *.local.se
  • *.moc
  • *.ngrcode
  • *.me
  • *.tld

Domains that are unreachable or mocked are not allowed.

Network rules​

If you have a firewall blocking incoming requests, you must whitelist connections from Svea's IP ranges:

  • 193.13.207.0/24
  • 193.105.138.0/24

Age Limit​

caution

Currently available for Swedish, Norwegian and Finnish merchants. Only applied to B2C customers.

In order for having age requirements enabled, particularly minimum age, you may have to either enable it explicitly for your orders while creating them or apply it using a general setting for all of your orders to have the same requirements. However you always can override the rule through the API both using creation and updating the order given certain circumstances If age limit is required, we always ask for BankId authentication once the end customer identifies himself/herself, and Anonymous flow is forbidden as well.

You need to provide MinAge while creating order and it should be a positive integer, otherwise you may leave it as what it is, nothing should be changed on your end! For more information regarding enforcing age requirements, see validation

In case you need to impose the age requirement as a general setting for all your upcoming orders, please contact our support team

Client Libraries​

Client library for PHP - https://github.com/sveawebpay/php-checkout