- Its typical for MFIs to add extra costs for their financial - products. There are typically Fees or Penalties. -
-Charges is what we use to model both fees and penalties. - For now charges can only be associated with loan products / loans.
-Field Descriptions |
- |||||||||||||||||||||||||||
| name | -|||||||||||||||||||||||||||
| Name associated with this charge. | -|||||||||||||||||||||||||||
| active | -|||||||||||||||||||||||||||
| Boolean flag determines if the Charge is currently active. | -|||||||||||||||||||||||||||
| penalty | -|||||||||||||||||||||||||||
| Boolean flag determines if the Charge is a penalty. | -|||||||||||||||||||||||||||
| currency | -|||||||||||||||||||||||||||
| Details of the currency associated with this charge. - Refer Charges Template for additional details | -|||||||||||||||||||||||||||
| amount | -|||||||||||||||||||||||||||
| Field holds the details of the actual amount to be collected - in the case of "Flat Charges" or the percentage amount to be collected in - case of "Percentage Amount Charges". Refer Charges Template - for details of the Available Charge Types | -|||||||||||||||||||||||||||
| chargeTimeType | -|||||||||||||||||||||||||||
| The time at which the charge becomes Due.
- Refer Charges Template for additional details - 1 = Disbursement : Applicable for loans and deducted at the time of loan disbursement. - 2 = Specified Due Date : Adhoc charge can be applied for loans and savings on a specified due date. - 3 = Savings Activation : This charge is applicable for savings account and charged at the time of account activation. This charge will be autodeducted once the account is activated with sufficient opening balance. - 5 = Withdrawal fee : Charge applied to every withdrawal of savings account. - 6 = Annual Fee : Recurring charge applied annually for savings on a specified Month and day. - 7 = Monthly Fee : Recurring charge applied on regular interval of months for savings. - |
- |||||||||||||||||||||||||||
| chargeAppliesTo | -|||||||||||||||||||||||||||
| The Entity for which the charge can be applied (Loans, Savings etc). - Refer Charges Template for additional details | -|||||||||||||||||||||||||||
| chargeCalculationType | -|||||||||||||||||||||||||||
| Rules for calculating the amount for a particular Charge. - Refer Charges Template for additional details | -|||||||||||||||||||||||||||
| feeOnMonthDay | -|||||||||||||||||||||||||||
| Used along with monthDayFormat to indicate the recurring charge due date starting on a given day of the month and follow specified feeInterval. e.g. fee due date starting on 10 May with feeInterval of two (2) months then a recurring fee on 10th of every two months is applied to savings account. monthDayFormat indicates day and month formatting used e.g. "dd MMM" for 10 May - This field is mandatory if chargeTimeType is of type Monthly Fee - |
- |||||||||||||||||||||||||||
| feeInterval | -|||||||||||||||||||||||||||
| Fee to be applied on a specified interval (number of months). - This field is mandatory if chargeTimeType is of type Monthly Fee - |
- |||||||||||||||||||||||||||
| minCap | -|||||||||||||||||||||||||||
| minimum cap: a 2% fee with a minimum cap of 500 - In case of a 5000 loan, the 2% is 100, and therefore automatically 500 is used as the value of the charge. - This field is optional and can be used along when ChargeCalculationType equals (2) PERCENT_OF_AMOUNT - |
-
+
+
Field Descriptions |
+
| name | +
| Name associated with this charge. | +
| chargeAppliesTo | +
| Enumeration for indicating whether charge is to be applicable for loans or savings. + 1=Loans, + 2=Savings + Once a charge definiton has been created, this attribute cannot be changed at any point. + |
+
| active | +
| Boolean flag determines if the charge is currently active. | +
| penalty | +
| Boolean flag determines if the charge is a penalty. If false the charge is considered a Fee | +
| currencyCode | +
| A three letter ISO code of currency. | +
| chargeCalculationType | +
| Enumeration for indicating whether charge amount is flat or percentage based: + 1=Flat, + 2=% of Amount + Used in combination with amount parameter e.g 1 % of Amount or 3.50 Flat +For loans, % of Amount refers to the loan principal disbursed. +For savings, % of Amount can be used with 'withrawal fees' and refers to the amount withdrawn. + |
+
| amount | +
| The charge amount. Used in combination with chargeCalculationType parameter. e.g 1 % of Amount or 3.50 Flat | +
| minCap | +
| Optional: Can be used when a '% of Amount' value is used for chargeCalculationType.
+ Used to enforce a minimum charge amount in cases where the calculated amount is less than the minimum amount provided. +e.g. A 2% fee with a minimum cap of 500: + In case of a 5000 loan, the 2% is 100, and therefore automatically 500 is used as the value of the charge. + + |
+
| maxCap | +
| Optional: Can be used when a '% of Amount' value is used for chargeCalculationType.
+ Used to enforce a maximum charge amount in cases where the calculated amount is greater than the maximum amount provided. +e.g. A 2% fee, with a maximum of 2000.: + In case of a 150000 loan, the 2% adds up to 3000 charge, and therefore the maximum cap of 2000 will be used. + + |
+
| chargeTimeType | +
| An enumeration indicating the time at which the charge becomes due: +
+ 1 = Disbursement : Applicable for loans and deducted at the time of loan disbursement. |
+
| chargePaymentMode | +
| Applicable to loan charges only: Enumeration for indicating whether charge is to be paid through an Account Transfer from savings or through Regular payment mode. + 0=Regular, + 1=Account Transfer + |
+
| feeOnMonthDay | +
| Used along with monthDayFormat to indicate the recurring charge due date starting on a given day of the month and follow specified feeInterval. e.g. fee due date starting on 10 May with feeInterval of two (2) months then a recurring fee on 10th of every two months is applied to savings account. monthDayFormat indicates day and month formatting used e.g. "dd MMM" for 10 May + This field is mandatory if chargeTimeType is of type Monthly Fee + |
+
| feeInterval | +
| Fee to be applied on a specified interval (number of months). + This field is mandatory if chargeTimeType is of type Monthly Fee + |
+
This is a convenience resource. It can be useful when - building maintenance user interface screens for client - applications. The template data returned consists of any or all - of: -
Example Request:
-
+
+
+
+ Retrieve Charge Template
+ This is a convenience resource. It can be useful when
+ building maintenance user interface screens for client
+ applications. The template data returned consists of any or all
+ of:
+
+ - Field Defaults
+ - Allowed Value Lists
+
+
+ Example Request:
+ charges/template
+
+
+
GET https://DomainName/api/v1/charges/template
-
-
+
+
{
- "active": false,
- "penalty": false,
- "currencyOptions":
- [
- {
- "code": "USD",
- "name": "US Dollar",
- "decimalPlaces": 2,
- "displaySymbol": "$",
- "nameCode": "currency.USD",
- "displayLabel": "US Dollar ($)"
- }
- ],
- "chargeCalculationTypeOptions":
- [
- {
- "id": 1,
- "code": "chargeCalculationType.flat",
- "value": "Flat"
- },
- {
- "id": 2,
- "code": "chargeCalculationType.percent.of.amount",
- "value": "% Amount"
- }
- ],
- "chargeAppliesToOptions":
- [
- {
- "id": 1,
- "code": "chargeAppliesTo.loan",
- "value": "Loan"
- },
- {
- "id": 2,
- "code": "chargeAppliesTo.savings",
- "value": "Savings"
- }
- ],
- "chargeTimeTypeOptions":
- [
- {
- "id": 1,
- "code": "chargeTimeType.disbursement",
- "value": "Disbursement"
- },
- {
- "id": 2,
- "code": "chargeTimeType.specifiedDueDate",
- "value": "Specified due date"
- },
- {
- "id": 3,
- "code": "chargeTimeType.savingsActivation",
- "value": "Savings Activation"
- },
- {
- "id": 5,
- "code": "chargeTimeType.withdrawalFee",
- "value": "Withdrawal Fee"
- },
- {
- "id": 6,
- "code": "chargeTimeType.annualFee",
- "value": "Annual Fee"
- },
- {
- "id": 7,
- "code": "chargeTimeType.monthlyFee",
- "value": "Monthly Fee"
- }
- ],
- "chargePaymetModeOptions":
- [
- {
- "id":0,
- "code":"chargepaymentmode.regular",
- "value":"chargepaymentmode.regular"
- },
- {
- "id":1,
- "code":"chargepaymentmode.accounttransfer",
- "value":"chargepaymentmode.accounttransfer"
- }
- ],
- "loanChargeCalculationTypeOptions" : [ { "code" : "chargeCalculationType.flat",
- "id" : 1,
- "value" : "Flat"
- },
- { "code" : "chargeCalculationType.percent.of.amount",
- "id" : 2,
- "value" : "% Amount"
- }
- ],
- "loanChargeTimeTypeOptions" : [ { "code" : "chargeTimeType.disbursement",
- "id" : 1,
- "value" : "Disbursement"
- },
- { "code" : "chargeTimeType.specifiedDueDate",
- "id" : 2,
- "value" : "Specified due date"
- }
- ],
- "savingsChargeCalculationTypeOptions" : [ { "code" : "chargeCalculationType.flat",
- "id" : 1,
- "value" : "Flat"
- },
- { "code" : "chargeCalculationType.percent.of.amount",
- "id" : 2,
- "value" : "% Amount"
- }
- ],
- "savingsChargeTimeTypeOptions" : [ { "code" : "chargeTimeType.specifiedDueDate",
- "id" : 2,
- "value" : "Specified due date"
- },
- { "code" : "chargeTimeType.savingsActivation",
- "id" : 3,
- "value" : "Savings Activation"
- },
- { "code" : "chargeTimeType.withdrawalFee",
- "id" : 5,
- "value" : "Withdrawal Fee"
- },
- { "code" : "chargeTimeType.annualFee",
- "id" : 6,
- "value" : "Annual Fee"
- },
- { "code" : "chargeTimeType.monthlyFee",
- "id" : 7,
- "value" : "Monthly Fee"
- }
- ]
+ "active": false,
+ "penalty": false,
+ "currencyOptions": [
+ {
+ "code": "USD",
+ "name": "US Dollar",
+ "decimalPlaces": 2,
+ "displaySymbol": "$",
+ "nameCode": "currency.USD",
+ "displayLabel": "US Dollar ($)"
+ }
+ ],
+ "chargeCalculationTypeOptions": [
+ {
+ "id": 1,
+ "code": "chargeCalculationType.flat",
+ "value": "Flat"
+ },
+ {
+ "id": 2,
+ "code": "chargeCalculationType.percent.of.amount",
+ "value": "% Amount"
+ }
+ ],
+ "chargeAppliesToOptions": [
+ {
+ "id": 1,
+ "code": "chargeAppliesTo.loan",
+ "value": "Loan"
+ },
+ {
+ "id": 2,
+ "code": "chargeAppliesTo.savings",
+ "value": "Savings"
+ }
+ ],
+ "chargeTimeTypeOptions": [
+ {
+ "id": 1,
+ "code": "chargeTimeType.disbursement",
+ "value": "Disbursement"
+ },
+ {
+ "id": 2,
+ "code": "chargeTimeType.specifiedDueDate",
+ "value": "Specified due date"
+ },
+ {
+ "id": 3,
+ "code": "chargeTimeType.savingsActivation",
+ "value": "Savings Activation"
+ },
+ {
+ "id": 5,
+ "code": "chargeTimeType.withdrawalFee",
+ "value": "Withdrawal Fee"
+ },
+ {
+ "id": 6,
+ "code": "chargeTimeType.annualFee",
+ "value": "Annual Fee"
+ },
+ {
+ "id": 7,
+ "code": "chargeTimeType.monthlyFee",
+ "value": "Monthly Fee"
+ }
+ ],
+ "chargePaymetModeOptions": [
+ {
+ "id": 0,
+ "code": "chargepaymentmode.regular",
+ "value": "Regular"
+ },
+ {
+ "id": 1,
+ "code": "chargepaymentmode.accounttransfer",
+ "value": "Account transfer"
+ }
+ ],
+ "loanChargeCalculationTypeOptions": [
+ {
+ "id": 1,
+ "code": "chargeCalculationType.flat",
+ "value": "Flat"
+ },
+ {
+ "id": 2,
+ "code": "chargeCalculationType.percent.of.amount",
+ "value": "% Amount"
+ }
+ ],
+ "loanChargeTimeTypeOptions": [
+ {
+ "id": 1,
+ "code": "chargeTimeType.disbursement",
+ "value": "Disbursement"
+ },
+ {
+ "id": 2,
+ "code": "chargeTimeType.specifiedDueDate",
+ "value": "Specified due date"
+ }
+ ],
+ "savingsChargeCalculationTypeOptions": [
+ {
+ "id": 1,
+ "code": "chargeCalculationType.flat",
+ "value": "Flat"
+ },
+ {
+ "id": 2,
+ "code": "chargeCalculationType.percent.of.amount",
+ "value": "% Amount"
+ }
+ ],
+ "savingsChargeTimeTypeOptions": [
+ {
+ "id": 2,
+ "code": "chargeTimeType.specifiedDueDate",
+ "value": "Specified due date"
+ },
+ {
+ "id": 3,
+ "code": "chargeTimeType.savingsActivation",
+ "value": "Savings Activation"
+ },
+ {
+ "id": 5,
+ "code": "chargeTimeType.withdrawalFee",
+ "value": "Withdrawal Fee"
+ },
+ {
+ "id": 6,
+ "code": "chargeTimeType.annualFee",
+ "value": "Annual Fee"
+ },
+ {
+ "id": 7,
+ "code": "chargeTimeType.monthlyFee",
+ "value": "Monthly Fee"
+ }
+ ]
}
-
-
-
+
+ Define a new charge specific to loan or saving that can later be associated with loan - products, loans Savings product or Savings account.
-
+
+
+
+ Create/Define a Charge
+ Define a new charge that can later be associated with loans and savings through their respective product definitions or directly on each account instance.
+
+
+
POST https://DomainName/api/v1/charges
-
-
+
+
POST charges
Content-Type: application/json
Request Body:
{
- "name": "Loan service fee",
- "chargeAppliesTo": 1,
- "currencyCode": "USD",
- "locale": "en",
- "amount": "230.56",
- "chargeTimeType": "1",
- "chargeCalculationType": "1",
- "chargePaymentMode": "1",
- "active": true
+"name": "Loan service fee",
+"chargeAppliesTo": 1,
+"currencyCode": "USD",
+"locale": "en",
+"amount": "230.56",
+"chargeTimeType": "1",
+"chargeCalculationType": "1",
+"chargePaymentMode": "1",
+"active": true
}
-
-
+
+
{
- "resourceId": 1
+"resourceId": 1
}
-
-
+
+
POST charges
Content-Type: application/json
Request Body:
{
- "locale": "en",
- "name": "Default Penalty",
- "amount": "2",
- "currencyCode": "USD",
- "chargeAppliesTo": "1",
- "chargeTimeType": "2",
- "chargeCalculationType": "2",
- "chargePaymentMode": "1",
- "active": "true",
- "penalty": "true",
- "minCap": 50.00,
- "maxCap": 100.00
+"locale": "en",
+"name": "Default Penalty",
+"amount": "2",
+"currencyCode": "USD",
+"chargeAppliesTo": "1",
+"chargeTimeType": "2",
+"chargeCalculationType": "2",
+"chargePaymentMode": "1",
+"active": "true",
+"penalty": "true",
+"minCap": 50.00,
+"maxCap": 100.00
}
-
-
+
+
{
- "resourceId": 4
+"resourceId": 4
}
-
+
-
+
POST charges
Content-Type: application/json
Request Body:
{
- "locale": "en",
- "name": "Annuaul Fee",
- "amount": "20",
- "currencyCode": "USD",
- "chargeAppliesTo": "2",
- "chargeTimeType": "6",
- "chargeCalculationType": "1",
- "chargePaymentMode": "1",
- "active": "true",
- "penalty": "false"
+"locale": "en",
+"name": "Annuaul Fee",
+"amount": "20",
+"currencyCode": "USD",
+"chargeAppliesTo": "2",
+"chargeTimeType": "6",
+"chargeCalculationType": "1",
+"chargePaymentMode": "1",
+"active": "true",
+"penalty": "false"
}
-
-
+
+
{
- "resourceId": 5
+"resourceId": 5
}
-
-
+
+
POST charges
Content-Type: application/json
Request Body:
{
- "locale": "en",
- "name": "Quarterly Fee",
- "amount": "5",
- "currencyCode": "USD",
- "chargeAppliesTo": "2",
- "chargeTimeType": "7",
- "feeOnMonthDay": "10 May",
- "monthDayFormat": "dd MMM",
- "feeInterval": "4",
- "chargeCalculationType": "1",
- "active": "true",
- "penalty": "false"
+"locale": "en",
+"name": "Quarterly Fee",
+"amount": "5",
+"currencyCode": "USD",
+"chargeAppliesTo": "2",
+"chargeTimeType": "7",
+"feeOnMonthDay": "10 May",
+"monthDayFormat": "dd MMM",
+"feeInterval": "4",
+"chargeCalculationType": "1",
+"active": "true",
+"penalty": "false"
}
-
-
+
+
{
- "resourceId": 6
+"resourceId": 6
}
-
-
-
+
+