Setting up Loyalty Programs

To integrate a loyalty program into the checkout, you must first implement the following endpoints in your middleware or adapter to handle loyalty-related operations:

Type	Operation	Requirement	Purpose
POST	Validate Loyalty Number	Mandatory	Validates the loyalty card number entered by the customer during checkout.
GET	Loyalty Points Conversion Rate	Optional	Defines how loyalty points are converted into a monetary value during checkout, enabling SCAYLE to calculate the redeemable order amount based on the customer’s available points.
POST	Collect/Book Loyalty Points	Mandatory	When an order is confirmed, the corresponding loyalty points must be booked and communicated to the customer through the OSP and the order confirmation email.
POST	Register Loyalty Number	Optional	Submits customer data to register a new loyalty card.
POST	Verify Loyalty Membership	Optional	Verifies whether a registered customer is an eligible loyalty member by validating the provided card number against the loyalty provider, and matching it with the customer's email address. Can be used to enable earning and redeeming loyalty points during checkout.
GET	Check Loyalty Point Balance	Mandatory	Called during checkout after the customer’s loyalty card number has been successfully validated. It returns the current loyalty point balance for that customer.
PUT	Capture Loyalty Points	Mandatory	Deducts the appropriate amount of loyalty points from the customer's account based on the final order value.
POST	Refund Loyalty Points	Optional	Used when an order is canceled or partially refunded. It restores previously captured loyalty points back to the customer's account, based on the refunded amount.

Loyalty data—such as the loyalty number and, if applicable, the promotional code—is automatically included in the order submission payload and forwarded to your system. No additional configuration is needed to attach it.

SCAYLE sends loyalty data to these endpoints, but it is your middleware’s responsibility to connect to the loyalty provider (e.g., PAYBACK) and return the appropriate validation or registration result.

Loyalty Endpoint Schemas

To begin the integration, you’ll find below the schemas for all mandatory loyalty endpoints required for basic functionality. Optional endpoints are listed at the end for extended use cases.

Validate Loyalty Number

Request

Parameter	Type
`cardKey`	string
`type`	enum
`email`	string

Response

Parameter	Type
`valid`	boolean
`loyaltyPoints.balance`	int

Get Loyalty Points Rate

SCAYLE Checkout sends through the Loyalty API a request to get informed what is the conversion rate for the membership points. The request contains currency and type as parameters.

Parameter	Type
`currency`	string
`type`	enum

SCAYLE’s Loyalty API receives the request as stated above, tries to lookup the conversion factor in the database and, if successful, it returns as below:

Property	Type
`conversionFactor`	float

SCAYLE Response Code	Description	Response Body
`200`	Request was successful	See the requirements here.
`404`	Factor not found	Empty
`422`	Parameters not given
`500`	Any other error	Error returned by Middleware

Book Loyalty Points

Upon order confirmation, SCAYLE sends the below request to the Loyalty API:

In case of a successful response, the Checkout shall receive the amount of points for that order:

SCAYLE Response Code	Description	Response Body
`200`	Request was successful	See the sample above
`400`	Bad Request (the information provided is invalid or inaccurate)	Empty
`401`	Unauthorized (unable to verify provided API credentials)	Empty
`422`	Validation failure	Error returned by Middleware

Check Balance

The loyalty point balance is retrieved during checkout after successful validation of the customer's loyalty number. SCAYLE Checkout will send through the Loyalty API a request to your system to fetch the balance amount following the below schemas:

Request Parameters	Type	Requirement
`cardKey`	string	Mandatory
`type`	enum	Mandatory
`email`	string	Optional

The customer’s email is an optional parameter provided by SCAYLE Checkout to the Loyalty API. You can use it to enable personalized experiences or support any required internal processes.

For a successful response, SCAYLE expects to receive the card balance as parameter:

Response Parameters	Type	Requirement
`balance`	integer	Mandatory

Upon receiving this information, the Loyalty API will send the information to the SCYALE Checkout as stated in the below example:

Based on the returned amount, the customer can either proceed using loyalty points alone or combine them with another payment method to cover the full order amount.

SCAYLE Response Code	Description	Response Body
`200`	Request was successful	See the requirements here.
`404`	Contact not found	Empty
`500`	Any other error	Error returned by Middleware

Capture Loyalty Points

The loyalty point balance is captured upon order confirmation, before the order is delegated. SCAYLE Checkout will send a request towards the SCAYLE Loyalty API as follows:

Request Parameter	Type	Requirement
`amount`	integer	Mandatory
`cardKey`	string	Mandatory
`type`	enum	Mandatory
`currencyCode`	string	Mandatory
`orderId`	integer	Mandatory
`transactionKey`	string	Mandatory
`email`	string	Optional

The customer’s email is an optional parameter provided by SCAYLE Checkout to the Loyalty API. You can use it to enable personalized experiences or support any required internal processes.

Example of Request body:

For a success capture, the Loyalty Point API expects an empty response body from the middleware.

Response Parameter	Type	Requirement	Mapping
`amount`	integer	Mandatory	Map to value initially received by Checkout in the `/loyalty/capture` request
`card`	object	Mandatory
`card.cardKey`	string	Mandatory	Map to value initially received by Checkout in the `/loyalty/capture` request
`card.type`	enum	Mandatory	Map to value initially received by Checkout in the `/loyalty/capture` request
`card.currencyCode`	string (max length: 3)	Mandatory	Map to value initially received by Checkout in the `/loyalty/capture` request
`status`	object	Mandatory	-
`card.status.balance`	integer	Mandatory	set to 0 (zero)
`card.status.capturedAmount`	integer	Optional	set to same value as `amount`
`card.status.refundedAmount`	integer	Optional	set to 0 (zero)
`orderId`	integer	Optional	Map to value initially received by Checkout in the `/loyalty/capture` request
`transactionKey`	string	Mandatory	Map to value initially received by Checkout in the `/loyalty/capture` request

Upon receiving the response, SCAYLE Loyalty API will transmit the data to the SCAYLE Checkout. Example below:

Response code mapping

SCAYLE Response Code	Description	Response Body
`200`	Request was successful	See response mapping here
`404`	Contact not found	Empty
`409`	Middleware detected a duplicate transactionKey	Empty
`406`	Capture amount exceeds the value of the balance	Empty
`417`	Loyalty point payment not applicable to current Shop, Country or Currency	Empty
`422`	Validation error	Middleware `422`
`500`	Any other error	Middleware `500`

Refund Loyalty points

Loyalty points are refunded if they were successfully captured, but the capture of the remaining payment via other methods fails and the order is not confirmed. In this case, SCAYLE Checkout will send a refund request towards the SCAYLE Loyalty API with the following schema:

Request Parameter	Type
`amount`	integer
`cardKey`	string
`type`	enum
`currencyCode`	string (max length: 3)
`orderId`	integer
`transactionKey`	string

Example of request body:

In case of a successful response, SCAYLE Loyalty API expects the following:

Response Parameter	Type	Requirement	Mapping
`amount`	integer		Map to value initially received by Checkout in the `/loyalty/refund` request
`card`	object	-	-
`card.cardKey`	string		Map to value initially received by Checkout in the `/loyalty/refund` request
`card.type`	enum		Map to value initially received by Checkout in the `/loyalty/refund` request
`card.currencyCode`	string (max. length: 3)		Map to value initially received by Checkout in the `/loyalty/refund` request
`status`	object	-	-
`card.status.balance`	integer	Mandatory	Set to 0 (zero)
`card.status.capturedAmount`	integer	Optional	Set to 0 (zero)
`card.status.refundedAmount`	integer	Optional	Set to `amount`
`orderId`	integer	Optional	Map to value initially received by Checkout in the `/loyalty/refund` request
`transactionKey`	string	Mandatory	Map to value initially received by Checkout in the `/loyalty/refund` request

The Loyalty API will send this information to the SCAYLE Checkout as stated in the example below:

Response codes:

SCAYLE Response Code	Description	Response Body
`200`	Request was successful	See example here.
`404`	Contact not found	Empty
`409`	Middleware detected a duplicate `transactionKey`	Empty
`417`	Loyalty point payment not applicable to current Shop, Country or Currency	Empty
`422`	Validation error	Error returned by Middleware
`500`	Any other error	Error returned by Middleware

The following endpoints are optional and should be implemented only if your loyalty program requires the related functionality.

Verify Loyalty Membership

Once the customer reaches the payment step in the checkout and the loyalty program slot is available, tenants have the option to perform an additional verification step. This verification ensures that the entered loyalty card number and customer are eligible to earn or redeem points.

This step is optional, and can be used for loyalty programs that require strict customer identification, such as matching the card number against a registered email address.

If the /loyalty/verify endpoint is integrated, SCAYLE Checkout will send a verification request to the loyalty API immediately after the loyalty card number has been validated. The request uses the following schema:

Request Parameter	Type	Requirement
`cardKey`	string	Mandatory
`type`	string	Mandatory
`email`	string	Mandatory

Example of the request sent from the Checkout to the Loyalty API is available below:

As successful response, SCAYLE Loyalty API expects the following parameters:

Response Parameter	Type	Requirement
`cardKey`	string	Mandatory
`type`	string	Mandatory
`email`	string	Mandatory
`valid`	boolean	Mandatory
`loyaltyPoints`	object
`loyaltyPoints.balance`	integer

Example of response body below:

Response code:

SCAYLE Response Code	Description	Response Body
`201`	Validation was successful	See the details here.
`400`	Request could not be processed (invalid JSON)	Empty
`401`	Authentication failed	Empty
`422`	Formal validation failure	Error returned by Middleware

Register Loyalty Number

During checkout, customers can register for a loyalty program via a dedicated endpoint. Once the registration is successful, the loyalty program is immediately linked to the order. This step is optional and should be implemented only if you want to allow customers to register for a membership or loyalty program directly during the checkout process.

Configure a Loyalty Program

You can implement as many loyalty programs as required. After integrating with the APIs, start by setting up the Loyalty Program in the SCAYLE Panel as following:

In the SCAYLE Panel go to Shops ➜ Storefront ➜ Checkout Settings ➜ Loyalty Programs and create/add a new Loyalty Program:

Enter a Name, which is only used to identify the program within the SCAYLE Panel, and a Key, which serves as the unique identifier transmitted in the payload of all requests to the Loyalty API.
To activate the program in checkout, switch on the Enable option; if you want to allow redemption of points, also enable the Redeemable setting.

Next, define the Calculation Factor, which determines how many points a customer earns based on the order total (e.g., with a factor of 0.01, an order of 250 EUR results in 25 points).
Because this calculation may result in decimals, you must also specify a rounding behavior.

Suppose the calculation factor results in 213.2 points for a given order.

Rounding down: The customer receives 213 points (the decimal part is discarded).
Rounding up: The customer receives 214 points (any decimal, even below .5, rounds up).

If you want to enable registration of new customers during checkout, toggle the Registration option, which expands additional fields for entering the required Endpoint and Token for authentication.
Finally, select the APIs that the loyalty program will use: validation, conversion rate, balance, capture, and refund.

In addition to the Loyalty Program setup in Panel, you must configure the following specifications:

disableRemoval - This allows customers to remove an attached loyalty card / membership number from the checkout.
minLength and maxLength of the loyalty card number input. The checkout uses these values for a basic input validation.
icon

Loyalty Program Number - Input Validation

The available programs will be included in the orderState.memberships.suggestions parameter of the state response.