Paylink Adjustments Model

The Adjustments model is designed to enable dynamic modifications to the base amount of a transaction, such as applying surcharges or discounts. These adjustments are driven by specific business rules, allowing you to customise the final transaction amount based on various conditions, including payment timing, discount codes, or promotional periods.

This guide provides an overview of the key elements within the model, example use cases, and guidance on how to structure the adjustments in your API requests.

Key Components of the Adjustments Model

adjustment (string) Defines the type of adjustment, with valid values being: surcharge: Adds an extra charge to the base amount. discount: Subtracts an amount or percentage from the base amount.

amount (integer) Specifies a fixed amount for surcharges or discounts, defined in the smallest currency unit (e.g., pence for GBP). If both amount and percentage are specified, the amount will take precedence.

percentage (double) For percentage-based adjustments, this specifies the percentage to be added or subtracted.

conditions (AdjustmentCondition) Defines the specific conditions under which the adjustment applies. These conditions can be based on key events such as the creation or due date of the transaction, or specific date ranges for promotional offers.

accumulate (string) Determines how adjustments are applied when multiple adjustments are present. The following accumulation modes are available:

  • None (default): Only the last applicable adjustment is applied. Previous adjustments are ignored.
  • AccumulateBase: Each adjustment is applied independently to the original base amount, and their effects are combined.
  • AccumulatePrevious: Adjustments are applied in sequence, with each one building on the previous adjustment's result.
  • AccumulateBaseOver: Compares the effect of applying an adjustment to the base amount with the result of accumulated adjustments. The system will apply whichever results in the higher final amount.

Example Use Cases

Use Case 1: Late Payment Surcharge

A business wishes to charge a late payment fee of £10 if the payment is made 7 days after the due date. In this example:

  • The adjustment is a fixed surcharge of £10.
  • It is applied 7 days after the due date.
  • Only the late payment surcharge is considered (no accumulation).

Use Case 1: Late Payment Surcharge

{
    "adjustment": "surcharge",
    "amount": 1000,
    "description": "£10 Late Payment Fee applied 7 days after the due date",
    "conditions": {
    "anchor": "after_due_date",
    "duration": 7
}
}

Use Case 2: Early Payment Discount

A business offers a 5% discount if the customer pays 5 days before the due date.

In this example:

  • A 5% discount is applied.
  • It is triggered 5 days before the due date.
  • The AccumulateBase mode ensures that the discount is applied independently of other adjustments.

Use Case 2: Early Payment Discount

{
    "adjustment": "discount",
    "percentage": 5.0,
    "description": "5% discount for early payments made 5 days before the due date",
    "conditions": {
    "anchor": "before_due_date",
    "duration": 5
},
    "accumulate": "AccumulateBase"
}

Use Case 3: Promotional Discount Code

A business runs a September promotion offering 15% off for orders made within September, requiring the discount code SEP24.

In this example:

  • A 15% discount applies only within the promotional period (1st to 30th September).
  • The customer must enter the discount code SEP24.
  • The AccumulatePrevious mode allows this discount to be combined with other previous adjustments.

Use Case 3: Promotional Discount Code

{
    "adjustment": "discount",
    "percentage": 15.0,
    "description": "15% promotional discount for September with code SEP24",
    "conditions": {
    "anchor": "custom",
    "start_date": "2024-09-01",
    "end_date": "2024-09-30",
    "discount_code": "SEP24"
},
    "accumulate": "AccumulatePrevious"
}

Use Case 4: Accumulating Surcharge and Percentage Discount

A £10 surcharge is applied for late payments 7 days after the due date, and a 15% discount applies for payments made 5 days before the due date.

In this example:

  • The £10 surcharge applies 7 days after the due date.
  • A 15% discount is available for payments made 5 days before the due date.
  • Both adjustments are applied to the base amount, and their effects are combined using the AccumulateBase mode.

Use Case 4: Accumulating Surcharge and Percentage Discount

{
    "adjustment": "surcharge",
    "amount": 1000,
    "description": "£10 late payment fee",
    "conditions": {
    "anchor": "after_due_date",
    "duration": 7
},
    "accumulate": "AccumulateBase"
},
{
    "adjustment": "discount",
    "percentage": 15.0,
    "description": "15% discount for early payments",
    "conditions": {
    "anchor": "before_due_date",
    "duration": 5
},
    "accumulate": "AccumulateBase"
}

Best Practices

  1. Accurate Anchoring: Ensure that the anchor points (such as after_due_date or before_expiry) are accurately defined to trigger the adjustments at the correct time.
  2. Combining Adjustments: Use the accumulate field strategically to control how adjustments are combined. If you need to ensure that only one adjustment is applied, use the None accumulation mode.
  3. Clear Descriptions: Provide clear and concise descriptions for each adjustment. This will help both developers and business users understand the purpose of the adjustment.
  4. Handling Promotions: For promotions, use discount_code in combination with start_date and end_date to ensure discounts are applied only during the valid period and require the correct code.

The Adjustments model provides a flexible and powerful way to dynamically modify transaction amounts based on business rules, customer incentives, and promotions. By leveraging conditions and accumulation modes, developers can build robust logic for calculating final transaction amounts, ensuring accurate and transparent billing for customers.