Payment Allocation details added to Loan Tape API

Overview

For customers using Lithic Credit Products, Lithic is now providing further detail on how repayment is allocated to pay off a credit balance.

The payment_allocation object within the Loan Tape API has been updated to break out each subcategory when repayment hits the Financial Account:

{
  "payment_allocation": {
    "interest": 315,
    "principal": 16925,
    "fees": 750,
    "interest_details": {
      "purchases": 150,
      "cash_advances": 90,
      "balance_transfers": 75
    },
    "principal_details": {
      "purchases": 8925,
      "cash_advances": 3000,
      "balance_transfers": 5000
    },
    "fee_details": {
      "purchases": 350,
      "cash_advances": 300,
      "balance_transfers": 100
    }
  }
}

Payments beyond the minimum payment are allocated in the order configured internally on the Credit Product, in order of highest interest rate -> lowest interest rate.

Customers should work with Lithic Implementations to configure this based on their intended setup.

Details

Lets go through a full example of a statement breakout + repayment allocation, to see how we would get the the allocation shown above. In this example, these are the broken out totals for the period:

{
  "period_totals": {
    "payments": 10000,
    "payment_details": {
      "ACH": {
        "ORIGINATION_CREDIT": 0,
        "ORIGINATION_DEBIT": 10000,
        "RECEIPT_CREDIT": 0,
        "RECEIPT_DEBIT": 0
      },
      "EXTERNAL_PAYMENT": {
        "EXTERNAL_WIRE": {
          "DEPOSIT": 0,
          "WITHDRAWAL": 0
        },
        "EXTERNAL_ACH": {
          "DEPOSIT": 0,
          "WITHDRAWAL": 0
        },
        "EXTERNAL_TRANSFER": {
          "DEPOSIT": 0,
          "WITHDRAWAL": 0
        }
      }
    },
    "purchases": 10000,
    "cash_advances": 3000,
    "balance_transfers": 5000,
    "fees": 750,
    "debits": 750,
    "debits_details": {
      "MANAGEMENT_FEE": {
        "CURRENCY_CONVERSION": 50,
        "LATE_PAYMENT": 200,
        "CASH_ADVANCE_FEE": 300,
        "BALANCE_TRANSFER_FEE": 100,
        "OVERLIMIT_FEE": 100
      }
    },
    "credits": -1000,
    "credits_details": {
      "MANAGEMENT_ADJUSTMENT": {
        "BILLING_ERROR": -300
      },
      "MANAGEMENT_REWARD": {
        "CASH_BACK": -700
      }
    },
    "interest": 315
  }
}

Calculation breakdown by category:

• Purchases
  • $100 in principal
  • $3.50 in fees. From debits_detailswe have:
    • CURRENCY_CONVERSION: $0.50
    • LATE_PAYMENT: $2
    • OVERLIMIT_FEE: $1
  • $1.50 in interest (calculated based on tierAPR)
• Cash Advances
  • $30 in principal
  • $3 in fees from CASH_ADVANCE_FEE
  • $0.90 in interest (calculated based on tier APR)
• Balance transfers
  • $50 in principal
  • $1 in fees from BALANCE_TRANSFER_FEE
  • $0.75 interest (calculated based on tier APR)

For our totals, we have:

• Total Principal: $180 ($100 + $30 + 50)
• Total interest: $3.15 ($1.50 + $0.90 + $0.75)
• Total fees: $7.50 ($3.50 + $3 + $1)

The total due for this period is then $180 + $3.15 + $7.50 = $190.75

We'll assume the $100 ORIGINATION_DEBIT from the period was to pay down a previous balance, so that's irrelevant here.

The next day, we'll say a repayment hits the account, and we can see how the payment_allocation plays out in the Loan Tape API. We'll say in this example that the customer goes ahead and pays only $180, instead of the total amount due of $190.75.

{
  "payment_allocation": {
    "interest": 315,
    "principal": 16925,
    "fees": 750,
    "interest_details": {
      "purchases": 150,
      "cash_advances": 90,
      "balance_transfers": 75
    },
    "principal_details": {
      "purchases": 8925,
      "cash_advances": 3000,
      "balance_transfers": 5000
    },
    "fee_details": {
      "purchases": 350,
      "cash_advances": 300,
      "balance_transfers": 100
    }
  }
}

Payments beyond the minimum payment are waterfall allocated in the order configured internally on the Credit Product, in order of highest interest rate -> lowest interest rate.

Because principal_details.purchases is the subcategory lowest configured APR, that is the amount that does not get fully paid off. Only $89.25 of the $100 is paid off.

Release Timeline

Available now: January 25, 2025. Loan Tapes beginning Jan 8, 2025 should have payment_allocation details fields fully populated

User Impact

No impact, this change is additive only. Learn more about Statements and Loan Tape APIs via our API Reference

If you have any questions or concerns, please contact us via the HELP link in your Lithic Dashboard.

The Lithic changelog has an RSS feed! To monitor for new update announcements, subscribe with your preferred RSS reader.