Installments payment

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.

FieldDescription
processing_codeUnique alphanumeric identifier.
descriptionDescription for this operation.
balance_impactUse 1 for credit/cash-in operations, -1 for debit/cash-out operations, and 0 for operations that don't impact balance.

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. For example, you could use the following sample code to create two installments:

{
    "charging_amount": 22.30,
    "processing_code": "005000",
    "descriptor": "Test descriptor",
    "tracking_id": "2a1ea2f6-97fb-4738-97f4-d25ac88713a1",
    "account_id": 1,
    "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"
}

Generated events

The Installments payment endpoint generates an Authorization event. 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": "TRANSFERENCIA",
            "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": "BRL",
        "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
                }
            ]
        }
    }
}

Management of 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.