📘

This guide provides an overview of Pismo’s new Discharge and Payment Hierarchy architecture, which is currently available exclusively in the EXT environment. To ensure backward compatibility, the default payment hierarchy maintains the original platform behavior. The sections below describe this behavior and outline the available configuration options supported by the new architecture.

The discharge process is the process that applies credit balances (payments, refunds, and adjustments) to outstanding debit transactions, following a defined order and eligibility logic. The process follows these steps.

1. A credit arrives (payment, refund, or internal adjustment).

2. The Pismo platform selects eligible debit transactions.

3. The platform orders those debits according to a configured payment hierarchy.

4. The platform applies the credit sequentially until it's exhausted or no more debits remain.

When a debit transaction is fully discharged, it's considered to be paid in full or paid off.

📘

The discharge process described here applies to the standard credit-cycle payment flow. Delinquency buckets have their own internal discharge order that is independent of this process.

The discharge process runs on the following occasions.

• When the platform receives a credit transaction. The discharge process finds eligible debit transactions with a balance due and begins paying them off one by one, according to the payment hierarchy, until the credit amount is used up or no eligible debits remain. If the credit amount is greater than the total eligible debits, the remainder constitutes a credit balance on the account. This balance gets applied to any future debits.
• When the platform receives a debit transaction from the customer (a purchase), and the account has an available credit balance. In this scenario, the Pismo platform uses any available credit to offset the new debit, partially or fully, depending on the debit and credit balance available. In this case, the Pismo platform does not run the entire discharge process—it just applies available credit to the new debit.
• Immediately before closing the credit cycle. Some debits, such as fees, don't come from the customer and don't directly trigger the discharge process, so an account could still have both a credit balance and unpaid debits at the end of a cycle. For this reason, the Pismo platform triggers the discharge process immediately before closing the credit cycle.

🚧

In times of high load, there could be a delay before the platform uses a payment to discharge transactions. You should take this into account when designing your credit program.

Payment hierarchy

The payment hierarchy is the set of rules the Pismo platform uses to determine the order in which unpaid transactions are paid off by the discharge process. The following section describes the default configuration for the payment hierarchy. Later sections explain how you can modify the default configuration to better meet your company's needs.

Default payment hierarchy

Under the default payment hierarchy, the discharge engine divides transactions into the following groups.

• Group 1—Overdue transactions
• Group 2—Transactions from the previous cycle that are not yet overdue
• Group 3—Transactions from the current credit cycle

Group 1 transactions are fully discharged first, then group 2, and finally group 3. Note that Groups 1, 2, and 3 correspond to the DebitType dimension sub-orders Overdue, ClosedNotDue, and Current, respectively, in the Custom payment hierarchies section.

Within each group, the order in which transactions are paid off is determined by their charge orders and their real due dates. For more information about the charge order, refer to Managing the charge order for debit transactions.

The transactions within each group are paid off according to the following rules. Each rule corresponds to one of the ordering dimensions in the Custom payment hierarchies section.

• Transactions with the lowest charge orders, as defined in their associated program transaction types, are discharged first. This corresponds to the ProgramTransactionType ordering dimension.
• Transactions with the oldest due dates are discharged next. This corresponds to the StatementDueDate ordering dimension.
• Transactions with the lowest charge orders, as defined in their associated program transaction categories, are paid off next. Charge orders configured in program transaction types override charge orders configured in program transaction categories. This corresponds to the TransactionCategory ordering dimension.
• Any remaining transactions are discharged last, in the order of their transaction event dates. The transaction event date is the date on which the transaction occurred, and it's returned in the event_date field of the Get transaction endpoint. This corresponds to the TransactionDate ordering dimension.

📘

An exception to the above rules can occur when a purchase is canceled. When a cardholder makes a purchase, the resulting debit transaction has an authorization ID (authorization_id). Canceling a purchase generates a credit transaction for the same amount and with the same authorization ID. In this case, the debit transaction has priority and is discharged before any other transactions.

In other words, when a credit transaction has the same authorization ID as a debit transaction, the debit transaction has priority over other transactions. This behavior is captured by the OriginalDebit dimension, placed first in the default hierarchy.

Custom payment hierarchies

The default payment hierarchy applies automatically. To create a custom payment hierarchy, follow these steps.

1. Contact your Pismo representative to review the target discharge behavior and validate it against your market and regulatory context.
2. Define the PaymentHierarchy object. To do this, pick the ordering dimensions you need and the sub-order values for DebitType if applicable.
3. Wrap the PaymentHierarchy object in a DischargeConfiguration object.
4. Create a Service Desk Configuration ticket requesting the change. Your Pismo representative can help you fill out the appropriate fields. By default, a payment hierarchy applies to the all the accounts in a program. If you want the new hierarchy to apply to a specific account, be sure to let your representative know. For more information, refer to Account-level configuration. The Pismo team reviews the requested configuration and validates the applicable scope before applying it.

Ordering dimensions

The Pismo platform uses ordering dimensions to determine which debits should be paid off first. The ordering dimension appears in the PaymentHierarchy object as dimension. Set it to one of the following values.

DebitType suborder types

The DebitType dimension supports explicit sub-ordering because debit lifecycle state is not inherently sortable without business context.

DischargeConfiguration object

The DischargeConfigurationobject binds a scope to a discharge strategy and to exactly one payment hierarchy.

PaymentHierarchy object

The PaymentHierarchy JSON object defines the ordered list of dimensions that the discharge engine applies. Each ordering entry has an order (lower values have higher priority) and, when supported, an optional suborder.

The following JSON code shows how the default PaymentHierarchy object is configured internally. Use this as a reference when creating a custom payment hierarchy.

{ 
  "Ordering": [ 
    { "order": 1, "dimension": "OriginalDebit" }, 
    { 
      "order": 2, 
      "dimension": "DebitType", 
      "suborder": { "Overdue": 1, "ClosedNotDue": 2, "Current": 3 } 
    }, 
    { "order": 3, "dimension": "ProgramTransactionType" }, 
    { "order": 4, "dimension": "StatementDueDate" }, 
    { "order": 5, "dimension": "TransactionCategory" }, 
    { "order": 6, "dimension": "TransactionDate" } 
  ] 
}

📘

Although the schema stores PaymentHierarchy as a list, only one hierarchy is active per scope at a time, and the hierarchy never changes mid-discharge.

Configuration resolution order

When a credit event arrives, the discharge engine resolves the hierarchy in the following order.

1. Account-level configuration—If an account-level configuration exists for the account and Enabled = true, use its payment hierarchy.

2. Program-level configuration—Otherwise, if a program-level configuration exists, use its payment hierarchy.

3. Default payment hierarchy—If no enabled account-level or program-level configuration exists, or the referenced hierarchy is missing or invalid, use the default payment hierarchy.

Account-level configuration

The account scope allows an individual account to use a payment hierarchy that overrides the program-level payment hierarchy.

To configure a payment hierarchy for a specific account, first configure the Secondary Charge Order for the account, as described in the Managing the charge order for debit transactions guide.

Next, define the SecondaryChargeOrder dimension n the PaymentHierarchy object. For example:

{
  "Ordering": [
    {
      "order": 1, "dimension": "OriginalDebit"
    },
    {
      "order": 2, "dimension": "SecondaryChargeOrder"
    },
    {
      "order": 3, "dimension": "StatementDueDate"
    },
    {
      "order": 4, "dimension": "TransactionDate"
    }
  ]
}

Finally, just as for a program-level configuration, get your Pismo representative to help you open a Service Desk ticket to implement the configuration. Make sure you explain to your representative that the configuration is for a specific account and provide them with the ID for that account.

SecondaryChargeOrder dimension

The SecondaryChargeOrder dimension makes the category's secondary_charge_order value available as an explicit hierarchy entry, so it can be composed with the other dimensions in the payment hierarchy. Use SecondaryChargeOrder when the payment hierarchy must prioritize transaction categories by their secondary_charge_order value.

Categories that have no secondary_charge_order value sort last, which keeps behavior predictable when only a subset of categories is configured.

Examples of how the discharge process works

The following examples assume the default discharge configuration. This behavior can vary considerably if you use a custom configuration.

Applying the discharge process in a simple example

The following example shows how the discharge process works in the simplest case.

The cardholder makes a purchase:

Later, the cardholder makes a payment:

The Pismo platform performs a discharge. It deducts the balance of transaction 2 from the balance of transaction 1:

The balance for the payment transaction is $0.00. If the payment had been for more than $50.00, then the payment transaction would have been left with a non-zero balance. This remaining balance would be deducted from any future purchases.

Applying the discharge process in a more complex example

The following example shows how the discharge process works in a more complex case where the debit transaction is associated with a program transaction category.

Suppose you have a program transaction category that defines charge orders for fineable and non-fineable transactions as follows:

Suppose you have transaction types defined for purchase transactions and interest transactions and those types are associated with program transaction categories (via program transaction types) as follows:

Now suppose you have the following transactions:

When the account receives a credit, the Pismo platform discharges the transactions in the following order:

1. B (because A and B are in an overdue statement, but the category of transaction B has a charge order lower than the category of transaction A.)
2. A (because transaction A is in an overdue statement and transaction C is not.)
3. C