Step 4: Process merchant transactions

With the creditor operations in place, ABC Furniture can start processing transactions.

Objective: Submit merchant activity to Seller management. This includes sales, cancellations, reversals, and split transactions.

Customer makes a purchase at ABC Furniture

ABC Furniture completes a USD 1,000 credit card sale in six installments. AcmePay submits it using the Create merchant transaction endpoint. The request carries only the business event and its identifying values. Seller management finds the matching creditor operation from the processing code and installment count. For the authorization-driven path, refer to Merchant transaction processing.

{
  "event_date": "2027-01-15T12:00:00Z",
  "amount": 1000.00,
  "installments": 6,
  "processing_code": "PC300",
  "currency_code": "USD",
  "authorization_id": 123456
}

event_date, amount, installments, and processing_code are required. amount is a number.

The response contains one item for each installment. The following example shows installment 1, which carries the MDR, the fixed transaction fee, and the marketplace fee. discount_details itemizes each deduction. Its amount is USD 166.70 rather than 166.66 because the first installment absorbs the rounding difference. For more information, refer to Recurring decimal breaks.

{
  "items": [
    {
      "id": 789013,
      "merchant_id": 4458801,
      "creditor_id": 777,
      "authorization_id": 123456,
      "parent_authorization_id": null,
      "org_operation_id": null,
      "amount": 166.70,
      "mdr_amount": 20.00,
      "mdr_without_fee": 20.00,
      "mdr_tax": 0,
      "fee": 0.30,
      "installment": 1,
      "number_of_installments": 6,
      "event_date": "2027-01-15T12:00:00Z",
      "scheduled_payment_date": "2027-02-14",
      "status": "SCHEDULED",
      "advanced_amount": 0,
      "type": "SALES",
      "origin_merchant_transaction_id": null,
      "advancement_request_id": null,
      "marketplace_id": 1001,
      "currency_code": "USD",
      "discount_amount": 25.30,
      "discount_details": [
        { "name": "MDR", "amount": 20.00 },
        { "name": "TRANSACTION_FEE", "amount": 0.30 },
        { "name": "MARKETPLACE_FEE", "amount": 5.00 }
      ]
    }
  ]
}

This endpoint generates a Merchant transaction created event.

Cancel a merchant transaction

If the customer cancels the purchase, AcmePay uses the Cancel merchant transaction endpoint. In this example, PC300C is AcmePay's cancellation processing code for PC300 sales.

{
  "event_date": "2027-02-01T12:00:00Z",
  "amount": 1000.00,
  "authorization": { "id": 123457, "parent_id": 123456 },
  "processing_code": "PC300C"
}

• event_date, amount, authorization.id, authorization.parent_id, and processing_code are required. authorization.parent_id is the authorization ID of the original sale.
• An amount equal to the original total is a full reversal. A lesser amount is partial.
• The response uses the same item structure as the sale response, with negative financial values, type: "CANCELLATION", and origin_merchant_transaction_id identifying the reversed installment.
• To cancel a split transaction, use the Cancel split request endpoint.

This endpoint generates a Merchant transaction created event for the cancellation transaction.

For the other merchant transaction endpoints, including split transaction requests, refer to Merchant transaction processing.