How to integrate Reconciliation to your payment flow

Overview

Once you have integrated Lean’s Payments API in your application, it is easy to extend the functionality of the integration to be notified when a payment is settled in your bank account. This guide will help you use our reconciliation services to notify your system when payments made through the Lean platform have been received by your bank account. For efficient reconciliation, it is highly recommended that you use the description field when creating a payment intent . The description is what Lean will use as the payment reference when submitting a payment and this value will often show in the receiving bank account as part of the transaction description for the corresponding deposit. The description value used should be 12 characters or less, should be unique for each payment and it should be stored against the payment object you create within your own system to represent the payment.

How is a payment marked as reconciled?

When a payment is initiated through Lean and the bank communicates that the status of that payment is either ACCEPTED_BY_BANK or PENDING, Lean will create a Reconciliation object for the payment with attributes such as status, reference, amount and currency. The reconciliation.status for all payments will start as OUTSTANDING to suggest that the payment has not yet been received by the destination bank account. As a result, the reconciliation workflow begins, with three different modalities that will allow the payment to be marked as reconciled.

📘

The status attribute of the payment object will not change as a result of any reconciliation workflow and will stay as ACCEPTED_BY_BANK or PENDING. The reconciliation.status is what determines if the payment has been reconciled or not.

❗️

Attention!

Lean's reconciliation product currently supports reconciling payments for only one destination account. That means that, if you receive payments into multiple bank accounts, you will need to select one to use with reconciliation. Also, if you receive payments in more than one sub account within your bank account (e.g.: one in AED and another in USD), you will need to select only one of those.

1. Manual reconciliation

You can reconcile payments by using the reconciliation tab on the application dashboard. The reconciliation tab shows a list of all payments that were made by Lean that have been marked as ACCEPTED_BY_BANK or PENDING and allows you to filter by variables such as date, bank and amount. This view will also give you important information to help reconcile payments against your bank statement such as transaction references and bank confirmation numbers that will show up in the description field of your bank statement. Here you will need to look through your bank statement for a deposit that matches the payment. When you find the matching deposit, you simply mark the payment as reconciled with the option to add a reconciliation reference. We suggest you use your bank's identifier for the matching deposit as your reconciliation reference. You have the option to either reconcile payments individually or in batches.

2. Partial auto reconciliation

You have the option of connecting your bank account to the platform using Lean's direct connections or uploading CSVs of your bank statements.

Once your bank is connected or bank statement is uploaded, Lean will retrieve the deposits and match them to payments made through the payments product. The reconciliation service will use a combination of transaction references, confirmation codes, account information, dates and transfer amounts to accurately and instantly match Lean payments to the deposits imported from the destination bank account. Each payment will either be uniquely matched, partially matched or not matched to the bank deposits.

You will be able to configure if you would like Lean to automatically mark uniquely matched payments as reconciled upon import or if you would like to manually confirm the matching payments and deposits before marking all as reconciled.

Every time you want to import new deposits you will need to upload a new CSV or refresh the connection with the bank.

3. Auto reconciliation

You also have the option of allowing Lean to continuously fetch the deposits from your bank account without your intervention.

❗️

Attention!

Not all banks are supported for auto reconciliation. Please let your Lean point of contact know which bank you use and they will be able to let you know if auto reconciliation is supported.

What happens when a payment is reconciled?

When a payment is marked as reconciled, either manually or automatically, a webhook of type payment.reconciliation.updated will be sent to the webhook URL you have configured through the application dashboard.

Handle the reconciliation updated webhook

You will need to configure your system to handle the payment.reconciliation.updated webhook. The payload of the object represents the reconciliation object that belongs to the payment object that was reconciled. The status shown in the payload is different from the status of the payment object - which will remain as the status returned to Lean by the bank upon payment initiation. The reconciliation status of a reconciled payment will be RECONCILED.

{
    "payload": {
        "payment_id": "5ca5b15c-33d5-437f-b2cb-03e48586b8f8",
        "payment_intent_id": "0ddd6590-3f7f-4c62-902f-18e6560c443c",
        "payment_description": "1b180ef839f4",
        "status": "RECONCILED",
        "reference": "ENBD/100218532",
        "amount": 1500.00,
        "currency": "AED"
    },
    "type": "payment.reconciliation.updated",
    "message": "A payment reconciliation object has been updated.",
    "timestamp": "2022-06-22T14:06:13.375317Z",
    "event_id": "2d72dfe2-8306-491c-be83-b4fe278e4081"
}

Like all webhooks with Lean, upon receipt, your system should respond with a 200 to acknowledge receipt. The payload will give you the payment.id and the payment_intent_id to help you identify the payment with the Lean created payment or payment intent object. If you have used an internal identifier for the payment_intent.description you will also be able to match the payment with the payment_description field from within the webhook.

📘

The amount in the payload may not match the amount of the payment you configured, this is because there are scenarios where the amount received is slightly below the amount specified. The amount associated with the payment object (payment.amount) will reflect the amount of the payment configured whereas the amount associated with the payment.reconciliation object (payment.reconciliation.amount) will reflect the amount that was received in your bank account.

What happens when a payment is not received?

In the rare circumstance that a payment made through the Lean platform is not received in the intended bank account, you will have the option to mark a payment as unreceived.

When a payment is marked as UNRECEIVED you will receive a similar payment.reconciliation.updated webhook where the status will be marked as UNRECEIVED. You should handle this situation appropriately within your system.

{
    "payload": {
        "payment_id": "7eeb8b76-17d8-408b-995a-84a7847885f0",
        "payment_intent_id": "ba03048e-cbfb-4e51-87b8-01ba77d55d0b",
        "payment_description": "ae5fd7d6db0e",
        "status": "UNRECEIVED"
    },
    "type": "payment.reconciliation.updated",
    "message": "A payment reconciliation object has been updated.",
    "timestamp": "2022-06-22T14:03:08.602434Z",
    "event_id": "160249de-0fa7-4917-8c2d-62a59acadf22"
}

What happens if you mistakenly mark a payment as reconciled or unreceived?

There are instances when a payment is mistakenly marked as RECONCILED or UNRECEIVED. In this scenario you will have the option to essentially undo this by manually marking the payment in question as OUTSTANDING.

When this happens, you will receive a payment.reconciliation.updated webhook to notify you that the payment has been marked as OUTSTANDING. You should ensure that your system handles this webhook and the scenario where a payment has been moved back from RECONCILED or UNRECEIVED to OUTSTANDING. This might require you to undo business logic that was performed as a result of being notified of the initial status change.

{
    "payload": {
        "payment_id": "8bfa816c-1c23-4ae4-abaf-2d1b28f86e43",
        "payment_intent_id": "d1378506-855b-4f4a-8861-dad707f8c52b",
        "payment_description": "8b7cac57d130",
        "status": "OUTSTANDING"
    },
    "type": "payment.reconciliation.updated",
    "message": "A payment reconciliation object has been updated.",
    "timestamp": "2022-06-22T11:17:10.837412Z",
    "event_id": "8c4ce46c-abc7-4d43-aad0-0b1f2f692ef9"
}

Additionally you should handle the instances when the payment is then later moved to either RECONCILED or UNRECEIVED.

How can I check the reconciliation status of a payment?

Lean provides two reconciliation endpoints:

1. an endpoint to get the reconciliation details for an individual payment (see Get payment API reference)
2. an endpoint to retrieve a list of payments with their reconciliation details (see Get list of payments API reference)

How do I get setup with reconciliation?

As soon as you can, reach out to your Lean point of contact to tell them you are interested in using reconciliation. Your Lean point of contact will set up a call between your team and Lean's team to discuss with you how to get set up.