Validate order

In order to verify that the articles exists in stock when completing a purchase you can provide a validation uri in the Initialize a Checkout Session request. If provided, a call this uri will be performed 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.

Please Note

Even if the validate call was successful (2xx, e.g. 200 OK) the purchase might not be completed due to various reasons. For example, the credit check on the customer might be rejected. This also means that 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. Please note that 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. In these cases there will be several 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"
  }
}

Please note!

By using this feature the time it takes to complete a purchase will increase, causing longer wait times for the end customer. If you have reservation functionality in your ecommerce system we suggest you use that instead. Reservation in ecommerce systems is a feature to reserve/lock the articles the customer have in the cart when visiting the Checkout page, preventing customers from buying articles that dont exist in stock.

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.