Important Notice: This document is intended for integrators who manage their own credits and handle their own sale and credit transactions.

Please Note: If you are an integrator for whom Pebble manages credits, be advised that including the sourceOfFunds parameter in your sale transactions will disrupt the credit handling process. This may lead to transaction errors or improper credit allocation.

Overview

The sourceOfFunds parameter makes it easier for integrators to handle sales and credit transactions by specifying how much of a transaction is sourced from particular credit purses. It automates credit purse creation and credit transactions, minimising manual setup and ensuring accurate data synchronisation.

Purpose

The feature is designed for integrators who want to manage credits themselves. By specifying the source of funds for transactions, integrators can: Streamline purse and credit management. Automatically create necessary credit purses and transactions without additional configuration. Avoid potential errors associated with manual purse and credit creation.

Scope

This documentation explains the sourceOfFunds parameter:

• Its role in sales and credit transactions.
• Guidelines for implementation.
• Behavioral expectations for different scenarios, such as missing or excess source values.
• Integration considerations, including refunds and error handling.

Description

Feature Functionality

The sourceOfFunds parameter allows integrators to specify:

• The name of the credit purse (e.g., "Free School Meals").
• The amount of the transaction attributed to that purse.

Key functions:

1. Automatic Credit Purse Creation:
   • If a specified purse does not exist, Trac automatically creates it.
   • Credit transactions are logged against this purse.
2. Handling of Default Purses:
   • If no source of funds is specified, the transaction amount is deducted from the default purse.
3. Excess Funds Handling:
   • If the total amount specified in the source of funds exceeds the transaction amount, excess values are ignored. No additional credits are created beyond the sale amount.
4. Refunds:
   • For refunds, including the sourceOfFunds parameter creates negative credit transactions, effectively reversing the credits spent.

Sale example:

Here is an example of sourceOfFunds usage, for a sale that is worth £10, where £2.50 of the sale was covered by credit (in this case Free School Meals):

{
    "amount": "-10.00",
    "transactionDate": "2004-10-11T12:24:12Z",
    "type": "sale",
    "sourceOfFunds": {
        "free school meals": {
            "amount": "2.50"
        }
    },
    "till": {
        "salePayments": {
            "ACCOUNT": {
                "paymentTotal": "10.00"
            }
        },
        "paymentMethods": [
            "ACCOUNT"
        ]
    }
}

When this transaction is sent to Trac, Trac will get or create a credit purse with the title “Free School Meals”, and the ID free-school-meals.

After getting the purse, a credit transaction of £2.50 is created against it but the balance for that purse will remain at 0. £7.50 is then taken from the default purse to cover the rest of this sale.

Refunds example

sourceOfFunds can also be set on refunds. Refunding the sale example above would look like this:

{
    "amount": "10.00",
    "transactionDate": "2004-10-11T12:24:12Z",
    "type": "sale",
    "sourceOfFunds": {
        "free school meals": {
            "amount": "2.50"
        }
    },
    "till": {
        "salePayments": {
            "ACCOUNT": {
                "paymentTotal": "10.00"
            }
        },
        "paymentMethods": [
            "ACCOUNT"
        ]
    }
}

Note the positive value for amount. This means that £7.50 will be given back to the default purse, a credit transaction of -2.50 will be created to reverse the credit spend.

Implementation

Configuration

Input Requirements:

• Add the sourceOfFunds parameter for each transaction.
• Specify:
  • Purse Name: Name of the purse (e.g., "Free School Meals").
  • Amount: The amount attributed to the purse.

Restrictions:

Do not create credit purses or credit transactions manually when using this feature. Doing so may cause conflicts and system errors.

Error Handling:

• If the combined sourceOfFunds values exceed the transaction amount, credit transactions will be created only up to the transaction amount. Any additional credits beyond that amount will not be applied but will still be recorded in the sourceOfFunds field for that transaction.
• Missing sourceOfFunds will default the entire transaction to the default purse.

Risks and Mitigations

Excess Allocation:

If the sum of source amounts exceeds the transaction amount, the system ignores the excess without detailed reporting.

Manual Purse and Credit Creation Conflicts:

Creating purses or credits manually when using sourceOfFunds can lead to duplication or errors. Therefore, it’s advised not to add them manually.