💸 Settlements

What is a settlement in Livble's jargon?

Metadata of a payment FROM Livble TO the tenant portal on behalf of a tenant

📘

Please read Flow of Funds page before this page

Why do we need settlements?

You (tenant portal) will be debiting Livble's account each time a tenant splits rent with Livble. In order to maintain your current workflow, Livble does not want to ACH credit the recipient's account. Therefore, we create a settlement object, that informs you (tenant portal) how much to debit Livble. This way you (tenant portal) can debit said amount and mark the tenant's ledger accordingly.

Settlement lifecycle

A settlement is created after a tenant finishes the split rent flow.

The settlement object

When/What to do with a settlement record?

Settlements can be retrieved and updated with PATCH/GET /payment/settlements/<id> endpoint

Settlement webhooks

📘

Please read the Webhooks section before

When a tenant splits rent, a settlement record in the UNSETTLED status will be created for that tenant. Livble will fire a webhook to the configured endpoint in order to inform you about a user having a new settlement record.

Implementing the settlement webhook is required since a tenant could be splitting rent through the Livble app after the 1st month of use

{ 
    "settlement_id": int,
    "amount": int, // amount paid in cents
    "charges_paid": string[],
    "charges_and_amounts_paid": {
        charge_id: string,
        amount_in_cents: int
    }[],
    "external_id": string
}

When receiving this webhook you should:

1. Call GET /payments/settlement/one?settlement_id=<settlement_id> and make sure the settlement is UNSETTLED. If the settlement is already in another status, you can drop the webhook process.
2. Initiate an ACH debit to Lvble's disbursement's account directed to the tenant portal's recipient account.
3. Call PATCH /payments/settlements/<id> in order to mark the settlement as UNVERIFIED

🚧

Make sure to always check a settlement has not already been initiated before creating a transaction with your processor

Failed settlements treatment

Transactions should not fail.

There are 2 types of failures:

1. Transactions that didn't go into ACH network

   1. These can be for example a case where your processor has some internal error. In these cases, please don't update the settlement to be UNVERIFIED and instead retry the transaction whenever possible. After you manage to get that transaction into the network update the settlement to be in UNVERIFIED state.

2. Transactions that did go into ACH network and fail

   1. In these cases (R01, R08, etc.) we will want to investigate why this happened. Please do mark the settlement as FAILED. We will monitor that behavior and investigate it. Once we have a solution for that, we will set the settlements back to UNSETTLED and update you, so you reinitiate those transactions.

📘

Build a batch process to settle all transactions in UNSETTLED status

⏰ Callback vs Webhook timing

As explained earlier, when a split rent happens, Livble will fire both a callback to the onEvent function and a webhook to your configured endpoint. The callback event will be invoked immediately whereas the webhook will fire 60 seconds after the callback.

The reason for this delay is the fact that we want our partners to take care of the settlement from the callback trigger. This will allow you to provide the best UI experience to your tenants by providing immediate feedback to the UI where they initiated the payment. You can show some confirmation, update the balance, refresh the page or any action you would take when a non-Livble payment is done.

The webhook will be shot 60 seconds later. This will give us another layer of protection in case the callback or its treatment has been lost on their way. In most of the cases in which the split rent event happens from within the Livble Experience, (i.e: hosted within your platform) the webhook will arrive and the settlement will already be in a UNVERIFIED state. In that case you can just respond with 200 and drop the handling. In case the status is UNSETTLED you will have to handle the settlement.

For payments being initiated from the Livble mobile app or Livble AutoPay the callback will be the only trigger.