Create Order

Submit a new order with product selection, payment details, and customer information.

POST /orders

Request Body

{
	"products": [
		{
			"productId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
			"productTypeId": 1,
			"quantity": 1,
			"vehiclePlate": "AB123CD",
			"vehicleCountryIsocode": "AT",
			"vehicleCategoryId": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
			"startAt": "2026-04-01T00:00:00.000Z",
			"endAt": "2026-04-10T23:59:59.000Z",
			"driverFirstname": "John",
			"driverLastname": "Doe"
		}
	],
	"payment": {
		"type": "CARD",
		"paymentMethodId": "pm_1234567890abcdef",
		"returnUrl": "https://yourapp.com/payment/callback"
	},
	"customer": {
		"email": "john.doe@example.com",
		"firstName": "John",
		"lastName": "Doe",
		"phone": "+43123456789"
	},
	"address": {
		"countryIsocode": "AT",
		"city": "Vienna",
		"addressLine": "Mariahilfer Strasse 1",
		"postalCode": "1060",
		"taxNumber": "ATU12345678",
		"companyName": "Doe GmbH"
	},
	"idempotencyKey": "unique-order-key-12345",
	"externalReference": "YOUR-ORDER-REF-001",
	"callbackUrl": "https://yourapp.com/webhooks/vignetim"
}

Products DTO

Field	Type	Required	Description
`productId`	UUID	Yes	The product ID from the catalog
`productTypeId`	integer	Yes	Product type: `1` = VIGNETTE, `2` = ESIM, `3` = INSURANCE, `4` = FINE_PAYMENT
`quantity`	integer	Yes	Number of units
`vehiclePlate`	string	Conditional	Vehicle license plate (required for VIGNETTE)
`vehicleCountryIsocode`	string	Conditional	Vehicle registration country (required for VIGNETTE)
`vehicleCategoryId`	UUID	Conditional	Vehicle category (required for VIGNETTE)
`startAt`	ISO 8601	Conditional	Validity start date (required for VIGNETTE)
`endAt`	ISO 8601	Conditional	Validity end date (required for VIGNETTE)
`driverFirstname`	string	No	Driver first name
`driverLastname`	string	No	Driver last name

Payment DTO

Field	Type	Required	Description
`type`	string	Yes	One of: `CARD`, `GOOGLE_PAY`, `APPLE_PAY`, `IDEAL`, `REVOLUT`, `BANCONTACT`
`paymentMethodId`	string	Conditional	Stripe payment method token (required for `CARD`)
`returnUrl`	string	Conditional	HTTPS URL for 3DS redirect callback (required for `CARD`)

Payment Routing

CARD payments are routed through NestPay and may require 3D Secure verification.
GOOGLE_PAY, APPLE_PAY, IDEAL, REVOLUT, and BANCONTACT are routed through Stripe.

Customer DTO

Field	Type	Required	Description
`email`	string	Yes	Customer email address
`firstName`	string	Yes	Customer first name
`lastName`	string	Yes	Customer last name
`phone`	string	No	Customer phone number (E.164 format recommended)

Address DTO

Field	Type	Required	Description
`countryIsocode`	string	Yes	Country ISO code
`city`	string	Yes	City name
`addressLine`	string	Yes	Street address
`postalCode`	string	No	Postal/ZIP code
`taxNumber`	string	No	Tax identification number
`companyName`	string	No	Company name (for business customers)

Additional Fields

Field	Type	Required	Description
`idempotencyKey`	string	No	Unique key to prevent duplicate orders. Same key with same payload returns the original order (recommended).
`externalReference`	string	No	Your internal order reference for tracking
`callbackUrl`	string	No	URL to receive order status updates

Response

201 Created

{
	"id": "ord-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
	"status": "PENDING",
	"redirectUrl": "https://pay.vignetim.com/3ds/verify/abc123",
	"clientSecret": "pi_1234567890_secret_abcdef",
	"products": [
		{
			"productId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
			"productTypeId": 1,
			"quantity": 1,
			"status": "PENDING"
		}
	],
	"total": {
		"amount": 11.5,
		"currency": "EUR"
	},
	"externalReference": "YOUR-ORDER-REF-001",
	"createdAt": "2026-03-20T14:30:00.000Z"
}

redirectUrl -- Present when 3D Secure verification is required (CARD payments). Redirect the customer to this URL.
clientSecret -- Present for Stripe-routed payments. Use this with Stripe.js to confirm the payment on the client side.

409 Conflict (Idempotent)

If the same idempotencyKey is sent with the same payload, the original order is returned with a 409 status code. This is safe to retry.

{
	"statusCode": 409,
	"message": "Order already exists for this idempotency key",
	"error": "Conflict"
}