Managing merchant transactions

Marketplace transactions represent sales where payments go to merchants affiliated with the marketplace. When creating a merchant transaction, you can include optional details such as installments, MDR (Merchant Discount Rate) calculations, and scheduled payment dates. It's also possible to split a transaction across multiple merchants or cancel an existing merchant transaction. You can cancel a request to split transactions also.

📘

The Pismo platform handles merchant transactions separately from the general transaction types listed via the List transaction types endpoint. To retrieve merchant transactions, use the List merchant transactions (V2) endpoint instead.

Prerequisites for merchant transactions

You should be onboarded for seller management as a prerequisite to offering merchant transactions or splitting transactions between merchants. See Seller management onboarding for requirements to meet during onboarding.

You need to have processing codes for your organization, creditor operations, and merchants in the marketplace prior to creating a merchant transaction (per merchant or split among multiple merchants).

Optionally, you can take in transactions in a flow from the Payment methods API. The Pismo platform automatically creates a merchant transaction when it sees a marketplace ID and merchant ID in the payment information. The mti or Message Type Identifier makes this connection with authorization requests with the mti value 0100(clearing type offline). Then the client sends a confirmation request with mti value 0202 (clearing type online) to confirm the transaction in this flow.

Create an authorization for merchant transactions

Use this workflow for authorization and to automatically create a merchant transaction. When using the Payment methods API, any transactions containing the marketplace ID and merchant ID creates a merchant transaction automatically with transaction_status set to SCHEDULED.

1. Request authorization using the PCI endpoint, Request authorization. You get an authorization ID in the response.
2. Use the authorization ID when creating the merchant transaction in the request body like this example:
   JSON

   {
     "event_date": "2025-02-14T10:30:00Z",
     "amount": 1500.00,
     "installments": 12,
     "authorization_id": 123456,
     "processing_code": "000700",
     "transaction_status": "SCHEDULED"
   }
   

See the Payment methods guide for details on authorizations.

If you want to cancel a merchant transaction later, you use this authorization_id as the parent_id, representing the parent authorization identifier from the original transaction. You'll have a separate authorization identifier for the cancellation.

Create a transaction per merchant

To create a single merchant transaction, you need the following information:

• Marketplace ID
• Merchant ID
• Date you want the transaction event to take place
• Amount
• Number of installments
• Processing code
• (optional) Authorization ID

You can optionally provide an authorization ID obtained with a Request authorization workflow and the Payment methods API endpoints to manage cash-in, cash-out, and transfer operations. Walk through that workflow in Create an authorization for merchant transactions.

Create a new transaction for a single merchant using the Create merchant transaction endpoint (without optional authorization) with a request body like this example:

{
  "event_date": "2025-08-14T10:30:00Z",
  "amount": 1000.00,
  "installments": 12,
  "processing_code": "000700",
  "transaction_status": "SCHEDULED"
}

This endpoint responds with HTTP 201 (Created) status code, a response body, and generates a Merchant transaction created event. The Pismo platform considers time zone, MDR taxes, and marketplace creditor operations when creating the transaction.

Cancel a merchant transaction

Example for canceling a merchant transaction with the Create reversal transaction endpoint. Notice that the authorization requires both a new identifier and the parent_id which is the original authorization ID.

{
  "event_date": "2025-02-18T11:35:00Z",
  "amount": 1500.00,
  "authorization": {
    "id": 123456,
    "parent_id": 654321
  },
  "processing_code": "000701"
}

This endpoint generates a Merchant transaction settled event.

Create transactions to split between merchants

In a marketplace with multiple vendors, you can split transactions between merchants for accurate account crediting. The transaction split ensures that each merchant receives their share of a transaction, based on defined amounts or percentages. It's particularly useful when a transaction involves multiple merchants, such as in a marketplace selling products from various vendors. For example, in an art-selling marketplace, a single checkout might include items from different artists. By splitting transactions, the marketplace can automate settlements, reduce administrative overhead, and provide a single purchase point for a buyer. This method also supports commissions or fees, ensuring appropriate compensation for all merchants.

Managing split transactions involves configuring, creating, and processing split requests among merchants in a marketplace with a scheduler entity. You also can cancel a split request if needed. This guide outlines the necessary API calls and steps to handle these marketplace management tasks.

The Pismo platform uses the concept of a "marketplace scheduler" to handle these split transactions. Each marketplace created with the v2 Create marketplace endpoint has a "schedule ID" assigned that serves as a marketplace scheduler. By creating the split transaction with the scheduler as the initial merchant, you put the transaction through the proper status changes from WAITING_SPLIT to PROCESSED.

Prerequisites for splitting a transaction

You can determine which merchants belong to the marketplace using the List marketplace merchants endpoint. You can use the List creditor operations for marketplace and merchant endpoint to view the rules applied for each. All merchants involved in the split must have their fee registration configured in the platform and they must be linked to the marketplace. The marketplace must have a valid schedule_id and in turn that merchant must have a valid creditor_id. This requirement means that you must create the marketplace with the v2 Create marketplace endpoint.

The data required for any split transaction includes:

• Merchant transaction ID
• Marketplace schedule ID (in the v2 Get marketplace response body you find the schedule_id)
• Event date for when the split should occur
• Processing code

You indicate all the merchants involved in the split transaction in a later API call.

Pre-authorize the sale transaction

First, use the Create merchant transaction endpoint and create a merchant transaction, specifying a merchant that is a marketplace scheduler. When you create a merchant transaction with the Marketplace's schedule_id, you get a transaction ID with a WAITING_SPLIT status.

In this example, the marketplace_id is 2625. This marketplace has a scheduler assigned to it, which you use in the next section.

Create a merchant transaction with this example request body:

{
  "authorization": {
    "principal_amount": 1000,
    "number_of_installments": 1,
    "installment_amount": 1000,
    "event_date_hour": "2025-04-20T18:14:56Z"
  },
  "acceptance": {
    "matched_mdr": false,
    "matched_settlement": false,
    "mdr": 0.03,
    "transaction_fee": 1,
  },
  "operation": {
    "org_operation_id": 1125
  },
  "additional_info": {
    "account_id": 8675309
  },
  "marketplace_id": 2625
}

Authorization applies to the full amount prior to splitting the amount per merchant. There's no split for authorization, only one authorization for the total amount. The authorization amount does not exceed the sum of split amounts.

Create a split transaction

Next, you provide the merchant authorization ID to the Create split request endpoint. This endpoint generates a Merchant transaction created event.

{
  "event_date": "2025-04-20T18:15:56Z",
  "installments": 1,
  "processing_code": "0120",
  "definitions": [
    {
      "merchant_id": 20445, # represents the scheduler_id for the marketplace
      "amount": 100,
      "amount_percentage": 0.35
    }
  ]
}

When you create a split transaction request, you specify either the amount or amount_percentage that defines the split, however you cannot combine fees and percentages, you must use one or the other. The total split cannot exceed the authorized transaction amount. Also, when using amount_percentage, the sum of each must total 1.0.

Specify a merchant that is a marketplace scheduler in the request by using the schedule_id that matches up with the marketplace. You must have a merchant transaction already created using the Create merchant transaction endpoint.

Here is an example request body for a split transaction. This example shows a split request sale request between two merchants with a percentage indicated. For percentage, the value is a decimal value where 0.7 represents 70%, 0.3 represents 30%, and 1.0 represents 100%. The total percentages must equal 1.0.

{
  "event_date": "2024-12-18T08:07:07Z",
  "installments": 1,
  "processing_code": "003000",
  "definitions": [
    {
      "merchant_id": 46729,
      "amount_percentage": 0.7
    },
    {
      "merchant_id": 49558,
      "amount_percentage": 0.3
    }
  ]
}

The endpoint responds with HTTP 202 (Accepted) status code and generates a Merchant transaction created event.

After processing the transaction, settlement occurs so that the system debits the customer's account, credits each merchant's account according to the defined splits (amount or percentage), then sets the transaction to PROCESSED. See How merchant settlements are processed for details.

Cancel a split request

You can cancel the split transaction using the Cancel split request endpoint. You must have the transaction ID of the original merchant transaction that was split. The body of the request contains the details such as event date, processing code, marketplace, and which merchants were included in the original split request.

{
  "event_date": "2023-12-19T20:23:55Z",
  "installments": 1,
  "processing_code": "009900",
  "marketplace": {
    "id": 1,
  },
  "definitions": [
    {
      "merchant_id": 46729,
      "amount": 100,
    },
    {
      "merchant_id": 47187,
    }
  ]
}

Request split totals

When you want to know the totals from a specific parent split request with the PROCESSED status, use the Get split request totals endpoint. It returns the gross amount for each participating merchant, as well as the marketplace schedule ID.