Create a custom financial operation

Use this procedure to define the transactions generated by a custom operation, link them to a processing code, configure the corresponding reversal, and validate the completed configuration.

Prerequisites

Before you create a custom financial operation:

Create an authorization processing code for the operation.
Create and link a reversal processing code by providing reversal_processing_code when creating the original processing code.
If the operation supports partial reversals, you can optionally configure and link a partial-reversal processing code. If no partial-reversal processing code is provided, the platform uses the default processing code 000515 and transaction type 515 - PARTIAL CANCELLATION (key = PRINCIPAL, isCredit = true, posted_transaction = true).
Obtain API access and an authorization token for the Transactions Core endpoints.
Review Processing codes and transaction types, Payments configurations, and Create transaction flow for more information.

Sandbox base URL: https://sandbox.pismolabs.io/transactions-core

Define the operation strategy

Map the transaction types and flows before creating them. For each intended transaction, record its statement behavior, debit or credit direction, level, and amount source.

Identify each transaction the operation must generate, including separate principal, fee, interest, or tax transactions.
For installment operations, decide whether to create transactions for individual installments, the consolidated contract, or both.
Identify which transactions must appear on the account holder statement.
Confirm whether the processing code has debit, credit, or no-balance impact.
Check that aggregate amounts do not overlap with separately posted components.

Create the transaction types

Call Create transaction type once for each transaction defined in the operation strategy. The following examples create installment-level and contract-level transaction types.

Example: Create an installment-level transaction type

This example creates a debit transaction type for the individual installments generated by the operation.

Request

curl --request POST \
  --url https://sandbox.pismolabs.io/transactions-core/v1/transaction-types \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_bearer_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "transaction_type_id": 7777,
    "description": "INSTALLMENT",
    "credit": false,
    "posted_transaction": true
  }'

What the example means

This request creates transaction type 7777 with the following behavior:

credit is false, so the transaction type creates debit transactions.
posted_transaction is true, so transactions created from this transaction type appear on the account holder's statement.
For this installment operation, the transaction type operates at the installment level.
The Pismo platform creates one transaction for each installment when the transaction type is associated with a supported transaction flow.
For example, if an operation contains three installments, the Pismo platform creates three installment transactions when transaction type 7777 is associated with a transaction flow that uses key = INSTALLMENT.

Example: Create a contract-level transaction type

This example creates a debit transaction type for the consolidated contract generated by the operation.

Endpoint

Create transaction type

Request

curl --request POST \
  --url https://sandbox.pismolabs.io/transactions-core/v1/transaction-types \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_bearer_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "transaction_type_id": 8888,
    "description": "INSTALLMENT CONTRACT",
    "credit": false,
    "posted_transaction": false
  }'

What the example means

This request creates transaction type 8888 with the following behavior:

credit is false, so the transaction type creates a debit transaction.
posted_transaction is false, so transactions created from this transaction type do not appear on the account holder's statement.
For this installment operation, the transaction type operates at the contract level.
The Pismo platform creates one consolidated transaction for the contract when the transaction type is associated with a supported transaction flow.
For example, if an operation contains three installments, the Pismo platform creates one transaction representing the entire contract when transaction type 8888 is associated with a transaction flow that uses key = CONTRACT.

Create a transaction flow for each transaction type

Call Create transaction flow to associate each transaction type with the processing code and identify the authorization-provided amount used to create the transaction.

The following examples create transaction flows for the installment-level and contract-level transaction types.

Example: Create an installment-level transaction flow

This example associates transaction type 7777 with processing code 5566 and configures the flow to use the installment amount.

Request

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": "INSTALLMENT",
    "transaction_type_id": 7777,
    "processing_code": "5566"
  }'

What the example means

This request creates a transaction flow with the following behavior:

transaction_type_id associates the flow with transaction type 7777.
processing_code associates transaction type 7777 with processing code 5566.
key = INSTALLMENT instructs the Pismo platform to use the installment amount from the authorization data.
Transaction type 7777 uses posted_transaction = true, so the Pismo platform creates one transaction for each installment.

For example, if the authorization creates three installments of 100.00, the configuration generates:

Installment 1 transaction: 100.00
Installment 2 transaction: 100.00
Installment 3 transaction: 100.00

Each transaction represents an individual installment and can appear on the account holder's statement.

Example: Create a contract-level transaction flow

This example associates transaction type 8888 with processing code 5566 and configures it to use the total contract amount.

Request

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": "CONTRACT",
"transaction_type_id": 8888,
"processing_code": "5566"
}'

What the example means

This request creates a transaction flow with the following behavior:

transaction_type_id associates the flow with transaction type 8888.
processing_code associates transaction type 8888 with processing code 5566.
key = CONTRACT instructs the Pismo platform to use the total contract amount from the authorization data.
Transaction type 8888 uses posted_transaction = false, so the Pismo platform creates one contract-level transaction rather than one transaction per installment.

For example, if the three-installment operation has a total contract amount of 300.00, the configuration generates:

Contract transaction: 300.00

The transaction represents the entire contract and does not appear or have impact on the account holder's statement.

Create the corresponding contract flow by linking transaction type 8888 to the same processing code with key = CONTRACT.

Custom amounts

To create a transaction from a custom amount, set key to OTHER and provide custom_key.

For example, a fee model with the ID fee_12345 can expose the amount as fee_12345Amount. In that case, configure the flow with key = OTHER and custom_key = fee_12345Amount.

Confirm that the selected custom_key resolves to the monetary amount that the transaction flow should use. A custom key generates transactions only when the authorization data contains that key.

Transaction type created event

Creating a transaction type generates the Transaction type created event.

The event payload includes:

transaction_type_id
description
credit
posted_transaction

Use this event to monitor transaction-type creation and synchronize downstream systems.

Validate the original configuration

Call List transaction types. Confirm that every intended transaction type exists and uses the expected credit and posted_transaction values.
Call List transaction flows. Filter by processingCode and transactionTypeId to confirm each mapping and selected amount key.
Check the minimum configuration. For an installment operation, include a non-posted CONTRACT or PRINCIPAL flow and a posted INSTALLMENT or PRINCIPAL flow.
Check for overlaps. Do not post an aggregate amount together with separately posted principal, interest, tax, or fee components already included in that amount.
If a key or custom_key is wrong, call Update transaction flow instead of creating a duplicate mapping.

Configure the reversal processing code

Create matching transaction types and flows for the reversal processing code.

Reversal requirements

Create the same number of reversal transaction types as the original processing code.
Use the same flow key and corresponding custom_key for each pair.
Invert the credit value. For example, an original debit transaction type with credit = false requires a reversal transaction type with credit = true.
Keep the same posted_transaction value as the corresponding original transaction type.

Example: Configure matching original and reversal transaction flows

In this example:

Processing code INST01 represents the original installment purchase operation.
Processing code INST99 represents the reversal operation.
Transaction type 7710 generates one posted transaction per installment using key = INSTALLMENT.
Transaction type 7711 generates a single non-posted contract transaction using key = CONTRACT.
Transaction types 7712 and 7713 mirror the original transaction types for the reversal processing code, with the credit value inverted.

Transaction flows created

Original operation (INST01):

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 '{
    "processing_code": "INST01",
    "transaction_type_id": 7710,
    "key": "INSTALLMENT"
  }

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 '{
    "processing_code": "INST01",
    "transaction_type_id": 7711,
    "key": "CONTRACT"
  }

Reversal operation (INST99):

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 '{
    "processing_code": "INST99",
    "transaction_type_id": 7712,
    "key": "INSTALLMENT"
  }

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 '{
    "processing_code": "INST99",
    "transaction_type_id": 7713,
    "key": "CONTRACT"
  }

If a 3-installment purchase is authorized using processing code INST01, the configuration generates:

Three installment transactions (7710), one for each installment, posted on the statement.
One contract transaction (7711) containing the total contract amount, not posted on the statement.

If the purchase is later cancelled, the Pismo platform uses the reversal processing code configuration to generate corresponding reversal transactions (7712 and 7713) and accounting entries.

Verify the completed configuration

After configuring the transaction types, transaction flows, and reversal processing code, verify that the completed configuration behaves as expected.

Verify transaction types

Use List transaction types to confirm that:

The expected transaction types were created successfully.
The transaction types use the expected credit values.
The transaction types use the expected posted_transaction values.

Verify transaction flows

Use List transaction flows to confirm that:

Transaction flows exist for the configured processing codes.
The expected transaction types are associated with each processing code.
The expected key or custom_key values are configured.

Verify installment configurations

For installment operations, confirm that:

At least one transaction flow uses CONTRACT or PRINCIPAL on a non-posted transaction type.
At least one transaction flow uses INSTALLMENT or PRINCIPAL on a posted transaction type.
Installment-level and contract-level transactions are generated as expected.

Verify reversal configurations

Confirm that the reversal processing code:

Contains the same number of transaction types as the original processing code.
Uses the same key or custom_key values as the original configuration.
Uses the inverse credit value for each corresponding transaction type.
Uses the same posted_transaction values as the original transaction types.

Verify generated transactions

Test representative authorization and reversal scenarios and confirm that:

The expected transactions are generated.
Duplicate financial effects do not occur.
The generated Transaction created events match the expected transaction behavior.

Verify processing-code status

Confirm that the custom processing code status changes from PENDING to SUCCESS.

Next steps

After verifying the completed configuration:

Configure the accounting mappings for the transaction types. For instructions, see Accounting overview.
Repeat the verification process in the target environment.
Move the configuration to production after completing testing and verification.

Create a custom financial operation

Prerequisites

Define the operation strategy

Create the transaction types

Example: Create an installment-level transaction type

Request

What the example means

Example: Create a contract-level transaction type

Endpoint

Request

What the example means

Create a transaction flow for each transaction type

Example: Create an installment-level transaction flow

Request

What the example means

Example: Create a contract-level transaction flow

Request

What the example means

Transaction type created event

Validate the original configuration

Configure the reversal processing code

Reversal requirements

Example: Configure matching original and reversal transaction flows

Transaction flows created

Verify the completed configuration

Verify transaction types

Verify transaction flows

Verify installment configurations

Verify reversal configurations

Verify generated transactions

Verify processing-code status

Next steps

Related topics

Changelog

Support

Pismo is here to help