Create order session

This is the initial point in the lifecycle of an order. A successful request response will contain a sessionId and an orderId string. The sessionId will be needed later for rendering the checkout iframe, fetching and updating the session etc.

The session will expire after 7 days.

When the end customer has succesfully completed the checkout flow and the order session is in state authorized, the system will yield an order entity managed by the /orders endpoint. The orderId can now be used for Order management.

curl -X POST 
-H 'authorization: Bearer v4.public.eyJpc3MiOiJs...' 
-H 'content-type: application/json' 
-d '{
	"autoCapture": {
		"delayMinutes": 180,
		"enabled": true
	},
	"country": "SE",
	"currency": "SEK",
	"customer": {
		"companyId": "559311-3714",
		"email": "jane.doe@example.com",
		"firstName": "Jane",
		"lastName": "Doe",
		"phone": "0700000000",
		"reference1": "",
		"reference2": "",
		"ssn": ""
	},
	"locale": "sv-SE",
	"metadata": {},
	"orderLines": [
		{
			"description": "Coffee Machine X200",
			"quantity": 10,
			"reference": "111-222-333",
			"totalAmount": 500000,
			"totalVatAmount": 100000,
			"type": "physical",
			"unitDiscountAmount": 0,
			"unitPrice": 50000,
			"vat": 2500
		},
		{
			"description": "Shipping fee",
			"quantity": 1,
			"reference": "444-555-666",
			"totalAmount": 10000,
			"totalVatAmount": 2000,
			"type": "shippingFee",
			"unitDiscountAmount": 0,
			"unitPrice": 10000,
			"vat": 2500
		}
	],
	"reference": null,
	"settings": {
		"customer": {
			"allowShippingAddress": false,
			"showNameFields": false,
			"showShippingAddressContact": false
		},
		"security": {
			"level": 300,
			"requireClientValidation": false,
			"validationSuccessOnTimeout": true
		},
		"urls": {
			"confirmation": "https://www.example.com?sessionid={session.id}",
			"notification": null,
			"privacy": null,
			"terms": "https://www.example.com/terms.html",
			"validate": null
		}
	},
	"storeId": null,
	"tokenize": false,
	"totalOrderAmount": 510000,
	"totalOrderAmountExclVat": 408000,
	"totalOrderVatAmount": 102000
}'
https://api.sandbox.ledyer.com/v1/sessions

Request body

autoCapture object Optional
An object consisting of the properties `delayMinutes` and `enabled`, `delayMinutes` must be a number between 0 and 10080 (7 days), `enabled` is a boolean. Example: { "delayMinutes": 180, "enabled": true }.
country string
Country code such as `SE`, `FI` etc (ISO 3166-1 alpha-2).
currency string
Example `SEK`, `NOK` (ISO 4217 alpha).
customer object
All customer information.
Show child attributes
companyId string Optional
Company registration number.
email string Optional
Customer email address.
firstName string Optional
Customer first name.
lastName string Optional
Customer last name.
phone string Optional
Customer phone number.
reference1 string Optional
Reference field 1.
reference2 string Optional
Reference field 2.
ssn string Optional
Social security number.
locale string
Specify language for the checkout, `sv-SE`, `da-DK` etc (BCP 47).
metadata object Optional
Merchant may send a key/value object literal for internal use. Example: { "property1": "value1", "property2": "value2" }.
orderLines array
An array of order lines.
Show child attributes
description string
Product name, description etc.
quantity integer
Non negative number.
reference string Optional
SKU or product reference.
totalAmount integer
Total amount in minor units.
totalVatAmount integer
Total VAT amount in minor units.
type string
Type of order line: `physical`, `shippingFee`, `discount`, `giftCard`.
unitDiscountAmount integer Optional
Discount per unit in minor units.
unitPrice integer
Price per unit in minor units.
vat integer
VAT rate in minor units (e.g., 2500 for 25%).
reference string Optional
This property can be used for merchant order reference and will be visible on the invoice. Maximum of 50 characters.
settings object
An object containing various setting possibilities.
Show child attributes
customer object Optional
Show child attributes
allowShippingAddress boolean Optional
Allow customer to enter shipping address.
showNameFields boolean Optional
Show name fields in checkout.
showShippingAddressContact boolean Optional
If true, show an Order recipient section where the customer can add the recipient's first name, last name, email, and phone number. The details are stored in customer.shippingAddress.contact. If false, the section is hidden.
security object Optional
Show child attributes
level integer Optional
Security level (100-500). Higher values require more verification.
requireClientValidation boolean Optional
Whether client-side validation is required.
validationSuccessOnTimeout boolean Optional
Whether to treat timeout as successful validation.
urls object Optional
Show child attributes
confirmation string Optional
URL to redirect after successful checkout. Use `{session.id}` placeholder.
notification string Optional
Webhook URL for notifications.
privacy string Optional
URL to privacy policy.
terms string Optional
URL to terms and conditions.
validate string Optional
URL for order validation webhook.
settlementReference string Optional
Maximum of 50 characters.
source string Optional
A string that should either be `pos` or `online`.
storeId string Optional
Only needed in case of multiple stores with same country and currency.
tokenize boolean Optional
If `true` a customer token will be created that can be used for recurring purchases.
totalOrderAmount integer
Total order amount in minor units.
totalOrderAmountExclVat integer
Total order amount excl. VAT in minor units.
totalOrderVatAmount integer
Total order VAT amount in minor units.
{
	"expiresAt": "2023-09-01T11:25:32.805672147Z",
	"orderId": "or_1xDXf4gwlsnyERFywD9VYZT0Tpp",
	"sessionId": "se_1xDXf4JI3PJsGeVAvLE3hHqYS09"
}

Response Headers

Location string
`/v1/sessions/:sessionId`

Handling sessions

The sessionId string should be stored and re-used until the purchase has been completed or the expiresAt time has been reached.