Validate order

To verify that the articles are in stock when completing a purchase, you can provide a validation URI in the Initialize a Checkout Session request. If provided, this URI will be called before the purchase is completed.

During this validate call your backend can (optionally) create an order and send the order reference back in the response as json.

Note that this order should not be considered completed on your side since the purchase is not completed yet. Please read up on the Handle Purchase Callbacks section since the notification callback is the only valid place to consider a purchase to be successful.

If an order reference is provided in the response it will be shown on the thank you page.

Important

Even if the validate call succeeds (2xx, e.g. 200 OK), the purchase might not be completed. For example, the credit check on the customer might be rejected. The validate call can be performed multiple times if the user tries again.

If this call returns a non-2xx http status code, we will stop the purchase and emit a walleyCheckoutOrderValidationFailed frontend event, read more in section Client-side events. We will follow redirects, e.g. 301.

This call has a timeout of 10 seconds, if the call does not return a response within this timeout the purchase will not be completed and the customer will be shown a message and given the opportunity to try again. This endpoint might be called several times. For example, when the end customer fails the credit check and chooses to purchase by card or direct bank transfer instead, there will be multiple calls to this endpoint.

Validate Call

POST /validation-uri-provided-in-initialize HTTP/1.1
Host: yourdomain.se

Success Response Examples

Response with a reference:

{
  "orderReference": "123456789"
}

Error Response Examples

Response with custom error:

{
  "title": "This is the validation title",
  "message": "This is the message containing details about the validation error"
}

Response with custom client payload:

{
  "clientPayload": {
    "myId": 12345678,
    "myErrorCode": "ERR_SOMETHING_USEFUL"
  }
}

Resonse with custom error and client payload:

{
  "title": "This is the validation title",
  "message": "This is the message containing details about the validation error",
  "clientPayload": {
    "myId": 12345678,
    "myErrorCode": "ERR_SOMETHING_USEFUL"
  }
}

Important

Using this feature increases the time to complete a purchase, causing longer wait times for the end customer. If your ecommerce system supports reservation functionality, consider using that instead. Reservation locks the articles in the customer's cart when visiting the Checkout page, preventing purchases of out-of-stock items.

Request properties

There are no request properties.

Response properties

Properties for successful response

Property	Required	Explanation
orderReference	No	Order reference to the order just created during the validate call. This can later be used to track the purchase with merchant services. It has a 50-character limit.

Properties for unsuccessful response

Property	Required	Explanation
title	No	The title of the validation failure displayed in the Checkout. Truncated to a maximum of 512 characters.
message	No	The message with a more descriptive text why the validation failed, and how the customer should proceed. Truncated to a maximum of 512 characters.
clientPayload	No	The clientPayload object allows you to optionally provide custom validation result information in a key/value format. Client Payload is not processed by Walley but will be sent as a payload parameter on the walleyCheckoutOrderValidationFailed client-side event.

There is a default validation error title and message that is shown if the non-2xx response is empty or if not both title and message are specified in the response. The title and message will appear the following way.