Charge Based Portal Guide
Before You Begin
Review the API reference for the
/portal_infoendpoint: (See here).Review the
leaseobject overview: (See here)Ensure your portal is classified as a "Charge-Based" portal.
Not sure? Check the Determine Your Portal Type section.
❓What This Guide Covers
This guide outlines how to format the /portal_info request body for Charge-Based portals, structured as follows:
- Example Breakdown – Understand how fields are derived from a sample Charge-Based portal.
- Key Considerations – Important notes on formatting the request body for Charge-Based portals.
- Full Request Payload – A complete JSON representation of a properly structured request body.
🖼️ Example Portal Breakdown
This section demonstrates how to derive /portal_info request fields from an existing tenant portal.
In the next section, we will explain key aspects specific to Charge-Based portals in more detail.
Below is a sample portal modeled after a typical Charge-Based system.
🖱 Click on any item to see how it maps to the /portal_info request payload.
How it looks in /portal_info body:
lease.charges[{{chargeIndex}}] = {
// The unique ID of the charge in your system.
"id": "charge-id-{{chargeIndex}}",
// The due date of the charge.
"due_date": "{{chargeDueDate}} 00:00:00",
// The charge description in your system.
"description": "{{chargeName}}",
// The charge amount in cents.
"original_amount_in_cents": {{chargeAmountInCents}},
// This charge was not paid, so 0 is passed here.
"amount_paid_in_cents": 0,
//{{appliedToOpenBalanceComment}}
"has_been_applied_to_open_balance": {{appliedToOpenBalance}}
}
{{chargeName}}
So it must be passed both in
charges and in historical_payments.Click below to see how it looks in each list:
historical_payments
charges
lease.historical_payments[{{historicalPaymentIndex}}] = {
// The unique ID of the payment in your system.
"id": "historical-payment-id-{{historicalPaymentIndex}}",
// The date the payment was made.
"payment_date": "{{chargeDueDate}}",
// The amount paid in cents.
"amount_in_cents": {{historicalPaymentAmountInCents}},
// The payment method used.
"payment_method": "CreditCard",
// The status of the payment.
"payment_status": "completed",
}
lease.charges[{{chargeIndex}}] = {
// The unique ID of the charge in your system.
"id": "charge-id-{{chargeIndex}}",
// The due date of the charge.
"due_date": "{{chargeDueDate}}",
// The charge description in your system.
"description": "{{chargeName}}",
// The charge amount in cents.
"original_amount_in_cents": {{historicalPaymentAmountInCents}},
// This charge was paid in full, so we pass the original amount.
"amount_paid_in_cents": {{historicalPaymentAmountInCents}},
// Because this is a past charge, it means it was applied to the open balance in the past.
"has_been_applied_to_open_balance": true
}
{{chargeName}}
lease.open_balance = 105000
Balance Breakdown:
+ 2025-03-01 Rent
+ 1000.00$
- 2025-03-01 Rent (Payment)
- 1000.00$
+ 2025-03-01 Utility Charges
+ 50.00$
- 2025-03-01 Utility Charges (Payment)
- 50.00$
+ 2025-04-01 Rent
+ 1000.00$
+ 2025-04-01 Utility Charges
+ 50.00$
Open Balance:
+ 1050.00$
Notes:
- The rent charge from
2025-05-01is a future charge, and it was not applied to the open balance. - The "Pay" button doesn't do anything. (It's for demo purposes)
$1,050.00
Current Open Balance (Includes past due)
📌 The following example portal presents a snapshot from 2025-04-01.
💡 The date format is as follows: YYYY-MM-DD
💳 Select Charges to Pay
📜 Payment History
🔑 Key Considerations
In this section, we cover key considerations for Charge-Based portals when structuring the /portal_info request.
💡charge.has_been_applied_to_open_balance
charge.has_been_applied_to_open_balanceThis field indicates whether the charge was ever added to the open_balance.
📌 Example in the Sample Portal:
All charges in the Sample Portal were applied to the open balance, except the upcoming charge.
Click on any charge in the example to see how this field is populated.
💡 lease.open_balance
lease.open_balanceThe tenant's current open balance for the lease in cents.
🧮 How It's Calculated in the Sample Portal:
In the Sample Portal, this value is calculated like so: SUM(applied_charges) – SUM(historical_payments)
Click on the open balance in the Sample Portal above to see a detailed breakdown.
⚠️ Ensure Consistency with Your Portal:
Even if your calculation differs from the Sample Portal example,
this value must always match the number the tenant sees in your portal.
💡 charge.amount_paid_in_cents
charge.amount_paid_in_centsThe amount paid specifically for this charge (in cents).
❓How to Populate This Field:
- Unpaid charges → Pass
0 - Fully paid charges → Pass the charge’s
original_amount_in_cents - Partial payments (if supported by your portal) → Pass the partial amount paid.
📌Example in the Sample Portal:
Click on any charge from the Sample Portal above to see how this field was populated:
- For the unpaid charges in the "💳 Select Charges to Pay" section →
0is passed. - For the fully paid charges in the "📜 Payment History" section → the charge's
original_amount_in_centsis passed.
📦 Full Request Payload
Below you can find an example for a full /portal_info request payload.
The data in the request matches the information from the example portal shown above.
Updated 5 months ago