Guides
About PismoContact Us

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.

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:

  1. Remove 100% of the interest on the advanced installment by setting remove_interest_from_current to true and setting calculator to NONE (or not setting it, since the default is NONE).
  2. Advance 100% of the interest on the advanced installment by setting remove_interest_from_current to false and setting calculator to NONE (or not setting it, since the default is NONE).
  3. Adjust the interest on the installments. To do this, set calculator to PRESENT_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 either true or false. If true, 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. If false, 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 about 2 months ago