Custom financial operations overview

A custom financial operation combines a processing code, one or more transaction types, and transaction flows. Together, these objects determine which transactions the Pismo platform creates after authorization, which amounts those transactions use, whether they affect balances, and whether they appear on an account holder statement.

During synchronous authorization, the Pismo platform uses the processing code for authorization validations. It creates transactions asynchronously from the configured transaction types and flows. For dual-message operations, transaction creation occurs after the corresponding confirmation.

Configuration model

A custom financial operation uses the following configuration objects:

• Processing code: Identifies the financial operation and its authorization behavior. It also identifies the linked reversal processing code.
• Transaction type: Defines a generated transaction, its debit or credit direction, whether it has a financial impact, and whether it appears on the statement.
• Transaction flow: Links a transaction type to a processing code and selects the authorization-provided amount through key or custom_key.

Transaction creation and generated events

A processing code can have multiple transaction types associated with it. As a result, a single authorization can create multiple transactions.

For example, an operation can generate:

• A principal transaction
• A contract transaction
• A fee transaction
• A tax transaction

Each generated transaction publishes a Transaction created event that downstream consumers can use for processing, reconciliation, and integration workflows.

Transaction levels

For installment operations, the posted_transaction value on a transaction type determines the transaction level:

• posted_transaction = true: Installment level. The Pismo platform creates one transaction for each installment that contains the selected amount.
• posted_transaction = false: Contract level. The Pismo platform creates one consolidated transaction for the contract.

Non-installment, single-payment operations do not have installment and contract levels. Each transaction type creates no more than one transaction, regardless of posted_transaction.

How the Pismo platform retrieves transaction amounts

Transaction flows determine which amount from the authorization data is used to create a transaction. The Pismo platform uses values already available in the authorization payload to determine principal, installment, contract, interest, tax, fee, or other amounts.

For installment operations:

• When posted_transaction = true, the Pismo platform retrieves the selected amount from each installment object and creates one transaction for each installment that contains that amount.
• When posted_transaction = false, the Pismo platform uses the total amount associated with the selected amount type at the contract level and creates a single contract-level transaction.

A common installment configuration contains a posted transaction type for each installment and a non-posted transaction type for the consolidated contract. For an installment operation, at least one non-posted flow must use CONTRACT or PRINCIPAL.

For example:

• A transaction flow that uses key = INSTALLMENT and a transaction type with posted_transaction = true creates one transaction for each installment.
• A transaction flow that uses key = CONTRACT and a transaction type with posted_transaction = false creates a single transaction for the entire contract.

The following keys identify the amount used to create a transaction:

• PRINCIPAL: Selects the principal amount and excludes interest, fees, and other charges. Use it to record or post the financed principal.
• INSTALLMENT: Selects the full installment amount, including applicable charges. Use it to create one posted transaction per installment.
• CONTRACT: Selects the total contract or operation amount, including applicable charges. Use it to create a consolidated contract transaction.
• OTHER with custom_key: Selects a named custom amount supplied by the authorization payload, such as interestAmount. Use it to create a separate transaction for a fee, tax, interest, or other charge.

Fee-model considerations

Custom amounts sourced from fee models are available only when the fee model is linked to an account or program.

For example, a fee model with the identifier fee_12345 can expose an authorization amount such as fee_12345Amount. A transaction flow can reference that amount by using:

{
  "key": "OTHER",
  "custom_key": "fee_12345Amount"
}

Reversal model

The reversal processing code mirrors the original configuration. It uses:

• The same number of transaction types
• The same flow keys and custom keys
• The same posted_transaction values
• The inverse credit value for each corresponding transaction type

This configuration enables cancellation to create the opposite financial effect.

Cancellation and reversal processing

During cancellation, the authorization request must submit or reference the original authorization operation as required by the authorization API.

The Pismo platform then:

1. Applies the opposite authorization-level impact.
2. Uses the reversal processing code linked to the original processing code.
3. Determines the reversal transactions from the reversal transaction flows.
4. Creates the corresponding accounting entries.

Because reversal transaction types use the same transaction-flow structure as the original configuration, cancellation generates a matching set of reversal transactions and accounting entries.

Duplicate financial effects

Overlapping flows can generate unintended transactions or accounting entries. For example, a posted INSTALLMENT transaction already includes applicable interest. Adding a second posted OTHER flow for interestAmount can represent that interest again.

Map transaction types and amount selections before configuration, then review the complete operation for overlap.

Best practices

Design a map of transaction types and transaction flows before creating them. For each transaction type, record:  

• level (installment or contract — for installment operations)

• posted_transaction value

• Associated key or custom_key  

Check for overlaps. Verify whether more than one transaction type uses the same combination of:

• Transaction level

• Amount type, such as PRINCIPAL, INSTALLMENT, CONTRACT, or custom_key

• Statement-posting behavior and accounting mapping  

Verify the completed configuration:  

• Use List transaction types and List transaction flows, filtering by processingCode and transactionTypeId, to review the mappings between processing codes and transaction types.  

Correct an existing flow instead of creating a duplicate:

If a transaction flow is configured incorrectly or is no longer needed, it cannot be deleted. Instead, use one of the following options:

1. Update the existing flow.
   • Modify the existing transaction flow and replace it with the correct configuration.
   • See the example in How the Pismo platform retrieves transaction amounts for guidance.
2. Create a new processing code.
   • Create a new processing code with the correct transaction type and transaction flow configuration.
   • Use the new processing code for future transactions.
3. Invalidate the existing transaction flow.
   • To prevent transactions from being created for a specific processing code and transaction type, update the flow configuration as follows:
     • key = OTHER
     • custom_key = INVALID (or another invalid fee identifier)

Example

key = OTHER
custom_key = INVALID

After this change, no transactions will be created for the associated Processing Code and Transaction Type, effectively disabling the transaction flow.

Example use case

An installment purchase can use processing code INST01 with transaction type 7710 for each installment and transaction type 7711 for the consolidated contract. A linked reversal code, INST99, uses transaction types 7712 and 7713 with matching flow keys and inverted credit values.

A three-installment authorization then produces three installment transactions and one contract transaction. Cancellation produces the corresponding reversal transactions.

Related topics

• Create a custom financial operation
• Custom financial operation configuration reference
• Processing codes and transaction types
• Transaction types
• Accounting overview