settlement.created webhook

📘

Please read the Webhooks section before

Overview

For our partners, it is required to implement a the settlement.created webhook to efficiently manage rent settlements when a tenant splits rent. This is crucial for maintaining accurate and up-to-date records of rent settlements in the UNSETTLED status.

How It Works

Whenever a tenant splits rent, Livble will create a settlement record in the UNSETTLED status for that tenant. To ensure partners are immediately informed about new settlement records, Livble will trigger a webhook to the partner's configured endpoint. This webhook carries essential details about the settlement that partners need to process.

Webhook Payload

The webhook will send the following payload to your configured endpoint:

{
    "settlement_id": int, // Unique identifier for the settlement
    "amount": int, // Amount paid, in cents
    "charges_paid": string[], // Array of charges that were paid
    "external_id": string // External identifier for cross-referencing
    "charges_and_amounts_paid": {
        charge_id: string,
        amount_in_cents: int
    }[]
}

Required Actions Upon Receiving the Webhook

Upon receiving this webhook, partners are required to:

1. Verify Settlement Status: Call GET /payments/settlement/one?settlement_id=<settlement_id> to retrieve the settlement record. Ensure that the settlement status is UNSETTLED.

2. Initiate ACH Debit: Based on the information retrieved, initiate an ACH debit to Lvble's disbursement account. This amount should then be directed to the tenant portal's recipient account, facilitating the settlement process.

3. Update Settlement Status: After initiating the ACH debit, call PATCH /payments/settlements/<id> with the appropriate settlement ID to update the settlement status to UNVERIFIED. This confirms that the process to settle the amount is underway.

Implementation Requirement

Implementing this webhook is mandatory for all Lvble partners. This ensures timely and accurate processing of rent settlements, enhancing the efficiency of our collective operations. Failure to implement this webhook as per the guidelines may result in discrepancies in settlement records and could impact the services provided to tenants.

Support

For any questions or assistance with implementing the webhook, please reach out to our partner support team. We are here to help ensure a smooth integration process.