Tutorial: Charges
Below are the main steps for creating, getting and paying charges.
Create Savings Account Charge
Step 1: Apply Charge into Savings Account
To add a charge to savings account:
curl --request POST \
--url 'https://{{host}}/v1/savingsaccounts/{{savingsId}}/charges' \
--header 'Authorization: Bearer your-token' \
--header 'Content-Type: application/json' \
--data '{
"chargeId":548,
"amount":"2.68",
"locale":"en",
"dateFormat":"dd MMMM yyyy",
"dueDate":"08 April 2024"
} '
Fields Detail
| Field | Detail |
|---|---|
| savingsId | Savings Account ID to apply charge |
| chargeId | Charge to be applied into this savings account |
Step 2: Get Savings Account Charges
Get savings account including charges
curl --request GET \
--url 'https://{{host}}/v1/savingsaccounts/{{savingsId}}?associations=charges' \
--header 'Authorization: Bearer your-token'
Create a Charge for Other Accounts
After understanding charge metadata such as chargeAppliesTo and chargeTimeType follow the instructions below create a charge for any type of account.
Step 1: Get Template
To get all valid options for creating a charge you first get charge template
curl --request GET \
--url 'https://{{host}}/v1/charges/template?tenantIdentifier=default' \
--header 'Authorization: Bearer your-token'
Response:
{
"active": false,
"penalty": false,
"applyToExistingAccount": false,
"currencyOptions": [
{
"id": 23,
"code": "AUD",
"name": "Australian Dollar",
"decimalPlaces": 2,
"displaySymbol": "A$",
"nameCode": "currency.AUD",
"displayLabel": "Australian Dollar (A$)"
},
{
"id": 24,
"code": "CAD",
"name": "Canadian Dollar",
"decimalPlaces": 2,
"nameCode": "currency.CAD",
"displayLabel": "Canadian Dollar [CAD]"
},
{
"id": 26,
"code": "EUR",
"name": "Euro",
"decimalPlaces": 2,
"displaySymbol": "€",
"nameCode": "currency.EUR",
"displayLabel": "Euro (€)"
},
{
"id": 28,
"code": "HKD",
"name": "Hong Kong Dollar",
"decimalPlaces": 2,
"nameCode": "currency.HKD",
"displayLabel": "Hong Kong Dollar [HKD]"
},
{
"id": 33,
"code": "JPY",
"name": "Japanese Yen",
"decimalPlaces": 0,
"nameCode": "currency.JPY",
"displayLabel": "Japanese Yen [JPY]"
},
{
"id": 30,
"code": "NZD",
"name": "New Zealand Dollar",
"decimalPlaces": 2,
"nameCode": "currency.NZD",
"displayLabel": "New Zealand Dollar [NZD]"
},
{
"id": 29,
"code": "NOK",
"name": "Norwegian Krone",
"decimalPlaces": 2,
"nameCode": "currency.NOK",
"displayLabel": "Norwegian Krone [NOK]"
},
{
"id": 27,
"code": "GBP",
"name": "Pound Sterling",
"decimalPlaces": 2,
"nameCode": "currency.GBP",
"displayLabel": "Pound Sterling [GBP]"
},
{
"id": 32,
"code": "SGD",
"name": "Singapore Dollar",
"decimalPlaces": 2,
"nameCode": "currency.SGD",
"displayLabel": "Singapore Dollar [SGD]"
},
{
"id": 31,
"code": "SEK",
"name": "Swedish Krona",
"decimalPlaces": 2,
"nameCode": "currency.SEK",
"displayLabel": "Swedish Krona [SEK]"
},
{
"id": 25,
"code": "CHF",
"name": "Swiss Franc",
"decimalPlaces": 2,
"nameCode": "currency.CHF",
"displayLabel": "Swiss Franc [CHF]"
},
{
"id": 22,
"code": "AED",
"name": "UAE Dirham",
"decimalPlaces": 2,
"nameCode": "currency.AED",
"displayLabel": "UAE Dirham [AED]"
},
{
"id": 21,
"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"
},
{
"id": 3,
"code": "chargeCalculationType.percent.of.amount.and.interest",
"value": "% Loan Amount + Interest"
},
{
"id": 4,
"code": "chargeCalculationType.percent.of.interest",
"value": "% Interest"
},
{
"id": 5,
"code": "chargeCalculationType.percent.of.disbursement.amount",
"value": "% Disbursement Amount"
}
],
"chargeAppliesToOptions": [
{
"id": 1,
"code": "chargeAppliesTo.loan",
"value": "Loan"
},
{
"id": 2,
"code": "chargeAppliesTo.savings",
"value": "Savings"
},
{
"id": 3,
"code": "chargeAppliesTo.client",
"value": "Client"
},
{
"id": 4,
"code": "chargeAppliesTo.shares",
"value": "Shares"
}
],
"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"
},
{
"id": 8,
"code": "chargeTimeType.instalmentFee",
"value": "Installment Fee"
},
{
"id": 9,
"code": "chargeTimeType.overdueInstallment",
"value": "Overdue Fees"
},
{
"id": 10,
"code": "chargeTimeType.overdraftFee",
"value": "Overdraft Fee"
},
{
"id": 11,
"code": "chargeTimeType.weeklyFee",
"value": "Weekly Fee"
},
{
"id": 12,
"code": "chargeTimeType.tranchedisbursement",
"value": "Tranche Disbursement"
},
{
"id": 13,
"code": "chargeTimeType.activation",
"value": "Share Account Activate"
},
{
"id": 14,
"code": "chargeTimeType.sharespurchase",
"value": "Share Purchase"
},
{
"id": 15,
"code": "chargeTimeType.sharesredeem",
"value": "Share Redeem"
},
{
"id": 16,
"code": "chargeTimeType.savingsNoActivityFee",
"value": "Saving No Activity Fee"
},
{
"id": 21,
"code": "chargeTimeType.domesticAtmWithdrawalChargeTime",
"value": "Domestic ATM Withdrawal"
},
{
"id": 22,
"code": "chargeTimeType.internationalAtmWithdrawalChargeTime",
"value": "International ATM Withdrawal"
},
{
"id": 23,
"code": "chargeTimeType.internationalTransactionChargeTime",
"value": "International Transaction"
},
{
"id": 24,
"code": "chargeTimeType.externalCardPushFee",
"value": "External Card PUSH Transaction"
},
{
"id": 25,
"code": "chargeTimeType.externalCardPullFee",
"value": "External Card PULL Transaction"
}
],
"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"
},
{
"id": 3,
"code": "chargeCalculationType.percent.of.amount.and.interest",
"value": "% Loan Amount + Interest"
},
{
"id": 4,
"code": "chargeCalculationType.percent.of.interest",
"value": "% Interest"
},
{
"id": 5,
"code": "chargeCalculationType.percent.of.disbursement.amount",
"value": "% Disbursement Amount"
}
],
"loanChargeTimeTypeOptions": [
{
"id": 1,
"code": "chargeTimeType.disbursement",
"value": "Disbursement"
},
{
"id": 2,
"code": "chargeTimeType.specifiedDueDate",
"value": "Specified due date"
},
{
"id": 8,
"code": "chargeTimeType.instalmentFee",
"value": "Installment Fee"
},
{
"id": 9,
"code": "chargeTimeType.overdueInstallment",
"value": "Overdue Fees"
},
{
"id": 12,
"code": "chargeTimeType.tranchedisbursement",
"value": "Tranche Disbursement"
}
],
"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"
},
{
"id": 11,
"code": "chargeTimeType.weeklyFee",
"value": "Weekly Fee"
},
{
"id": 10,
"code": "chargeTimeType.overdraftFee",
"value": "Overdraft Fee"
},
{
"id": 16,
"code": "chargeTimeType.savingsNoActivityFee",
"value": "Saving No Activity Fee"
},
{
"id": 21,
"code": "chargeTimeType.domesticAtmWithdrawalChargeTime",
"value": "Domestic ATM Withdrawal"
},
{
"id": 22,
"code": "chargeTimeType.internationalAtmWithdrawalChargeTime",
"value": "International ATM Withdrawal"
},
{
"id": 23,
"code": "chargeTimeType.internationalTransactionChargeTime",
"value": "International Transaction"
},
{
"id": 24,
"code": "chargeTimeType.externalCardPushFee",
"value": "External Card PUSH Transaction"
},
{
"id": 25,
"code": "chargeTimeType.externalCardPullFee",
"value": "External Card PULL Transaction"
}
],
"clientChargeCalculationTypeOptions": [
{
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
}
],
"clientChargeTimeTypeOptions": [
{
"id": 2,
"code": "chargeTimeType.specifiedDueDate",
"value": "Specified due date"
}
],
"shareChargeCalculationTypeOptions": [
{
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
},
{
"id": 2,
"code": "chargeCalculationType.percent.of.amount",
"value": "% Amount"
}
],
"shareChargeTimeTypeOptions": [
{
"id": 13,
"code": "chargeTimeType.activation",
"value": "Share Account Activate"
},
{
"id": 14,
"code": "chargeTimeType.sharespurchase",
"value": "Share Purchase"
},
{
"id": 15,
"code": "chargeTimeType.sharesredeem",
"value": "Share Redeem"
}
],
"feeFrequencyOptions": [
{
"id": 0,
"code": "frequencyperiodFrequencyType.days",
"value": "Days"
},
{
"id": 1,
"code": "frequencyperiodFrequencyType.weeks",
"value": "Weeks"
},
{
"id": 2,
"code": "frequencyperiodFrequencyType.months",
"value": "Months"
},
{
"id": 3,
"code": "frequencyperiodFrequencyType.years",
"value": "Years"
}
],
"incomeOrLiabilityAccountOptions": {
"liabilityAccountOptions": [
{
"id": 30,
"name": "Current Accounts",
"parentId": 1,
"glCode": "10104",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 2,
"code": "accountType.liability",
"value": "LIABILITY"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"nameDecorated": "....Current Accounts",
"tagId": {
"id": 0,
"active": false,
"mandatory": false,
"systemDefined": false
}
},
{
"id": 2,
"name": "Overpayment Liability",
"glCode": "10200",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 2,
"code": "accountType.liability",
"value": "LIABILITY"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"nameDecorated": "Overpayment Liability",
"tagId": {
"id": 0,
"active": false,
"mandatory": false,
"systemDefined": false
}
},
{
"id": 55,
"name": "Liability Transfer (Temp)",
"glCode": "220004-Temp",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 2,
"code": "accountType.liability",
"value": "LIABILITY"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"description": "Temporary Liability account to track Account Transfers",
"nameDecorated": "Liability Transfer (Temp)",
"tagId": {
"id": 0,
"active": false,
"mandatory": false,
"systemDefined": false
}
}
],
"incomeAccountOptions": [
{
"id": 54,
"name": "Loan Recovery (Temp)",
"glCode": "220002-Temp",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 4,
"code": "accountType.income",
"value": "INCOME"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"description": "Temporary account to track income from Loan recovery",
"nameDecorated": "Loan Recovery (Temp)",
"tagId": {
"id": 0,
"active": false,
"mandatory": false,
"systemDefined": false
}
},
{
"id": 36,
"name": "Fees and Charges",
"parentId": 18,
"glCode": "30101",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 4,
"code": "accountType.income",
"value": "INCOME"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"nameDecorated": "....Fees and Charges",
"tagId": {
"id": 0,
"active": false,
"mandatory": false,
"systemDefined": false
}
},
{
"id": 37,
"name": "Penalties",
"parentId": 18,
"glCode": "30102",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 4,
"code": "accountType.income",
"value": "INCOME"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"nameDecorated": "....Penalties",
"tagId": {
"id": 0,
"active": false,
"mandatory": false,
"systemDefined": false
}
},
{
"id": 38,
"name": "Interest Received from Borrowers",
"parentId": 18,
"glCode": "30103",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 4,
"code": "accountType.income",
"value": "INCOME"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"nameDecorated": "....Interest Received from Borrowers",
"tagId": {
"id": 0,
"active": false,
"mandatory": false,
"systemDefined": false
}
},
{
"id": 39,
"name": "Insurance Charges",
"parentId": 18,
"glCode": "30104",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 4,
"code": "accountType.income",
"value": "INCOME"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"nameDecorated": "....Insurance Charges",
"tagId": {
"id": 0,
"active": false,
"mandatory": false,
"systemDefined": false
}
},
{
"id": 40,
"name": "Other Operating Income",
"parentId": 18,
"glCode": "30105",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 4,
"code": "accountType.income",
"value": "INCOME"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"nameDecorated": "....Other Operating Income",
"tagId": {
"id": 0,
"active": false,
"mandatory": false,
"systemDefined": false
}
}
]
},
"taxGroupOptions": [],
"ignoreChargesOnNegativeBalance": false,
"isMandatory": false,
"chargeDueDateOnAccountActivation": false
}
Step 2: Create Charge
Then to create a charge you make a POST API call
curl --request POST \
--url 'https://{{host}}/v1/charges?tenantIdentifier=default' \
--header 'Authorization: Bearer your-token' \
--header 'Content-Type: application/json' \
--data '{
"name": "Loan service fee",
"chargeAppliesTo": 1,
"currencyCode": "USD",
"locale": "en",
"amount": "230.56",
"chargeTimeType": "1",
"chargeCalculationType": "1",
"chargePaymentMode": "1",
"active": true
}'
Fields Descriptions
| Name | Description | Validation |
|---|---|---|
| name | Name associated with this charge. | Mandatory |
| chargeAppliesTo | Enumeration for indicating whether charge is to be applicable for loans, savings or clients: 1=Loan, 2=Savings, 3=Client, 5=Transfer, 6=Credit Card. Once a charge definition has been created, this attribute cannot be changed at any point. | Mandatory |
| currencyCode | A three letter ISO code of currency. | Must be same with account currency code |
| 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 | |
| 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 'withdrawal fees' and refers to the amount withdrawn. | Mandatory |
| amount | The charge amount. Used in combination with chargeCalculationType parameter. e.g 1 % of Amount or 3.50 Flat | Mandatory |
| 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, find detail on: https://apidocs.cloud.mbanq.com/docs/intro-to-charges | Mandatory |
| 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. | This field is mandatory if chargeTimeType is of type Monthly Fee or feeFrequency is selected |
| feeFrequency | This field is Optional Used to indicate the recurring(days,weeks,months and Years) charge due date starting on system calculated date for overdue penalty. | |
| productIDs | This field is Optaional and type array list and you can define ids from saving production example [1,2,3] so this charge will applying auto to that saving product. | |
| applyToExistingAccount | This field is optional and it base on productIDs if you set saving product 1(productIDs:[1]) with applyToExistingAccount is true all account create from product will applying this charge too. |
Get Charges
curl --request GET \
--url 'https://{{host}}/v1/charges?tenantIdentifier=default' \
--header 'Authorization: Bearer your-token'
Response
[
{
"id": 8,
"name": "Loan service fee",
"active": true,
"penalty": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 230.560000,
"chargeTimeType": {
"id": 1,
"code": "chargeTimeType.disbursement",
"value": "Disbursement"
},
"chargeAppliesTo": {
"id": 1,
"code": "chargeAppliesTo.loan",
"value": "Loan"
},
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
},
"chargePaymentMode": {
"id": 1,
"code": "chargepaymentmode.accounttransfer",
"value": "Account transfer"
},
"applyToExistingAccount": false,
"ignoreChargesOnNegativeBalance": false,
"isMandatory": false,
"chargeDueDateOnAccountActivation": false
}
]
Pay a Charge
Most often charges are collected automatically either by scheduler job or by event triggering (such as transfer charge). However If you wish to pay a charge immediately you can call API as below
curl --request POST \
--url 'https://{{host}}/v1/savingsaccounts/{savingsId}/charges/{{savingsChargeId}}?command=paycharge' \
--header 'Authorization: Bearer your-token' \
--header 'Content-Type: application/json' \
--data '{dueDate: "08 April 2024", amount: 2.68, locale: "en", dateFormat: "dd MMMM yyyy"}'
Updated 8 months ago