Custom loyalty adapter

A custom loyalty adapter allows you to integrate Walley with your own CRM system

Overview

The custom loyalty adapter is an API that you host on your own system. It is called by Walley Checkout when certain events occur. The adapter is used to check whether a customer is a member of your loyalty program, and to create a new membership if the customer chooses to join.

Please Note

This functionality is at an early stage and is not yet available for all merchants. Please contact your Walley representative for more information.

Also note that this is the version 1 of the custom loyalty adapter api, and will be deprecated as soon as version 2 is released later this year.

Authentication

All API requests require Basic Authentication and all communication is over HTTPS.

Endpoints

Get Membership

Description

Walley calls this endpoint to retrieve the loyalty membership details of a customer based on their email, phone number, and registration number. It is typically called after a successful identification of the customer in Walley Checkout.

Example request

GET https://your-adapter.com/api/v1/membership?storeId=123&email=earl.grey@walley.se&mobilePhoneNumber=1234567890&locale=sv-SE

Request Headers

Header	Value
Authorization	Basic

Query Parameters

Parameter	Type	Sent	Description
storeId	string	Yes	The store identifier. Can be used to identify where requests came from in your CRM
email	string	Yes	The customer’s email address.
mobilePhoneNumber	string	Yes	The customer’s mobile phone number.
registrationNumber	string	Maybe	The customer’s registration number. Only sent if the customer has provided it.
locale	string	Yes	The desired locale used to localize applicationText, membershipName and termsUri Supported languages

Response

Success (200 OK)

{
  "isMember": true,
  "applicationText": "Yes, I would like to become a member in ABC Reward Club and confirm the member terms\n Become a member and gain access to:\n- Points on all purchases\n- Bonus checks\n- Exclusive offers",
  "membershipName": "ABC Reward Club",
  "termsUri": "https://merchant-url.com/terms",
  "membershipDetails": {
    "id": "123456",
    "memberNumber": "987654"
  },
  "requiresRegistrationNumber": false
}

Property	Type	Required	Description
isMember	boolean	Yes	Indicates if the customer is a member of the loyalty program or not
applicationText	string	No	The text shown to the customer. See description
membershipName	string	Yes	The name of the loyalty program.
termsUri	string	Yes	The URL to the terms and conditions of the loyalty program.
membershipDetails	object	No	The membership details of the customer. Only provided if the customer is a member of the loyalty program.
requiresRegistrationNumber	boolean	No	Indicates if the adapter requires the registration number to create the membership.

Application text

The applicationText property is shown to the user if provided. It can show unique selling points if the user is not a member, or membership benefits if the user already is a member. It supports simplified markdown, and supported formatting are:

**bold** bold

*italic* italic

- bullet • bullet

\n new line

Errors & Timeouts

If the response is not received within 10 seconds, the request will be considered timed out. 1 retry will be made for server errors and http exceptions after 2 seconds back-off.

Any non 2xx response or timeout will result in the fallback to not show the membership details to the user.

Create Membership

Description

After the customer completes their purchase, Walley calls this endpoint if the customer is not yet a member. The applyMembership property indicates whether they chose to apply for membership.

Example request

POST https://your-adapter.com/api/v1/membership

Request Body

{
  "applyMembership": true,
  "storeId": "store-123",
  "externalStoreId": "ext-5678",
  "address": {
    "firstName": "John",
    "lastName": "Doe",
    "street": "123 Main St",
    "postalCode": "416 70",
    "city": "Gothenburg",
    "countryCode": "SE"
  },
  "email": "john.doe@example.com",
  "mobilePhoneNumber": "+46701234567",
  "registrationNumber": "000000-0000"
}

Request Headers	Value
Authorization	Basic
Content-Type	application/json

Property	Type	Sent	Description
applyMembership	boolean	Yes	Indicates if the customer wants to apply for membership.
storeId	string	Yes	The store identifier. Can be used to identify where requests came from in your CRM
externalStoreId	string	Maybe	The external store identifier provided when initializing a checkout.
address	object	Yes	The address of the customer.
email	string	Yes	The customer’s email address.
mobilePhoneNumber	string	Yes	The customer’s mobile phone number.
registrationNumber	string	Maybe	The customer’s registration number. Only sent if the customer has provided it.

Response

Success (201 Created)

{
  "id": "123456",
  "memberNumber": "987654"
}

Property	Type	Required	Description
id	string	No	The internal ID to identify the membership
memberNumber	string	No	The member number of the customer.

Errors & Timeouts

If the response is not received within 10 seconds, the request will be considered timed out. 1 retry will be made for server errors and http exceptions after 2 seconds back-off.

Any non 2xx response or timeout will result in the membership not being created.

After the payment is completed

When acquiring checkout information, and the status property is PurchaseCompleted, the data.customer.loyaltyMembership object contains information about the outcome of the membership registration.

Property	Type	Returned	Description
provider	string	Yes	Always `custom` for a custom adapter.
success	bool	Yes	`false` if the registration of membership failed.
isMember	string	Maybe	Indicates membership, possible values are: yes, no, new.
id	string	Maybe	The internal ID to identify the membership.
memberNumber	string	Maybe	The member number of the customer.

There will be four possible outcomes:

The customer is already a member, so no registration was performed.
The customer chose to apply for membership, and a membership was registered successfully.
The customer chose not to apply for membership.
The customer chose to apply for membership, but the registration failed due to technical reasons.

Please note

When the membership failed to register due to technical reasons, it is recommended to create the membership manually so that the customer does not lose their points, bonus levels or similar. To see why the registration of the membership failed, please see the developer logs in the Merchant hub

1. Customer is already a member
2. Customer was registered successfully
3. Customer chose not to apply for membership
4. Membership failed to register

{
  "data": {
    "customer": {
      "loyaltyMembership": {
        "provider" : "custom",
        "success": true,
        "isMember":"yes",
        "id": "9b43c86e-227b-4149-b0ee-de7f4846be26",
        "memberNumber": "123456789"
      }
    }
  }
}

{
  "data": {
    "customer": {
      "loyaltyMembership": {
        "provider" : "custom",
        "success": true,
        "isMember":"new",
        "id": "9b43c86e-227b-4149-b0ee-de7f4846be26",
        "memberNumber": "123456789"
      }
    }
  }
}

{
  "data": {
    "customer": {
      "loyaltyMembership": {
        "provider" : "custom",
        "success": true,
        "isMember":"no"
      }
    }
  }
}

{
  "data": {
    "customer": {
      "loyaltyMembership": {
        "provider" : "custom",
        "success": false
      }
    }
  }
}

Custom loyalty adapter

Overview​

Authentication​

Endpoints​

Get Membership​

Description​

Example request​

Request Headers​

Query Parameters​

Response​

Success (200 OK)​

Application text​

Errors & Timeouts​

Create Membership​

Description​

Example request​

Request Body​

Response​

Success (201 Created)​

Errors & Timeouts​

After the payment is completed​

Overview

Authentication

Endpoints

Get Membership

Description

Example request

Request Headers

Query Parameters

Response

Success (200 OK)

Application text

Errors & Timeouts

Create Membership

Description

Example request

Request Body

Response

Success (201 Created)

Errors & Timeouts

After the payment is completed