Installment management
Installments are payments (debit transactions) that are scheduled to be made at regular intervals. An installment agreement is a contract for a series of installments. It’s associated with a particular account and is intended to pay off a debt. An account can have multiple installment agreements associated with it. See Create an installment agreement for more information.
The first installment in an installment agreement is posted to either the current statement or a future one. Successive installments in the agreement are then posted to successive statements — that is, one installment per statement. However, there are times when a customer might want to pay off one or more future installments ahead of time. To enable this, the installments must be advanced to the current cycle. To advance an installment means to reschedule the installment to appear on the statement for the current cycle.
Installment advancements
One or more future installments can be advanced in a single operation called an installment advancement. An installment advancement can specify a specific number of future installments to advance in a specific installment agreement. Or it can advance all future installments in all installment agreements associated with the account. (All installments in all agreements might be advanced if the customer wants to pay off their entire debt at once.)
Installments are advanced starting with the last future installment in the series and working down from there. For example, suppose you are currently in cycle 1, and you have a series of installments scheduled for cycles 2, 3, 4, and 5. Now suppose you create an installment advancement and set the number of installments to advance to 2. This causes the installments for cycles 4 and 5 to be advanced to cycle 1. The installments for cycles 2 and 3 are unaffected.
The Pismo platform has four endpoints for managing installment advancements. These are explained in the linked sections.
- Simulate installment advancement
- Create installment advancement
- Get installment advancement
- Cancel installment advancement
When you advance an installment to the current cycle, you must specify what to do with the interest for that installment. There are three possibilities:
- Remove 100% of the interest on the advanced installment by setting
remove_interest_from_current
totrue
and settingcalculator
toNONE
(or not setting it, since the default isNONE
). - Advance 100% of the interest on the advanced installment by setting
remove_interest_from_current
tofalse
and settingcalculator
toNONE
(or not setting it, since the default isNONE
). - Adjust the interest on the installments. To do this, set
calculator
toPRESENT_VALUE
. This tells the Pismo platform to recalculate the interest on an advanced installment based on the difference between the original statement due date and the due date of the current statement.remove_interest_from_current
can be set to eithertrue
orfalse
. Iftrue
, then the interest on installments that were already in the current cycle (and did not need to be advanced) is recalculated based on the date of the advancement. Iffalse
, the interest on those installments is unchanged.
Simulating an installment advancement
Simulate installment advancement lets you simulate an advancement without actually creating it.
To simulate advancing installments for all the installment agreements (contracts) associated with an account, set the condition
query parameter to ALL_CONTRACTS
. To simulate advancing installments for a single installment agreement, set the condition
query parameter to SINGLE_CONTRACT
, and set the transaction_id
query parameter to the transaction ID of any one of the installments in the agreement.
Example
Executing the following request simulates advancing all the installments in each of the installment agreements associated with an account whose ID is 169528212. Since removeInterestFromCurrent
is false
and calculator
is NONE
, the interest for each advanced installment is moved with the installment.
curl --request GET \
--url 'https://sandbox.pismolabs.io/installment-management/v1/accounts/6912345/installment-advance/simulations?transactionId=98457355&condition=ALL_CONTRACTS&removeInterestFromCurrent=false&calculator=NONE&reschedule=ADVANCEMENT' \
--header 'accept: application/json'
If the request executes successfully, it should produce a result similar to the following.
{
"account_id": 169528212,
"condition": "ALL_CONTRACTS",
"calculator": "NONE",
"reschedule": "ADVANCEMENT",
"installments": [
{
"id": 2862814643,
"old_statement_id": 1391523222,
"new_statement_id": 1391523222,
"old_amount": 55.00,
"new_amount": 55.00,
"old_interest_amount": 5.00,
"new_interest_amount": 5.00
},
{
"id": 2862814645,
"old_statement_id": 1391523223,
"new_statement_id": 1391523222,
"old_amount": 55.00,
"new_amount": 55.00,
"old_interest_amount": 5.00,
"new_interest_amount": 5.00
},
{
"id": 2862814647,
"old_statement_id": 1391523224,
"new_statement_id": 1391523222,
"old_amount": 55.00,
"new_amount": 55.00,
"old_interest_amount": 5.00,
"new_interest_amount": 5.00
},
{
"id": 2862814649,
"old_statement_id": 1391523225,
"new_statement_id": 1391523222,
"old_amount": 55.00,
"new_amount": 55.00,
"old_interest_amount": 5.00,
"new_interest_amount": 5.00
},
{
"id": 2862814642,
"old_statement_id": 1391523222,
"new_statement_id": 1391523222,
"old_amount": 5.00,
"new_amount": 5.00
},
{
"id": 2862814644,
"old_statement_id": 1391523223,
"new_statement_id": 1391523222,
"old_amount": 5.00,
"new_amount": 5.00
},
{
"id": 2862814646,
"old_statement_id": 1391523224,
"new_statement_id": 1391523222,
"old_amount": 5.00,
"new_amount": 5.00
},
{
"id": 2862814648,
"old_statement_id": 1391523225,
"new_statement_id": 1391523222,
"old_amount": 5.00,
"new_amount": 5.00
}
]
}
Creating an installment advancement
Create installment advancement creates an advancement of one or more installments to the current cycle.
To advance all the installments for all the installment agreements (contracts) associated with an account, set thecondition
body parameter to ALL_CONTRACTS
. To advance installments for a single installment agreement, set the condition
body parameter to SINGLE_CONTRACT
, and set transaction_id
to the transaction ID of any one of the installments in the agreement.
Example
Executing the following request advances all installments in each of the installment agreements associated with an account whose ID is 169528212. Since remove_interest_from_current
is false
and calculator
is PRESENT_VALUE
, the interest on each advanced installment is not removed, but it is recalculated.
POST v1/accounts/{{account_id}}/installment-advance
curl --request POST \
--url https://sandbox.pismolabs.io/installment-management/v1/accounts/169528212/installment-advance \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-cid: 5bb05174-4e80-11ea-b77f-2e728ce88125' \
--data '
{
"remove_interest_from_current": false,
"condition": "ALL_CONTRACTS",
"calculator": "PRESENT_VALUE",
"reschedule": "ADVANCEMENT"
}
If the request executes successfully, it should produce a result similar to that shown below. Note that several of the installments have had their interest reduced. These are the installments that were advanced. The installments that show the same values for old_interest_amount
and new_interest_amount
were already in the current cycle, so they weren't moved.
Normally, there would be one installment scheduled per cycle. However, installments can be manipulated by other services, such as transaction shifts, so there could be more than one installment already in the current cycle before the advancement request. That's the case in this example.
{
"advancement_id": 84,
"account_id": 169528212,
"org_id": "TN-cc8f8b89-233a-4582-9f36-63ee85278d6d",
"condition": "ALL_CONTRACTS",
"calculator": "PRESENT_VALUE",
"reschedule": "ADVANCEMENT",
"created_at": "2024-04-22T12:02:43",
"installments": [
{
"id": 2862814643,
"old_statement_id": 1391523222,
"new_statement_id": 1391523222,
"old_amount": 55.00,
"new_amount": 55.00,
"old_interest_amount": 5.00,
"new_interest_amount": 5.00
},
{
"id": 2862814645,
"old_statement_id": 1391523223,
"new_statement_id": 1391523222,
"old_amount": 55.00,
"new_amount": 54.53,
"old_interest_amount": 5.00,
"new_interest_amount": 4.53
},
{
"id": 2862814647,
"old_statement_id": 1391523224,
"new_statement_id": 1391523222,
"old_amount": 55.00,
"new_amount": 54.12,
"old_interest_amount": 5.00,
"new_interest_amount": 4.12
},
{
"id": 2862814649,
"old_statement_id": 1391523225,
"new_statement_id": 1391523222,
"old_amount": 55.00,
"new_amount": 53.73,
"old_interest_amount": 5.00,
"new_interest_amount": 3.73
},
{
"id": 2862814642,
"old_statement_id": 1391523222,
"new_statement_id": 1391523222,
"old_amount": 5.00,
"new_amount": 5.00
},
{
"id": 2862814644,
"old_statement_id": 1391523223,
"new_statement_id": 1391523222,
"old_amount": 5.00,
"new_amount": 5.00
},
{
"id": 2862814646,
"old_statement_id": 1391523224,
"new_statement_id": 1391523222,
"old_amount": 5.00,
"new_amount": 5.00
},
{
"id": 2862814648,
"old_statement_id": 1391523225,
"new_statement_id": 1391523222,
"old_amount": 5.00,
"new_amount": 5.00
}
]
}
Retrieving an installment advancement
Get installment advancement retrieves an existing advancement.
Example
Executing the following request retrieves an installment advancement with ID 8191125.
curl --request GET \
--url https://sandbox.pismolabs.io/installment-management/v1/accounts/6912345/installment-advance/8191125 \
--header 'accept: application/json' \
--header 'x-cid: 5bb05174-4e80-11ea-b77f-2e728ce88125'
If the request executes successfully, it should return something similar to the following. In this case, the advancement is only advancing one installment.
{
"tracking_id": "string",
"created_at": "2021-04-14T12:00:00-03:00",
"cancelled_at": "2021-04-14T12:00:00-03:00",
"accountId": 67854328,
"condition": "SINGLE_CONTRACT",
"calculator": "PRESENT_VALUE",
"reschedule": "ADVANCEMENT",
"installments": [
{
"new_interest_amount": 9.9,
"old_interest_amount": 11.9,
"new_amount": 99.9,
"old_amount": 102.9,
"new_statement_id": 1,
"old_statement_id": 10
}
]
}
Canceling an installment advancement
Cancel installment advancement cancels an existing advancement, reverting the installments to their original due dates. The original interest charges are reinstated.
Example
Executing the following request cancels the installment advancement that was created in the example for the Creating an installment advancement section.
curl --request DELETE \
--url https://sandbox.pismolabs.io/installment-management/v1/accounts/169528212/installment-advance/84 \
--header 'accept: application/json' \
--header 'x-cid: 5bb05174-4e80-11ea-b77f-2e728ce88125'
If the request executes successfully, the results should list the installments with their amounts and interests reset to their original values.
{
"advancement_id": 84,
"account_id": 169528212,
"org_id": "TN-cc8f8b89-233a-4582-9f36-63ee85278d6d",
"condition": "ALL_CONTRACTS",
"calculator": "PRESENT_VALUE",
"reschedule": "ADVANCEMENT",
"cancelled_at": "2024-04-22T12:08:59.578668977",
"created_at": "2024-04-22T12:02:43",
"installments": [
{
"id": 2862814643,
"old_statement_id": 1391523222,
"new_statement_id": 1391523222,
"old_amount": 55.0,
"new_amount": 55.0,
"old_interest_amount": 5.0,
"new_interest_amount": 5.0
},
{
"id": 2862814645,
"old_statement_id": 1391523222,
"new_statement_id": 1391523223,
"old_amount": 54.53,
"new_amount": 55.00,
"old_interest_amount": 4.53,
"new_interest_amount": 5.0
},
{
"id": 2862814647,
"old_statement_id": 1391523222,
"new_statement_id": 1391523224,
"old_amount": 54.12,
"new_amount": 55.00,
"old_interest_amount": 4.12,
"new_interest_amount": 5.0
},
{
"id": 2862814649,
"old_statement_id": 1391523222,
"new_statement_id": 1391523225,
"old_amount": 53.73,
"new_amount": 55.00,
"old_interest_amount": 3.73,
"new_interest_amount": 5.0
},
{
"id": 2862814642,
"old_statement_id": 1391523222,
"new_statement_id": 1391523222,
"old_amount": 5.0,
"new_amount": 5.0
},
{
"id": 2862814644,
"old_statement_id": 1391523222,
"new_statement_id": 1391523223,
"old_amount": 5.0,
"new_amount": 5.0
},
{
"id": 2862814646,
"old_statement_id": 1391523222,
"new_statement_id": 1391523224,
"old_amount": 5.0,
"new_amount": 5.0
},
{
"id": 2862814648,
"old_statement_id": 1391523222,
"new_statement_id": 1391523225,
"old_amount": 5.0,
"new_amount": 5.0
}
]
}
Updated 3 months ago