Loyalty Prepay Accounts: Validation Rules

If any of the below validations fail, the API will return an HTTP-400 error.

Configurations

1. maximum_product_balance: Defines the maximum balance per product that can be held at any point in time.

2. maximum_product_quantity: Defines the maximum quantity per transaction that can be purchased at any point in time.

3. maximum_rolling_purchase_quantity: Defines the maximum amount of fuel allowed to be purchased over the configured rolling_purchase_quantity_days config.

4. rolling_purchase_quantity_days: Defines the number of days to calculate the rolling purchase balance for the maximum_rolling_purchase_quantity.

5. maximum_related_people_per_account: Defines the maximum number of consumers (children) attached to a prepay account.

6. Each product used by prepay must be configured manually in the table [loyalty_prepay_accounts].[PrepayProducts].

Prepay Accounts

When a prepay account is created or updated, the API will validate that:

The Loyalty program exists.
A Loyalty account exists where loyalty_account_code matches the owner_loyalty_account_code_specified, and that the Loyalty account belongs to the specified program.
For each consumer Loyalty account, check that the Loyalty account exists and belongs to the specified program.
That the number of consumers specified is less than or equal to the maximum_related_people_per_account configuration.
Any consumer_loyalty_account is also not the same as the owner code.

Pre-authorisations

When a pre-authorisation is created for an account, the API will validate that:

The Loyalty program exists.
The prepay account exists and belongs to the specified Loyalty program.
The consumer Loyalty account is either the owner of the account or is configured as one of the consumers of the account.
Each of the specified products are configured for prepay.
The quantity is greater than 0.
The balance of the prepay account for each product is greater than or equal to the pre-authorisation quantity.

Once a pre-authorisation has been validated, the API will create a debit against the account using the pre-authorisation code as the reference.

A debit as a result of a preauthorisation will NOT change the Weighted Average Purchase Price (WAPP).

A get will return only non-reversed pre-authorisations.

If a get is requested for a pre-authorisation that is reversed already or expires it will return a 404 error.

Pre-authorisation Reversal

When a pre-authorisation reversal is created for an account, the API will validate that:

The Loyalty program exists.
The pre-authorisation exists.
The pre-authorisation has not been reversed already.
Each of the specified products are configured for prepay.

Once a pre-authorisation has been reversed, the API will create a credit against the account using the pre-authorisation code as the reference.

A credit transaction as a result of a pre-authorisation will NOT change the Weighted Average Purchase Price (WAPP).

Prepay Transactions

When a transaction is created, the API will validate that:

The Loyalty program exists.
A Loyalty account exists where loyalty_account_code matches the owner_loyalty_account_code_specified, and that the Loyalty account belongs to the specified program.
For each consumer Loyalty account, that the Loyalty account exists and belongs to the specified program.
Each of the specified products are configured for prepay.
If a pre-authorisation code is specified, then that pre-authorisation exists for the specified prepay account. The pre-authorisation must not have been reversed already.
The quantity is greater than 0.
The transaction_value is specified.
The prepay account has not purchased more than the maximum allowable quantity of the product in the previous 12-month period, as defined by the maximum_rolling_purchase_quantity config, i.e. the current value plus the value of the transaction should not exceed the value of maximum_rolling_purchase_quantity.
The new balance_quantity is less than or equal to the maximum_product_balance configuration.
The new balance_quantity is less than or equal to the maximum_product_quantity configuration.
A debit transaction does not cause the balance_quantity to fall below 0.
If the transaction is a debit which isn’t a pre-authorisation, the standard_unit_selling_price is specified.

When a transaction is created, the API will update the balance of the prepay account for each product.

If the transaction type is credit, then:

1. The balance_quantity will be set to balance_quantity + transaction quantity.

2. If the credit is because of a pre-authorisation reversal then reverse the pre-authorisation.

3. last_transaction_date will be set to transaction_date.

4. If the credit is NOT due to a pre-authorisation reversal then the following steps will occur:

Recalculate the WAAP based on the following rules: if the current balance is <> 0 then the weighted_average_purchase_price will be set to ((weighted_average_purchase_price * balance_quantity) + transaction_value) / (balance_quantity + transaction quantity). Otherwise, if the current balance = 0 then weighted_average_purchase_price will be set to (transaction_value) / transaction quantity).
last_purchase_price will be set to transaction_value / transaction quantity.

If the transaction type is debit, then:

1. If transaction_value is 0, keep the transaction_value as zero.

2. balance_quantity will be set to balance_quantity - transaction quantity.

3. The current balance must be greater than zero, and must be greater than the amount of the transaction. This is to ensure the balance never goes below zero. If this validation fails the API should return an "Insufficient balance available" error.

If a pre-authorisation code is included in the request: balance + pre-authorisation quantity must be greater than or equal to transaction quantity.
If a pre-authorisation code is NOT included in the request: balance must be greater than or equal to transaction quantity.

4. If the debit transaction is NOT due to a pre-authorisation then the following steps will occur:

weighted_average_purchase_price will be set to ((weighted_average_purchase_price * balance_quantity) - transaction_value) / (balance_quantity - transaction quantity).
last_purchase_price will be set to transaction_value / transaction quantity.