---
updatedAt: 2026-08-06T20:43:32.000Z
---

Fetch the complete documentation index at: https://developers.pismo.io/pismo-docs/llms.txt. Use this file to discover all available pages before exploring further.

# Creating payment agreements with custom transactions

When you create a payment agreement, you can associate it with a transaction flow using custom transactions. The following table lists the processing codes you should use for this feature. They are default codes for the platform.

| Processing code | Description             | **Undo processing code** | **Description**                |
| :-------------- | :---------------------- | :----------------------- | :----------------------------- |
| 005091          | REFINANCING INSTALLMENT | 005095                   | CANCEL REFINANCING INSTALLMENT |
| 005092          | AGREEMENT INSTALLMENT   | 005096                   | CANCEL AGREEMENT INSTALLMENT   |
| 005093          | COMPULSORY INSTALLMENT  | 005097                   | CANCEL COMPULSORY INSTALLMENT  |

When additional transactions need to be created as part of a payment agreement, such as insurance, fees, or other auxiliary charges, the integration must follow a two‑step configuration process. This ensures that the Pismo platform properly generates the additional transactions and links them to the agreement lifecycle.

# Step 1: Create a transaction flow using a custom key

First, define a transaction flow for the additional transaction type using the [Create transaction flow ](https://developers.pismo.io/pismo-docs/reference/posttransactionflow) endpoint. The `custom_key` serves as a unique identifier for this custom transaction flow. You reference it when you create the payment agreement in Step 2.

<Callout icon="📘" theme="info">
  In Step 1, the value for `custom_key` must have an "Amount" suffix. For example: `Insurance01Amount`. In Step 2, you must remove the suffix from this value before passing it in the `custom_key`field of the`custom_transactions` objects: `Insurance01`.
</Callout>

## Example: Create a transaction flow for the agreement installment using processing code 005092

In this example:

* The `custom_key` (`Insurance01Amount`) identifies the transaction flow. It must end in "Amount".
* This flow defines how the custom transaction is created and processed.

```curl
curl --request POST \ 
     --url https://sandbox.pismolabs.io/transactions-core/v1/transaction-flow \ 
     --header 'Accept: application/json' \ 
     --header 'Authorization: Bearer <your_bearer_token>' \ 
     --header 'Content-type: application/json' \ 
     --data ' 
{ 
  "key": "OTHER", 
  "transaction_type_id": 10000, 
  "processing_code": "005092", 
  "custom_key": "Insurance01Amount" 
}'
```

# Step 2: Associate the custom key when creating the payment agreement

Use the [Create payment agreement ](https://developers.pismo.io/pismo-docs/reference/installmentpaymentsv4) endpoint to create the payment agreement. Remove the "Amount" suffix from the value that you used for `custom_key`in Step one, and use the resulting value for the `custom_key` fields in the `custom_transactions` objects of the request. You should use a different value for the `custom_key` fields  in the `custom_contract_transaction` object.

## Example: Create payment agreement with custom transactions

In this example:

* `Insurance01` is used in the `custom_key` field of each `custom_transactions`object (instead of `Insurance01Amount`).
* A new value, `Insurance02`, is used in the `custom_key` field of the `custom_contract_transaction` object.
* The transaction created from the `custom_contract_transaction` field can represent any value you choose as long **as it does not exceed the total contract amount**. It appears on the current statement, but does not impact the balance or limit.
* The `custom_transactions` array lists transactions associated with installments, which appear on the statements. (`posted_transaction` = `true` in the [transaction types](https://developers.pismo.io/pismo-docs/docs/transactiontypes).)
* As a result, the Pismo platform automatically creates and manages the insurance transactions associated with `Insurance01` as part of the payment agreement.

```curl
curl --request POST \ 
     --url https://sandbox.pismolabs.io/statements/v4/accounts/accountId/installment-payments \ 
     --header 'accept: application/json' \ 
     --header 'authorization: Bearer <your_bearer_token>' \ 
     --header 'content-type: application/json' \ 
     --data '
{
  "statement_agreement": true,
  "compulsory": false,
  "settle_accrual": false,
  "split_iof": false,
  "use_original_rate": false,
  "custom_contract_transaction": {
    "custom_key": "Insurance02",
    "amount": 100
  },
  "installments": [
        {
            "installment_number": 1,
            "description": "first installment",
            "total_amount": 604.55,
            "principal_amount": 541.00,
            "interest_rate": 18.00,
            "interest_amount": 50.00,
            "iof_amount": 10.00,
            "daily_iof_amount": 0.00,
            "custom_transactions": [
                {
                    "amount": 3.55,
                    "custom_key": "Insurance01"
                }
            ]
        },
        {
            "installment_number": 2,
            "description": "second installment",
            "total_amount": 604.55,
            "principal_amount": 541.00,
            "interest_rate": 18.00,
            "interest_amount": 50.00,
            "iof_amount": 10.00,
            "daily_iof_amount": 0.00,
            "custom_transactions": [
                {
                    "amount": 3.55,
                    "custom_key": "Insurance01"
                }
            ]
        }
  ]
}
```