—
–
/

to search

Reading time — 6 minutes

Edit this page ↗

#Settlement object

The Setu bill object can optionally contain instructions on how to settle a collected bill amount, as part of the settlement object shown in the sample code snippet.

The settlement object contains the following details—

  1. Which bank account(s) the settlement should be deposited to.
  2. What is the split applied on the amount when making the settlement.
"data" : {
    "customer": {
        "name": "Shailesh"
    },
    "billDetails" : {
        "billFetchStatus" : "AVAILABLE",
        "bills" : [
            {
                "generatedOn"       : "2020-06-04T06:59:04Z" // bill generation / fee start date, 
                "dueDate"           : "2020-06-04T06:59:04Z" // last date for fee payment,  
                "recurrence"        : "ONE_TIME",  
                "amountExactness"   : "EXACT", 
                "billerBillID"      : "string",  // bill identifier, sent with each payment
                "customerAccount"   : {},
                "amount"            : {}, //amount against the bill
                "items"             : [], // array of line items
                "aggregates"        : {}, // details on final amount that the customer needs to pay
                "settlement"        : {
                    // details about the settlement instructions for this bill
                     "primaryAccount" : {},
                     "parts" : []
                } 
            }
        ]
    }
}

#When to use the settlement object

The common use cases for utilising the settlement object have been elaborated below.

This is an optional parameter. If the settlement object is not present in bill object, we will settle the full amount to the primary bank account set as part of the merchant configuration on The Bridge.

Case 1 — Redirect entire funds to a different account

A primary account is where the entire funds are settled to by default, in the absence of any settlement instructions. Exactly 1 account can be marked as primary on The Bridge.

In the event you would like to redirect the funds away from this account, you can specify the preferred settlement account as the primaryAccount inside the settlement object. This specifies the settlement account to be changed only for this bill, other settlements will continue to happen to your primary account.

The account you specify as primary in the settlement object has to be one of the accounts already marked as CERTIFIED on The Bridge. Otherwise, the settlement would fail.

Case 2 — Split funds into different accounts

Some business use cases require a bill to be split and settled to multiple bank accounts. Some examples could be—

  1. Different collection accounts for different heads
  2. Different line items belong to different parts of the organization (departments, sub organizations, business entities, etc)
  3. Splits to vendor/partner accounts

We support upto 5 splits on a single bill.


Setu supports this using the settlement object in the merchant’s fetch API, so that the merchant can pass on their bill settlement preference to us, and Setu can take care of settlement scenarios.

Splits work only if amountExactness is set to EXACT or EXACT_UP , ie, the customer can pay the exact bill amount or more. In case paid amount is more than bill amount, the extra money will be settled to the primary account specified in the settlement object.

#Settlement object structure

The settlement JSON object consists of 2 objects—

  • parts—contains the split rules for settlement
  • primaryAccount—money is transferred to this account after all splits have been settled
{
    "settlement" : {
        "parts"          : [],
        "primaryAccount" : {},
    },
}
Parts

Parts is an array of objects that defines the split and account to which that split should be settled.

"parts" : [
    {
        "account" : {
            "id"   : "string",
            "ifsc" : "string",
            "name" : "string"   //optional
        },
        "split" : {
            "unit" : "INR",
            "value": int, // in paise
        }
        "remarks"   : "string"   //optional
    }
]

Descriptions

  • account.id Bank account number for the settlement of this particular split
  • account.ifsc Bank IFSC for the settlement of desired split part
  • account.name Name that appears against the bank account account
  • split.unit Unit by which the split part is calculated. The supported value is INR or Indian National Rupee.
  • split.value Value of the split relative to the mentioned unit, INR accepts integer values and treats them as amount in paise. Please note that we expect only values converted to paise, for simplicity of calculations.
  • remarks Description of the split that will appear in the settlement report.
Primary account

Primary account is an account object which defines the bank account where the balance amount is settled after calculating and settling all the splits. Here is what it looks like.

"primaryAccount" : {
        "id"   : "string",
        "ifsc" : "string",
        "name" : "string"   //optional
    }
}

Only one bank account can be specified here, otherwise the settlement will be rejected.


Descriptions

  • account.id Bank account number for the primary account
  • account.ifsc Bank IFSC for the primary account
  • account.name Name against primary account. This is optional.

#Split calculation method

Setu always start calculating the splits by secondary accounts, that is, accounts that are not marked as primaryAccount in the settlement object. Based on the following descriptions, you can set your business logic to allow for proper splits that are accepted by Setu.

Split by fixed amount value(s)

Enter the exact amount of the split(s) in paise. The total of split parts should either add up to the total bill settlement amount or be less than that.

In case of the latter, we will calculate the difference between the two and settle the difference to the account marked as primaryAccount in the settlement object.

Settlement will be rejected in case the total of splits exceeds the bill settlement amount.


Example scenario— For a bill of ₹100, a merchant wants ₹20 for itself and the remaining balance has to be settled to a vendor bank account. For this scenario, the settlement object would look like—

{
    "primaryAccount" : {
        "account"   : {
            "id"   : "vendor-bank-account-number",
            "ifsc" : "vendor-bank-ac-ifsc"
        }
      },
      "parts" : [
            {
                "account" : {
                    "id"   : "biller-bank-ac-number",
                    "ifsc" : "biller-bank-ac-ifsc"
                },
                "split" : {
                    "unit"  : "INR",
                    "value" : 2000 // in paise
                }
           }
       ]
}
Split settlement example

Take the following scenario—

Amount to settle: 200000 (₹2000), which is the amount actually paid by customer, in paise

{
    "primaryAccount" : {
        "account" : {
            "id"   : "TUITION-FEE-ACCOUNT",
            "ifsc" : "string"
        }
    },
    "parts" : [
        {
            "account" : {
                "id"   : "BUS_FEE_ACCOUNT",
                "ifsc" : "string"
            },
            "split" : {
                "value" : 60000,
                "unit"  : "INR"
            },
            "remarks" : "Sports fee"
        },
        {
            "account" : {
                "id"   : "SPORTS-FEE-ACCOUNT",
                "ifsc" : "string"
            },
            "split" : {
                "value": 40000,
                "unit" : "INR"
            },
            "remarks" : "Sports fee"
        }
    ]
}

The resulting settlement happens as follows, with the values in paise—

  1. ₹600 for the bus fee account: 60000
  2. ₹400 for the sports fee account: 40000
  3. Balance of ₹1000 for the tuition fee account: 100000

Was this page helpful?