Configuration planning

Before you configure creditor operations, you must define the transaction classifications and financial conditions that Seller management must apply.

Prerequisites

Before a creditor operation can be used, confirm the following:

• The marketplace exists and belongs to your organization.
• The merchant exists and is linked to the marketplace.
• The merchant's status allows transacting.
• The processing code is registered.
• A creditor operation exists for that processing code and installment count. Refer to Installments for more information.
• MDR tax is configured for the marketplace.
• For settlement into a Pismo account, the creditor's crediting method is set to ACCOUNT with an account associated. Refer to Update creditor for more information.

For the complete onboarding sequence, refer to Seller management onboarding and Prerequisites for merchant transactions.

Define creditor operation rules

Define the settlement timing, installment treatment, transfer timing, fees, and processing codes for each transaction. Map each transaction type to the applicable processing code, marketplace, merchant, and creditor context.

Creditor operations depend on these configuration elements.

Settlement rules

Settlement rules define when Seller management schedules funds for payment to the creditor account and how it processes settlement after transaction evaluation.

Timing

When work_days is false, the scheduled payment date of installment i is:

scheduled_payment_date = event_date
                       + first_installment_days_to_payment
                       + (i − 1) × n_installment_days_to_payment

Matched settlement

Matched settlement (matched_settlement) indicates whether this is a matched settlement. A matched settlement is paid in several batches; false indicates the full amount is paid in one single payment. Default false.

Installments

The installment count is the number of installments in a sale. It appears as installments in the Create merchant transaction request and as number_of_installments in the merchant transaction response.

Each creditor operation applies to sales with one specific installment count. A sale requires only one creditor operation, regardless of how many installments it has. For example, a USD 200 sale with processing code 003000 in 3 installments requires a single creditor operation with processing_code: 003000 and installments: 3, not one creditor operation for each of the three installments. The payment dates and charges of all three installments are derived from that single operation.

To accept sales with different installment counts under the same processing code, configure one creditor operation for each count you accept. For example, to accept sales of one to six installments, configure operations for installment counts 1 through 6. The Create marketplace creditor operations endpoint creates one creditor operation for each merchant and each installment entry in the request.

Installment count affects:

• Payment timing
• Fee application
• Receivables schedule generation

Rates, fees, and discounts

Creditor operations require you to define the financial conditions that determine the net settlement amount. The applicable rates and fees depend on the transaction's processing code and installment count. Fees reduce the gross transaction value to determine the net amount scheduled for payment.

Merchant Discount Rate (MDR)

The Merchant Discount Rate (MDR) is the rate charged to a merchant for payment-processing services. Seller management deducts the MDR from the gross transaction amount when it calculates the net receivable.

Matched MDR

Matched MDR (matched_mdr) indicates whether the Merchant Discount Rate (MDR) is matched. When false, the fixed transaction fee and the MDR amount are applied only to the first installment. Default false.

Custom fees

In addition to the MDR and the fixed transaction fee (transaction_fee), a creditor operation can carry any number of percentage-based or fixed custom fees in its fees array. Marketplace fees, which compensate the marketplace and are deducted during transaction processing, are one example.

{
  "fees": [
    { "name": "EMISSION_FEE", "value": 1.5 },
    { "name": "MAINTENANCE_FEE", "value": 0.01 }
  ]
}

Both name (the fee model name) and value are required. The value's meaning depends on the fee model: usually a percentage (for example, 0.05 for 5%) or a fixed amount (for example, 1.5 for a fixed fee of 1.5 currency units).

MDR tax

MDR tax is configured per marketplace, separately from the creditor operation, as a set of ranges by transaction amount. Each range defines minimum_transaction_amount, maximum_transaction_amount, fixed_tax, and percentage_tax. Submitting the Create MDR tax information request replaces the entire set of ranges. For an example, refer to Step 3: Configure creditor operations.

Deductions and advancement discounts

"Discount" refers to two different things in Seller management:

• Deductions: The MDR, fixed transaction fee, and custom fees that reduce the gross transaction amount to the net amount scheduled for payment.
• Advancement discount: The discount rate applied when receivables are advanced before their scheduled payment date. Refer to Advancement terms for more information.

Note: You can review and maintain the MDR, transaction fee, and custom fees of a marketplace's creditor operations through APIs or Control Center. For Control Center, refer to Seller management in Control Center.

Advancement terms

Advancement terms are configured on the creditor, not the creditor operation, and apply to all of the merchant's sale transactions. No creditor operation setting affects advancement.

Define these terms when you create the creditor, in the creditor object of the Create merchant request. To change them later, use Update creditor. Some organization-level advancement defaults are set by Pismo on request. Contact your Pismo representative for more information.

Establish transaction classifications

First, identify each transaction type your organization supports. For each transaction type, define its processing code, payment timing, installment conditions, rates, fees, and expected outcomes.

Together, these define your organization's Seller management configuration rules. For how these decisions fit within the broader planning and implementation process, refer to Get started with Seller management.

The following planning matrix helps you translate business requirements into measurable financial outcomes before any configuration takes place. Complete one matrix for each transaction type you support, and use it progressively: define the Classification and Configuration layers before implementation, and use the Evaluation layer to record what you intend to validate afterward. The matrix is an illustrative planning aid and is not required to configure creditor operations. Creditor operations end-to-end completes it for one end-to-end example scenario.

Your required configuration depends on your business model and supported transaction classifications. For processing codes, refer to Step 3: Define processing codes in the Get started with Seller management guide. After you define the transaction classifications, configure them as described in Creditor operation implementation.