Class FanPointsModule<PartnerLabel>

This class allows you to interact with the FanPoints module. The FanPoints module allows to distribute FanPoints to users and collect FanPoints from a user as a method of payment.

Type Parameters

  • PartnerLabel extends string

Methods

createFanPointsPaymentSession createTixevoFanPointsPaymentSession estimateGivenOutFanPointsOnPurchase getBalance getPriceInFanPoints getTransaction getTransactions giveFanPointsOnPurchase payPurchaseWithFanPoints registerTixevoCheckout undoPurchase

Methods

createFanPointsPaymentSession

  • createFanPointsPaymentSession(price, successUrl, cancelUrl, customPurchaseId?, loyaltyProgramId?, webhookUrl?, partnerId?, partnerLabel?, currency?): Promise<{
        amount: number;
        cancelUrl: string;
        currency: Currency;
        customPurchaseId: undefined | string;
        expiryDate: string;
        partnerId: string;
        sessionId: string;
        sessionUrl: string;
        status: FanPointsPaymentSessionStatus;
        successUrl: string;
    }>

  • Creates a new payment session which can be used to allow payment with FanPoints.

    The flow is as follows:

    1. When your user chooses to pay with FanPoints, you can use this method to create a payment session.
    2. The payment session has a unique session URL with the checkout form hosted by the loyalty program. Redirect your user to this URL.
    3. The user completes the checkout and is redirected to the given callback URL or cancellation URL.
    4. A request is sent to the webhook URL if provided.

    This flow is preferred over the payPurchaseWithFanPoints method as it allows to properly authenticate the user on the checkout page hosted by the loyalty program.

    Parameters

    • price: number

      the price of the purchase

    • successUrl: string

      the URL to redirect to if the user completes the payment successfully

    • cancelUrl: string

      the URL to redirect to if the user cancels the payment

    • OptionalcustomPurchaseId: string

      an optional custom purchase id which can be used to link the payment to a specific purchase in your system

    • OptionalloyaltyProgramId: string

      the ID of the loyalty program, where the user belongs to (only needed if the client config does not contain a loyalty program ID)

    • OptionalwebhookUrl: string

      the URL to send a request to after the payment is completed

    • OptionalpartnerId: string

      the id of the partner where the purchase happened (only needed if the client config does not contain a partner ID)

    • OptionalpartnerLabel: PartnerLabel

      the label of the partner where the purchase happened (optional)

    • Optionalcurrency: Currency

      the currency of the price (only needed )

    Returns Promise<{
        amount: number;
        cancelUrl: string;
        currency: Currency;
        customPurchaseId: undefined | string;
        expiryDate: string;
        partnerId: string;
        sessionId: string;
        sessionUrl: string;
        status: FanPointsPaymentSessionStatus;
        successUrl: string;
    }>

    the created session with the session URL

    Throws

    RequestError if the given price is not valid (invalidRewardAmountError) or if the given custom purchase id is not valid (invalidTransactionIdError).

createTixevoFanPointsPaymentSession

  • createTixevoFanPointsPaymentSession(partnerType, price, successUrl, cancelUrl, webhookUrl?, customPurchaseId?, currency?): Promise<{
        amount: number;
        cancelUrl: string;
        currency: Currency;
        customPurchaseId: undefined | string;
        expiryDate: string;
        partnerId: string;
        sessionId: string;
        sessionUrl: string;
        status: FanPointsPaymentSessionStatus;
        successUrl: string;
    }>

  • Creates a new payment session which can be used to allow payment with FanPoints.

    Use this method when your loyalty program is connected to Tixevo. In contrast to the createFanPointsPaymentSession method, this method only works if your client is configured with the loyalty program connected to Tixevo.

    The flow is as follows:

    1. When your user chooses to pay with FanPoints, you can use this method to create a payment session.
    2. The payment session has a unique session URL with the checkout form hosted by the loyalty program. Redirect your user to this URL.
    3. The user completes the checkout and is redirected to the given callback URL or cancellation URL.
    4. A request is sent to the webhook URL if provided.

    This flow is preferred over the payPurchaseWithFanPoints method as it allows to properly authenticate the user on the checkout page hosted by the loyalty program.

    Parameters

    • partnerType: TixevoPartnerType

      the type of the Tixevo partner where the purchase happened

    • price: number

      the price of the purchase

    • successUrl: string

      the URL to redirect to if the user completes the payment successfully

    • cancelUrl: string

      the URL to redirect to if the user cancels the payment

    • OptionalwebhookUrl: string

      the URL to send a request to after the payment is completed

    • OptionalcustomPurchaseId: string

      an optional custom purchase id which can be used to link the payment to a specific purchase in your system

    • Optionalcurrency: Currency

      the currency of the price (only needed )

    Returns Promise<{
        amount: number;
        cancelUrl: string;
        currency: Currency;
        customPurchaseId: undefined | string;
        expiryDate: string;
        partnerId: string;
        sessionId: string;
        sessionUrl: string;
        status: FanPointsPaymentSessionStatus;
        successUrl: string;
    }>

    the created session with the session URL

    Throws

    RequestError if the given price is not valid (invalidRewardAmountError), if the given custom purchase id is not valid (invalidTransactionIdError), or if the configured loyalty program is not connected to Tixevo (notConfiguredError).

estimateGivenOutFanPointsOnPurchase

  • estimateGivenOutFanPointsOnPurchase(purchaseItems): Promise<number>

  • Estimates how many Fan Points a user would receive for the given purchase.

    This allows you to check how many Fan Points a user would receive for a given purchase. It does not actually distribute the Fan Points. Use giveFanPointsOnPurchase to distribute Fan Points.

    Parameters

    • purchaseItems: {
          currency?: Currency;
          partnerId?: string;
          partnerLabel?: PartnerLabel;
          price: number;
          rateLabel?: string;
      }[]

      the items that were purchased

    Returns Promise<number>

    the amount of Fan Points the user would receive.

getBalance

  • getBalance(userId): Promise<{
        currency: Currency;
        fanPoints: number;
        monetaryValue: number;
    }>

  • Returns the total number of Fan Points the user has collected.

    Parameters

    • userId: string

      the id of the user.

    Returns Promise<{
        currency: Currency;
        fanPoints: number;
        monetaryValue: number;
    }>

    an object containing the total amount of Fan Points the user has collected as well as the amount that can be purchased with these points.

    Throws

    RequestError if the user does not exist (unknownUserError).

getPriceInFanPoints

  • getPriceInFanPoints(price, partnerId?, partnerLabel?, currency?): Promise<number>

  • Returns the number of Fan Points that correspond to the given price.

    If multiple partners are configured, you can use the partnerId or the partnerLabel parameter to specify the partner where the purchase happens.

    Parameters

    • price: number

      the price in the default currency of the partner or the currency given in the currency parameter

    • OptionalpartnerId: string

      the id of the partner where the purchase happens

    • OptionalpartnerLabel: PartnerLabel

      the label of the partner where the purchase happens

    • Optionalcurrency: Currency

      the currency of the price

    Returns Promise<number>

    the number of Fan Points that correspond to the given price

    Throws

    RequestError if the given price is not valid (InvalidRewardAmountError).

getTransaction

  • getTransaction(userId, purchaseId, partnerId?, partnerLabel?): Promise<{
        purchaseId: string;
        purchaseItems: {
            amount: number;
            currency: Currency;
            date: string;
            description: string;
            hasBeenSettled: boolean;
            hasBeenUndone: boolean;
            partner: {
                branding: {
                    logoUrl: undefined | string;
                };
                description: string;
                name: string;
                website: string;
            };
            partnerId: string;
            price: number;
            purchaseItemId: string;
            rateLabel: undefined | string;
            title: string;
        }[];
        transactionType: FanPointsTransactionType;
        userId: string;
    }>

  • Returns the Fan Points transactions of the given user, purchaseId and partner.

    This method can return both transactions where the user received FanPoints on a purchase and transactions where the user purchased using FanPoints.

    Parameters

    • userId: string

      the id of the user

    • purchaseId: string

      the id of the purchase to return

    • OptionalpartnerId: string

      the id of the partner where the purchase happened

    • OptionalpartnerLabel: PartnerLabel

      the label of the partner where the purchase happened

    Returns Promise<{
        purchaseId: string;
        purchaseItems: {
            amount: number;
            currency: Currency;
            date: string;
            description: string;
            hasBeenSettled: boolean;
            hasBeenUndone: boolean;
            partner: {
                branding: {
                    logoUrl: undefined | string;
                };
                description: string;
                name: string;
                website: string;
            };
            partnerId: string;
            price: number;
            purchaseItemId: string;
            rateLabel: undefined | string;
            title: string;
        }[];
        transactionType: FanPointsTransactionType;
        userId: string;
    }>

    the transaction

getTransactions

  • getTransactions(userId, limit?, earlierThan?): Promise<{
        purchaseId: string;
        purchaseItems: {
            amount: number;
            currency: Currency;
            date: string;
            description: string;
            hasBeenSettled: boolean;
            hasBeenUndone: boolean;
            partner: {
                branding: {
                    logoUrl: undefined | string;
                };
                description: string;
                name: string;
                website: string;
            };
            partnerId: string;
            price: number;
            purchaseItemId: string;
            rateLabel: undefined | string;
            title: string;
        }[];
        transactionType: FanPointsTransactionType;
        userId: string;
    }[]>

  • Returns all Fan Points transactions of the given user at partners.

    The returned transactions contains both transactions where the user received FanPoints on a purchase and transactions where the user purchased using FanPoints.

    If limit is given, at most limit transactions will be returned. If earlierThan is given, only transactions that happened before this transaction will be returned. Combine both parameters to paginate the results.

    Parameters

    • userId: string

      the id of the user

    • Optionallimit: number

      the maximum number of transactions to return

    • OptionalearlierThan: Date

      if given, transactions before this date will be returned

    Returns Promise<{
        purchaseId: string;
        purchaseItems: {
            amount: number;
            currency: Currency;
            date: string;
            description: string;
            hasBeenSettled: boolean;
            hasBeenUndone: boolean;
            partner: {
                branding: {
                    logoUrl: undefined | string;
                };
                description: string;
                name: string;
                website: string;
            };
            partnerId: string;
            price: number;
            purchaseItemId: string;
            rateLabel: undefined | string;
            title: string;
        }[];
        transactionType: FanPointsTransactionType;
        userId: string;
    }[]>

    a list of the transactions.

    Throws

    RequestError if the user does not exist (unknownUserError).

giveFanPointsOnPurchase

  • giveFanPointsOnPurchase(userId, purchaseItems, customPurchaseId?): Promise<{
        purchaseId: string;
        purchaseItems: {
            amount: number;
            currency: Currency;
            date: string;
            description: string;
            hasBeenSettled: boolean;
            hasBeenUndone: boolean;
            partner: {
                branding: {
                    logoUrl: undefined | string;
                };
                description: string;
                name: string;
                website: string;
            };
            partnerId: string;
            price: number;
            purchaseItemId: string;
            rateLabel: undefined | string;
            title: string;
        }[];
        transactionType: FanPointsTransactionType;
        userId: string;
    }[]>

  • Gives Fan Points to the user for the given purchase and purchase items.

    The titles and descriptions can be used to add human readable information on the transaction that could be used to display to the user.

    Each purchase item can correspond at a different partner. If no partner is given, the default partner will be used. You can set the partner using the partnerId or the partnerLabel parameter. If both are given, the partnerId will be used.

    Each purchase item can have a different rate label in order to specify the conversion rate from the price to the number of Fan Points. If no rate label is given, the default rate of the partner will be used.

    A custom purchase id can be given in order to link the transaction to a specific event on your side. This operation is idempotent w.r.t. the purchase group id. This means that if you call this method twice with the same custom group id, the second call will not have any effect and an error will be raised.

    Parameters

    • userId: string

      the id of the user to give FanPoints to

    • purchaseItems: {
          currency?: Currency;
          customPurchaseItemId?: string;
          description: string;
          partnerId?: string;
          partnerLabel?: PartnerLabel;
          price: number;
          rateLabel?: string;
          title: string;
      }[]

      the items that were purchased

    • OptionalcustomPurchaseId: string

      an optional custom purchase id

    Returns Promise<{
        purchaseId: string;
        purchaseItems: {
            amount: number;
            currency: Currency;
            date: string;
            description: string;
            hasBeenSettled: boolean;
            hasBeenUndone: boolean;
            partner: {
                branding: {
                    logoUrl: undefined | string;
                };
                description: string;
                name: string;
                website: string;
            };
            partnerId: string;
            price: number;
            purchaseItemId: string;
            rateLabel: undefined | string;
            title: string;
        }[];
        transactionType: FanPointsTransactionType;
        userId: string;
    }[]>

    a list of the resulting purchase transactions

    Throws

    RequestError if the user does not exist (unknownUserError), if the given price is not valid (invalidRewardAmountError), if the custom purchase id is not valid (invalidTransactionIdError), if a transaction with the given custom purchase id already exists (alreadyExecutedError), if the given custom purchase item ids are not unique (nonUniquePurchaseItemIdsError), or if one of the rate categories does not exist (invalidRateCategoryError).

payPurchaseWithFanPoints

  • payPurchaseWithFanPoints(userId, purchaseItems, customPurchaseId?): Promise<{
        purchaseId: string;
        purchaseItems: {
            amount: number;
            currency: Currency;
            date: string;
            description: string;
            hasBeenSettled: boolean;
            hasBeenUndone: boolean;
            partner: {
                branding: {
                    logoUrl: undefined | string;
                };
                description: string;
                name: string;
                website: string;
            };
            partnerId: string;
            price: number;
            purchaseItemId: string;
            rateLabel: undefined | string;
            title: string;
        }[];
        transactionType: FanPointsTransactionType;
        userId: string;
    }[]>

  • Parameters

    • userId: string

      the id of the user to give FanPoints to

    • purchaseItems: {
          currency?: Currency;
          customPurchaseItemId?: string;
          description: string;
          partnerId?: string;
          partnerLabel?: PartnerLabel;
          price: number;
          title: string;
      }[]

      the items that were purchased

    • OptionalcustomPurchaseId: string

      an optional custom purchase id

    Returns Promise<{
        purchaseId: string;
        purchaseItems: {
            amount: number;
            currency: Currency;
            date: string;
            description: string;
            hasBeenSettled: boolean;
            hasBeenUndone: boolean;
            partner: {
                branding: {
                    logoUrl: undefined | string;
                };
                description: string;
                name: string;
                website: string;
            };
            partnerId: string;
            price: number;
            purchaseItemId: string;
            rateLabel: undefined | string;
            title: string;
        }[];
        transactionType: FanPointsTransactionType;
        userId: string;
    }[]>

    a list of the resulting purchase transactions

    Deprecated

    Allows a user to pay a purchase using FanPoints.

    This method directly performs the payment. It is recommended to use the createFanPointsPaymentSession method for a simpler payment flow, where a payment session is created, where you can redirect the user to a dedicated FanPoints checkout page hosted by the loyalty program. This allows to authenticate the user on the checkout page hosted by the loyalty program.

    The titles and descriptions can be used to add human readable information on the transaction that could be used to display to the user.

    Each purchase item can correspond at a different partner. If no partner is given, the default partner will be used. You can set the partner using the partnerId or the partnerLabel parameter. If both are given, the partnerId will be used.

    A custom purchase id can be given in order to link the transaction to a specific event on your side. This operation is idempotent w.r.t. the purchase group id. This means that if you call this method twice with the same custom group id, the second call will not have any effect and an error will be raised.

    Throws

    RequestError if the user does not exist (unknownUserError), if the user does not have enough FanPoints (tooFewAvailableError), if the given price is not valid (invalidRewardAmountError), if the custom purchase id is not valid (invalidTransactionIdError), if a transaction with the given custom purchase id already exists (alreadyExecutedError), if the given custom purchase item ids are not unique (nonUniquePurchaseItemIdsError), or if one of the rate categories does not exist (invalidRateCategoryError).

registerTixevoCheckout

  • registerTixevoCheckout(jsonPayload): Promise<undefined>

  • Registers a Tixevo checkout.

    This method allows you to register a new or modified raw Tixevo checkout.

    Parameters

    • jsonPayload: string

      The JSON payload of the Tixevo checkout as a string.

    Returns Promise<undefined>

    Throws

    RequestError if the payload is not in the expected format (invalidDataFormatError) or if the Tixevo configuration is not set (tixevoConfigurationNotSetError) in the dashboard.

undoPurchase

  • undoPurchase(userId, purchaseId, purchaseItems): Promise<{
        purchaseId: string;
        purchaseItems: {
            amount: number;
            currency: Currency;
            date: string;
            description: string;
            hasBeenSettled: boolean;
            hasBeenUndone: boolean;
            partner: {
                branding: {
                    logoUrl: undefined | string;
                };
                description: string;
                name: string;
                website: string;
            };
            partnerId: string;
            price: number;
            purchaseItemId: string;
            rateLabel: undefined | string;
            title: string;
        }[];
        transactionType: FanPointsTransactionType;
        userId: string;
    }[]>

  • Undoes a purchase.

    This will reverse the effect of giving out FanPoints or paying with FanPoints.

    The purchaseItems parameter specifies what items of the given purchase (purchaseId) should be undone. You don't have to undo all items of a purchase.

    Note that undoing a purchase might not be possible, e.g. if the FanPoints have already been spent by the user.

    Undoing a purchase corresponds to creating a new purchase with a negative price. This operation is idempotent w.r.t. the purchase id and purchase item id. This means that if you call this method twice with the same arguments, the second call will not have any effect.

    If you configured multiple partners, you can use the specificPartnerId parameter ot the partnerLabel parameter to specify the partner where the purchase happened. If you configured multiple partners and don't provide a specificPartnerId, the default partner will be used.

    Parameters

    • userId: string

      the id of the user that performed the purchase to undo

    • purchaseId: string

      the id of the purchase to undo

    • purchaseItems: {
          partnerLabel?: PartnerLabel;
          purchaseItemId: string;
          specificPartnerId?: string;
      }[]

      the purchase items to undo

    Returns Promise<{
        purchaseId: string;
        purchaseItems: {
            amount: number;
            currency: Currency;
            date: string;
            description: string;
            hasBeenSettled: boolean;
            hasBeenUndone: boolean;
            partner: {
                branding: {
                    logoUrl: undefined | string;
                };
                description: string;
                name: string;
                website: string;
            };
            partnerId: string;
            price: number;
            purchaseItemId: string;
            rateLabel: undefined | string;
            title: string;
        }[];
        transactionType: FanPointsTransactionType;
        userId: string;
    }[]>

    an list of the performed undo purchases

    Throws

    RequestError if the purchase does not exist (transactionNotFoundError), if the user does not have enough FanPoints (tooFewAvailableError), or if the purchase has already been undone (alreadyExecutedError).

Settings

Member Visibility

On This Page

Methods