Skip to main content

Loyalty programs

A LoyaltyProgram is used to enable clients to run a Loyalty Program for their customers. It consists of the following properties for configuration:

  • Name: Identifier, used for display purposes
  • BackendID: unique identifier, used to identify the program in external systems
  • Handler: the handler used to handle requests for this program: payments/subscriptions
  • UsageType: what this program supports, { BuildUp = 1, Payment = 2 }
  • Data: configuration data for the selected Handler

To manage these programs some nice CRUD services are available:

  • CreateLoyaltyProgram
  • UpdateLoyaltyProgram
  • DeleteLoyaltyProgram
  • ListLoyaltyPrograms
  • Filters: Name, UsageType, Handler
  • GetLoyaltyProgramHandlers

To (un)subscribe to these LoyaltyPrograms, a Subscription can be created. New properties are added to the Subscription services:

  • Create/Update: LoyaltyProgramID, ManualUserIdentifiers
  • List: LoyaltyProgramID, LoyaltyProgramName, IdentifierCustomFieldName, ManualUserIdentifiers
  • GetAvailableSubscriptions: UserIdentifierRequiredForSubscription
  • GetUserSubscriptions: Subscriptions.UserIdentifier, Subscriptions.Subscription.UserIdentifierRequiredForSubscription
  • SubscribeUser: UserIdentifier

The handler on the Subscription should be set to "LOYALTYPROGRAM".

For each Subscription <-> User an identifier can be stored in a CustomField. To allow this, a CustomField of Type User with DataType String should be created. This CustomFieldID can be set on the Subscription. When the UserIdentifier is not provided by the handler, it can be entered in the front end. To support this, the ManualUserIdentifiers property should be set to true on the Subscription. This will result in the UserIdentifierRequiredForSubscription property being true.

To use the LoyaltyProgram for payments, the UsageType should contain Payment (2). Next to this, a PaymentType should be created for the PaymentMethod LOYALTY. This PaymentType needs the LoyaltyProgramID to be set in PaymentType.Properties.LoyaltyProgramID.

At the moment there is only one handler supported for the LoyaltyPrograms: LOYALTYAPI This is the generic API implementation, that allows external parties to receive all loyalty related requests in realtime.

The Data object for LOYALTYAPI on the LoyaltyPrograms should be in the following format:

{
    "BaseUrl": "https://my.endpoint.com/loyalty",
    "Username": "my-basicauth-username",
    "Password": "my-basicauth-password",
    "Timeout": 5 // seconds
}

Eva will call different endpoints for different operations, all calls are POST and contain application/json as request and expect application/json as response.

/get-balance​

Used to fetch the current balance of the LoyaltyProgram of a User

{
    "LoyaltyProgramBackendID": "myloyaltyprogram",
    "PreferredCurrencyID": "EUR",
    "User": {
        "ID": 13784,
        "BackendID": "user-backend-id",
        "CustomID": "user-custom-id",
        "EmailAddress": "user@email.com",
        "Nickname": "user123",
        "LoyaltyID": "LOY383983" 
    }
}

/convert-to-currency​

Used to convert a points amount to the value in a currency

{
    "LoyaltyProgramBackendID": "myloyaltyprogram",
    "PreferredCurrencyID": "EUR",
    "User": {
        "ID": 13784,
        "BackendID": "user-backend-id",
        "CustomID": "user-custom-id",
        "EmailAddress": "user@email.com",
        "Nickname": "user123",
        "LoyaltyID": "LOY383983" 
    },
    "Points": 12.50
}

/convert-to-points​

Used to convert a currency amount to the value in points

{
    "LoyaltyProgramBackendID": "myloyaltyprogram",
    "CurrencyID": "EUR",
    "User": {
        "ID": 13784,
        "BackendID": "user-backend-id",
        "CustomID": "user-custom-id",
        "EmailAddress": "user@email.com",
        "Nickname": "user123",
        "LoyaltyID": "LOY383983" 
    },
    "CurrencyValue": 6.25
}

/subscribe​

Used to subscribe a new user

{
    "LoyaltyProgramBackendID": "myloyaltyprogram",
    "User": {
        "ID": 13784,
        "BackendID": "user-backend-id",
        "CustomID": "user-custom-id",
        "EmailAddress": "user@email.com",
        "Nickname": "user123",
    },
    "RequestedLoyaltyID": "LOY1"
}

/unsubscribe​

Used to unsubscribe a user

{
    "LoyaltyProgramBackendID": "myloyaltyprogram",
    "User": {
        "ID": 13784,
        "BackendID": "user-backend-id",
        "CustomID": "user-custom-id",
        "EmailAddress": "user@email.com",
        "Nickname": "user123",
        "LoyaltyID": "LOY383983" 
    }
}

/pay​

Used to execute a payment with a loyalty points

{
    "LoyaltyProgramBackendID": "myloyaltyprogram",
    "User": {
        "ID": 13784,
        "BackendID": "user-backend-id",
        "CustomID": "user-custom-id",
        "EmailAddress": "user@email.com",
        "Nickname": "user123",
        "LoyaltyID": "LOY383983" 
    },
    "Points": 12.50,
    "PreferredCurrencyID": "EUR"
}

/refund​

Used to refund an executed payment

{
    "LoyaltyProgramBackendID": "refund",
    "User": {
        "ID": 13784,
        "BackendID": "user-backend-id",
        "CustomID": "user-custom-id",
        "EmailAddress": "user@email.com",
        "Nickname": "user123",
        "LoyaltyID": "LOY383983" 
    },
    "Points": 12.50,
    "PreferredCurrencyID": "EUR"
}

Most of these calls use a PreferredCurrencyID, this is used to request the value of the points in a specific currency. If the integration doesn't support the requested currency, it is allowed to respond with a different currency. The configured exchange rates in EVA will be used to convert the value in those cases.

When creating a payment with the LOYALTY payment method, the amount can be specified with the normal Amount on CreatePayment, but it is also allowed to specify the Points amount in the Properties object in the Points property.