Guides
Sub-processorsAbout PismoContact us

Managing merchant transactions

Create, split, and cancel marketplace transactions to manage payments to merchants linked to your marketplace. You can include installments, merchant discount rate (MDR) calculations, and scheduled payment dates when you create a merchant transaction. You can also cancel a split request.

📘

Note

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

Prerequisites for merchant transactions

Before you create merchant transactions or split transactions between merchants:

  1. Complete Seller management onboarding. For requirements, refer to Seller management onboarding.
  2. Create a marketplace.
  3. Create processing codes for your organization, creditor operations, and merchants in the marketplace.

You can also receive transactions through the Payment methods API. The Pismo platform creates a merchant transaction when the payment information contains a marketplace ID and merchant ID. The message type indicator (MTI) links this flow to authorization requests through the mti element.

Send an authorization request with the mti element set to 0100 (offline clearing). Then send a confirmation request with the mti element set to 0202 (online clearing) to confirm the transaction.

Create an authorization for merchant transactions

Use this workflow to authorize a merchant transaction. When you use the Payment methods API, transactions containing a marketplace ID and merchant ID trigger merchant transaction creation. The Pismo platform sets the transaction_status element 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: 
    {
  "event_date": "2025-02-14T10:30:00Z",
  "amount": 1500.00,
  "installments": 12,
  "authorization_id": 123456,
  "processing_code": "000700",
  "transaction_status": "SCHEDULED"
}

For authorization details, refer to the Payment methods guide.

To cancel the merchant transaction, use the original authorization ID as the value of the parent_id element. Use a separate authorization ID 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 provide an authorization ID from the Request authorization workflow. The Payment methods API supports cash-in, cash-out, and transfer operations. For the authorization workflow, refer to Create an authorization for merchant transactions.

Use the Create merchant transaction endpoint to create a transaction for a single merchant. This example request body omits the optional authorization ID:

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

The endpoint returns HTTP 201 (Created) with a response body and generates a Merchant transaction created event. The Pismo platform considers the time zone, merchant discount rate taxes, and marketplace creditor operations when creating the transaction.

Cancel a merchant transaction

Use the Cancel merchant transaction endpoint to cancel a merchant transaction. In the authorization element, provide a new authorization ID and set the parent_id element to 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

You can split a marketplace transaction between merchants using defined amounts or percentages. For example, a single checkout in an art marketplace might include items from different artists. Splitting the transaction credits each merchant's share and supports commissions or fees.

To manage split transactions, configure the merchants, create a transaction, and submit a split request. You can also cancel a split request.

The Pismo platform uses a marketplace scheduler (a merchant that handles split transactions) for this flow. Create your marketplace through the Create marketplace (v3) endpoint. The schedule_id element identifies the marketplace scheduler. Use this scheduler as the initial merchant so the transaction can move from WAITING_SPLIT to PROCESSED.

Prerequisites for splitting a transaction

Before you split a transaction:

  1. Create the marketplace through the Create marketplace (v3) endpoint.
  2. Confirm that the marketplace has a valid schedule_id element and that the scheduler merchant has a valid creditor_id element.
  3. Link every participating merchant to the marketplace and configure each merchant's fee registration.
  4. Use the List marketplace merchants endpoint to confirm which merchants belong to the marketplace.
  5. Use the List creditor operations for marketplace and merchant endpoint to review each merchant's rules.

Collect the data required for a split transaction:

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

Specify the participating merchants when you create the split request.

Pre-authorize the sale transaction

Use the Create merchant transaction endpoint to create a transaction for the marketplace scheduler. Use the marketplace's schedule ID as the merchant ID. The response includes a transaction ID with the WAITING_SPLIT status.

In this example, the marketplace_id element is 2625. Use this marketplace's scheduler for the split workflow.

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
}

Authorize the full transaction amount before splitting it between merchants. Use one authorization for the total amount, not separate authorizations for each merchant. The total split amount must not exceed the authorized amount.

Create a split transaction

Provide the merchant transaction ID to the Create split request endpoint. Confirm that the merchant transaction has the WAITING_SPLIT status before you submit the request. This endpoint generates a Merchant transaction created event.

This example uses a fixed amount:

{
  "event_date": "2025-04-20T18:15:56Z",
  "installments": 1,
  "processing_code": "0120",
  "definitions": [
    {
      "merchant_id": 20445,
      "amount": 100
    }
  ]
}

Use either the amount element or the amount_percentage element to define the split. Do not combine fixed amounts and percentages. The total split must not exceed the authorized transaction amount.

Create the original merchant transaction for the marketplace scheduler using the Create merchant transaction endpoint. Use the marketplace's schedule ID as the merchant ID for that transaction.

This example splits the transaction between two merchants using percentages. For the amount_percentage element, 0.7 represents 70%, 0.3 represents 30%, and 1.0 represents 100%. The percentages must total 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 returns HTTP 202 (Accepted) and generates a Merchant transaction created event.

During settlement, the Pismo platform debits the buyer's account and credits each merchant's account according to the defined amounts or percentages. It then sets the transaction to PROCESSED. For details, refer to How merchant settlements are processed.

Cancel a split request

Use the Cancel split request endpoint to cancel a split request. Provide the original merchant transaction ID. Include the event date, processing code, marketplace, and merchants from the original split request in the request body:

{
  "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

Use the Get split request totals endpoint to retrieve totals for a parent split request with the PROCESSED status. The response includes each participating merchant's gross amount and the marketplace schedule ID.

Updated 19 days ago

Did this page help you?