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.

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

📘

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_keyfield of thecustom_transactions objects: Insurance01.

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 --request POST \ 
     --url https://sandbox.pismolabs.io/transactions-core/v1/transaction-flow \ 
     --header 'accept: application/json' \ 
     --header 'authorization: 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 endpoint to create the payment agreement. Remove the "Amount" suffix from the value that you used for custom_keyin 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_transactionsobject (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.)
• As a result, the Pismo platform automatically creates and manages the insurance transactions associated with Insurance01 as part of the payment agreement.

curl --request POST \ 
     --url https://sandbox.pismolabs.io/statements/v4/accounts/accountId/installment-payments \ 
     --header 'accept: application/json' \ 
     --header 'authorization: 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"
                }
            ]
        }
  ]
}