The Installments payment endpoint gives users an easy way to pay in installments. You can set up rules for installments using flexible transaction controls.

📘

Currently, the Installments payment endpoint only works with credit accounts. You must calculate all fees and interests ahead of time and include them in the request. Talk to your Pismo representative about defining these for your organization.

Before you call the Installments payment endpoint, you need to configure processing codes and transaction types for the endpoint. The following sections step you through how to do this.

🚧

If you try to call the Installments payment endpoint without first configuring the processing codes and transaction types, the platform will not be able to create the transactions involving the principal amount and other charges.

Create processing code

To create a processing code, use the Create processing code endpoint, and provide the required body parameters in the request.

To create two related processing codes (where one is used to reverse the other), use the Create processing code endpoint and, in addition to the required fields for the first processing code, provide values in the optional undo_processing_code and undo_description fields.

For additional options, see Create or update processing code.

Create transaction type

To create a transaction type, use the Create transaction type endpoint. You need to create a transaction type for the contract and another one for the installments. If the operation includes taxes that appear on the customer’s statement, you need to create transaction types for them, too.

Example for creating a new transaction type for the contract:

{  
     "transaction_type_id": 7500,  
     "description": "Contract for credit offering",  
     "credit": true,  
     "posted_transaction": false  
}

In this case, the contract does not appear on the customer’s statement (posted_transaction is false).

Example for creating a new transaction type for the installments transactions:

{  
     "transaction_type_id": 7501,  
     "description": "Installment credit offering",  
     "credit": true,  
     "posted_transaction": true  
}

In this case, the transaction installments will be on the final customer’s statement (posted_transaction is true).

Create transaction flow

The final step before calling the Installments payments endpoint is to setup the transaction flow. A transaction flow links a processing code with transaction types for installment non-network operations. Using the Create transaction flow endpoint, you can define transaction flows for both the contract and the installments.

Example for a contract transaction:

{  
     "key": "CONTRACT",  
     "transaction_type_id": 7500,  
     "processing_code": "5566"  
}

Example for an installment transaction:

{  
     "key": "INSTALLMENT",  
     "transaction_type_id": 7501,  
     "processing_code": "5566"  
}

📘

Note that the same processing code is linked to the contract transaction type and to the installment transaction type.

Make an installments payment

You make an installments payment using the Installments payment endpoint. The payload for the request should include an array of installment objects. Optionally, you can also include the first_installment_date. For example, you could use the following sample code to create two installments that would start on June 1, 2023:

{
    "charging_amount": 22.30,
    "processing_code": "005000",
    "descriptor": "Test descriptor",
    "tracking_id": "2a1ea2f6-97fb-4738-97f4-d25ac88713a1",
    "account_id": 1,
  	"first_installment_date": 2023-06-01,
    "installments": [
        {
            "installment_number": 1,
            "total_amount": 11.15,
            "principal_amount": 10.00,
            "interest_amount": 1.00,
            "interest_rate": 0.10,
            "tax_amount": 0.15
        },
        {
            "installment_number": 2,
            "total_amount": 11.15,
            "principal_amount": 10.00,
            "interest_amount": 1.00,
            "interest_rate": 0.10,
            "tax_amount": 0.15
        }
    ]
}

If successful, this request returns the following response:

{
	"authorization_id": 36174570,
	"tracking_id": "2a1ea2f6-97fb-4738-97f4-d25ac88713a1",
	"event_date": "2022-06-28T16:01:11.674"
}

Financed charge

The financed_charge object in the Installments payment endpoint request allows you to specify financed charges such as fees or taxes that are embedded in each installment's principal_amount field.

When you provide a value or multiples values in this object, the platform generates a separate accounting transaction for the specified financed charges. All fields within the financed_charge object must have the suffix “ _amount”. For example, “iof_amount”, "iva_amount", “your_tax_amount”. Work with your Pismo representative to define new financed charge type fields. When the representative creates and maps the new field, you can then use it and get the expected result.

🚧

Don't use tax_amount field

If you use the financed_charge object, you can't use the tax_amount field for the installments in the same request.

The financed_charge object is reserved for cases when the fee or tax is embedded in the principal_amount and must not be described in the tax_amount field.

{  
	"charging_amount": 22,  
	"processing_code": "215000",  
	"descriptor": "Installments payment",  
	"account_id": 123,  
	"tracking_id": "754d7b6b-a7c1-494c-8f7b-06d36a28c0bf",  
	"financed_charge": {  
          "iof_amount": 1,
          "fee_amount": 0.5
	},  
	"installments": [  
		{  
			"installment_number": 1,  
			"total_amount": 11,  
			"principal_amount": 10,  
			"interest_amount": 1,
			"interest_rate": 0.1
		},  
		{  
			"installment_number": 2,  
			"total_amount": 11,  
			"principal_amount": 10,  
			"interest_amount": 1,  
			"interest_rate": 0.1
    }
   ]
}

Skip balance validation

By default, the Pismo platform performs account balance validation for installment operations. To skip account balance validation for installments, you can set the skip_balance_validation field to true, which forces the impact on the account's balance without checking the account limits.

In the following example, the account's global limit is 3,000.00 and the installments contract specifies 3 installments of 1,100.00. Since skip_balance_validation is true and the balance impact is forced, 3,300.00 in principal amount and 150.45 in fees and taxes is used for this installments operation for the total of 3,450.45. Global limit on the account remains 3,000.00. In this case, the call to check available limit on the account will return -450.45.

{  
	"charging_amount": 3450.45,  
	"processing_code": "00",  
	"descriptor": "Installments payment",  
	"account_id": 345,  
	"tracking_id": "123d4b5b-a7c1-494c-8f7b-06d36a28c0bf",  
	"skip_balance_validation": true,  
	"installments": [  
		{  
          "installment_number": 1,  
          "total_amount": 1150.15,  
          "principal_amount": 1100.00,
          "interest_amount": 50,
          "interest_rate": 0.1,
          "tax_amount": 0.15
		},  
		{  
          "installment_number": 2,  
          "total_amount": 1150.15,  
          "principal_amount": 1100.00,
          "interest_amount": 50,
          "interest_rate": 0.1,
          "tax_amount": 0.15
		}, 
    {  
          "installment_number": 3,  
          "total_amount": 1150.15,  
          "principal_amount": 1100.00,
          "interest_amount": 50,
          "interest_rate": 0.1,
          "tax_amount": 0.15
		}  
	]

Generated events

The Installments payment endpoint generates an authorization-event-1. The details field of the event contains the same array of installment objects that you send in the Installments payment request. For example:

{
    "cid": "test-installments-80605872",
    "timestamp": "2022-08-29T17:32:48Z",
    "org_id": "08102A0B-D4F8-42A2-8B0E-2052D05577D7",
    "domain": "authorization",
    "schema_version": "1",
    "event_type": "authorization-event",
    "data": {
        "amount": 22.3,
        "event_date": "2022-08-29T17:32:48.515",
        "authorization": {
            "id": 39787630,
            "code": "815958",
            "descriptor": "Test descriptor",
            "processing_code": "005000",
            "operation_description": "TRANSFER",
            "type": "INSTALLMENTS_PAYMENT",
            "account": {
                "id": 2
            },
            "card": {},
            "custom": {},
            "merchant": {},
            "available_change": {
                "id": "7154e307-b068-4af9-842e-116935091438",
                "update_datetime": "2022-08-29T17:32:48Z"
            }
        },
        "currency": "USD",
        "tracking_id": "b2163e26-ca87-4ec9-b6e9-76f2150359b7",
        "correlation_id": "test-installments-80605872",
        "location": {},
        "installments": {
            "number_of_installments": 2,
            "details": [
                {
                    "installment_number": 1,
                    "total_amount": 11.15,
                    "principal_amount": 10,
                    "interest_amount": 1,
                    "interest_rate": 0.1,
                    "tax_amount": 0.15
                },
                {
                    "installment_number": 2,
                    "total_amount": 11.15,
                    "principal_amount": 10,
                    "interest_amount": 1,
                    "interest_rate": 0.1,
                    "tax_amount": 0.05
                }
            ]
        }
    }
}

Manage installments on the customer statement

An installment advance is a transfer of one or more installments from future cycles/statements to the present cycle/statement, always in descending order (that is, transferring the last installments first).

Use the Create installment advance endpoint to advance installments. If you want to cancel the contract by advancing all installments, set mode to "all". If you want to advance a set number of installments (without canceling the contract), set mode to "single", and enter the number of installments that you want to advance in the installments_to_advancefield. When you execute the request, the operation transfers the installments to the current statement. You can then make an adjustment to settle the installments debt .

📘

If mode is set to "all", the installments_to_advance field is ignored. If mode is set to “single” and installments_to_advance is not filled, all transactions are advanced.

When an installment is advanced, the interest, if any, is released. The interest amount is returned as a credit (available limit) to the customer's account.

📘

The remove_interest_from_current field indicates whether the interest for the current statement should be released. The default value is "false". This field only applies when mode is set to "all". If mode is set to "single", the interest for the current statement cannot be released. Interest on future installments is always released when those installments are advanced.

Use the Cancel installments advance endpoint to cancel an advance. When an installment advance is canceled, the interest on the installment, if any, is reinserted, and the installment reverts to the original (future) cycle/statement.