--- title: "Create payment agreement" method: POST path: "/statements/v4/accounts/{accountId}/installment-payments" tags: ["Refinancing"] --- # Create payment agreement `POST /statements/v4/accounts/{accountId}/installment-payments` ## Request - Base URL: `https://sandbox.pismolabs.io` - URL: `https://sandbox.pismolabs.io/statements/v4/accounts/{accountId}/installment-payments` - Auth: HTTP bearer Create a payment agreement and post the refinanced debt as new installment transactions, beginning from the currently open statement. The `statement_agreement` and `compulsory` flags are used to specify the transaction types of the transactions that are created on the customer's statement. Here are the possible combinations. Type of payment agreement: Statement agreement Description: The customer renegotiates all debt for all their statements. `statement_agreement`: true `compulsory`: false Transaction types of transactions: 712 (INSTALLMENT AGREEMENT) 711 (CREDIT BY AGREEMENT) 713 (CONTRACT AGREEMENT) Type of payment agreement: Installment agreement Description: This an agreement that the customer makes with their credit card issuer stating that they aren't able to pay off their debt within the current month, so they intend to settle the amount over the next few bills. In other words, the amount that remains outstanding is added to their statement for the following month. `statement_agreement`: false `compulsory`: false Transaction types of transactions: 702 (REFINANCING INSTALLMENT) 701 (INSTALLMENT CREDIT) 703 (REFINANCING CONTRACT) Type of payment agreement: Compulsory agreement Description: This is the same as an installment agreement, except that it's the result of a renegotiation that was made independently of the customer. This is mandatory in Brazil, due to a measure initiated by the Central Bank to protect customers from revolving credit interest charged on the unpaid amount of the invoice. According to this measure, after 30 days, the bank or financial institution must offer more advantageous conditions for the customer to pay off the debt. In practice, the amount owed is automatically divided into installments, allowing the user to fit the payment of the debt into their monthly budget. `statement_agreement`: false `compulsory`: true Transaction types of transactions: 722 (CP REFINANCING INSTALLMENT) 721 (CP INSTALLMENT CREDIT) 723 (CP REFINANCING CONTRACT) Notes: - The installment transactions for the refinanced debt have transaction type `REFINANCING AGREEMENT`. - The following combination is not valid. It returns the error message "A compulsory request requires the statement agreement field to be set to false." `statement_agreement`: true `compulsory`: true - After the installments are created, the Pismo platform asynchronously generates an [Installment payment processed](https://developers.pismo.io/events/docs/balance-installment-payment-processed-1) event. You should not try to access the new payment agreement until you receive this event. ## Path parameters - `accountId` integer, required ## Headers - `Authorization` string, required ## Request body - InstallmentPaymentsV4Request: Installment Payments request (v4) - `statement_agreement` boolean, required: Is the generated agreement a statement agreement (`true`) or an installment agreement (`false`)? - `installments` object[], required: Installment payments. Note: You must define at least 2 installment payments. - `installment_number` integer, required: Installment number - `total_amount` number, float, required: Sum of this installment's principal amount with its interest and fees. Maximum of 2 digits allowed after the decimal place. - `principal_amount` number, float, required: Principal amount. Maximum of 2 digits allowed after the decimal place. - `interest_amount` number, float, required: Interest amount. Maximum of 2 digits allowed after the decimal place. - `interest_rate` number, float, required: Installment's interest rate - `iof_amount` number, float, required: IOF (Brazilian tax) amount. Maximum of 2 digits allowed after the decimal place. - `daily_iof_amount` number, float: Daily IOF (Brazilian tax) amount for installment. Maximum of 2 digits allowed after the decimal place. - `description` string: Optional description for this installment transaction - `custom_transactions` object[]: Allows to register a separate custom contract transaction - `custom_key` string: Key for the custom transaction. - `amount` number, float: Amount for the custom transaction. - `compulsory` boolean: Is the generated agreement a compulsory agreement (`true`) or not (`false`)? - `settle_accrual` boolean: Is the generated agreement settled to accrual (`true`) or not (`false`)? If `true`, pending accruals are included when calculating the refinanced amount. - `split_iof` boolean: Should IOF be split? If `true`, the Pismo platform generates a separate transaction for the IOF tax. - `use_original_rate` boolean: Set to `true` if the original installment rate should be used to generate accruals. Set to `false`, otherwise. The original installment rate is the payment agreement contract interest rate. So, if this field is set to `true`, this rate is used instead of the transaction category interest rate when a payment agreement installment is due. - `payment_datetime` string, date-time: Date/time of the down payment. Format = YYYY-MM-DDThr:mm:ss. This field may represent the payment date for the down payment. When provided, this date is used as the transaction event date for credit and installments. - `credit_transaction_description` string: Credit Transaction Description field is up to 100 characters. - `metadata` MetadataPaymentAgreementV4: This is a JSON object converted to a string with additional information relevant to the customer. No business rule validation is performed on it. **Note**: This field must not be used to send Personally Identifiable Information (PII), Payment Card Industry (PCI) data, or any sensitive/regulated information. Metadata fields are intended for operational, non-sensitive data only. For sensitive data, use the specific parameters designed for that purpose. For more information, refer to [Get started with Pismo APIs](ref:get-started-with-pismo-apis). - `custom_contract_transactions` object[]: Allows to register a separate custom contract transaction - `custom_key` string: Key for the custom transaction. - `amount` number, float: Amount for the custom transaction. ## Response `201` Created - InstallmentPaymentsV4SuccessResponse - `id` integer: Payment agreement ID - `statement_agreement` boolean: Is the generated agreement a statement agreement (`true`) or an installment agreement (`false`)? - `compulsory` boolean: Is the generated agreement a compulsory agreement (`true`) or not (`false`)? - `settle_agreement` boolean: Is the generated agreement settled (`true`) or not (`false`)? - `split_iof` boolean: Should IOF be split? If `true`, the Pismo platform generates a separate transaction for the IOF tax. - `created_at` string: Creation date/time. Format = yyyy-mm-ddThh:mm:ss. ## Other responses - `400`: Bad request - `404`: Not Found - `423`: Locked - `500`: Internal Server Error --- [API](https://skmtc.dev/pismo/apis/revolving-credit-statements.md) - [All operations](https://skmtc.dev/pismo/apis/revolving-credit-statements/llms.txt) - [OpenAPI document](https://skmtc.dev/pismo/apis/revolving-credit-statements/revisions/09f552b0f850?raw)