Overview

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

The Split Payments solution enables a "Marketplace" model where a customer can create a single aggregated order containing products or services from multiple vendors (sites).

When a customer pays for this aggregated order, the system automatically handles the distribution of funds. The main order is processed on the primary (sending) site, and corresponding "internal" orders and transactions are instantly created on the vendor (receiving) sites.

How It Works

1. Aggregated Order: You create a single order request on the primary merchant site (the "marketplace site").
2. Split Definition: Inside this request, you declare the destination sites and amounts using the transactionOptions parameter with the splitPayment schema.
3. Automatic Distribution: Upon a successful payment:

• A primary Order and Transaction are created on the sending site.
• New Orders are automatically created on each "receiving site" defined in the split schema.
• Funds Transfer: Internal credit and deposit transactions are executed to move funds from the sending site to the receiving sites.

Integration Methods

You can implement Split Payments using either the Direct API or the Hosted Checkout solution.

Direct API (POST /order)

Use this method if you are integrating directly via the POST /order endpoint.

Request Structure

In addition to the standard Create Order parameters (such as amount, currency, customerId, orderType), you must include the transactionOptions object containing the splitPayment definition.

Example Request In this example, a customer purchases items totaling 100.00 EUR.

• 50.00 EUR goes to Vendor A (Site 9825).
• 30.00 EUR goes to Vendor B (Site 9792).
• 20.00 EUR remains on the Marketplace (Sending Site) as commission/fees.

{
  "amount": 100.00,
  "currency": "EUR",
  "orderType": "purchase",
  "customerId": 12345,
  "description": "Marketplace Aggregated Order #5501",
  "transactionOptions": {
    "splitPayment": {
      "splitSchema": [
        {
          "toSite": 9825,
          "amount": 50.00,
          "description": "Payment to Vendor A",
          "tag": ["vendorA", "electronics"]
        },
        {
          "toSite": 9792,
          "amount": 30.00,
          "description": "Payment to Vendor B",
          "tag": ["vendorB", "accessories"]
        }
      ]
    }
  }
}

Hosted Checkout

Use this method if you are using the Hosted Checkout page. The configuration is passed within the encrypted jsonRequest payload used to initialize the payment session. This method is suitable for merchants who are not PCI DSS compliant.

Request Structure Add the transactionOptions object to the root of your jsonRequest structure.

Example jsonRequest

{
  "siteId": 1,
  "customer": {
    "identifier": "your-unique-customer-id",
    "firstName": "John",
    "lastName": "Doe",
    "country": "RO",
    "city": "Bucharest",
    "email": "john.doe@test.com"
  },
  "order": {
    "orderId": "your-unique-order-id",
    "description": "Order Description",
    "type": "purchase",
    "amount": 2194.98,
    "currency": "RON"
  },
  "cardTransactionMode": "authAndCapture",
  "backUrl": "https://myshop.com/payment-back-url",
  "transactionOptions": {
    "splitPayment": {
      "splitSchema": [
        {
          "toSite": 9825,
          "amount": 1000.00,
          "description": "Payment for Vendor A",
          "tag": ["vendorA"]
        },
        {
          "toSite": 9792,
          "amount": 500.00,
          "description": "Payment for Vendor B",
          "tag": ["vendorB"]
        }
      ]
    }
  }
}

Configuration Reference

transactionOptions Schema

splitSchema Item Details

Post-Processing & Artifacts

Once the transaction is successful, the system generates several linked entities to represent the flow of funds.

On the Sending Site (Marketplace)

• Order: A standard purchase order is created.
• Transaction: A transaction of type='credit' and transactionMethod='transfer' is created.
  • This transaction will have a component named "internal-credit".

On the Receiving Site (Vendor)

For every item in the splitSchema, the following are automatically generated on the specific toSite:

• New Customer:
  • Created with identifier format: "internal-{customerId from sending site}".
• New Order:
  • Created with orderType='purchase'.
  • Linked via externalOrderId format: "internal-{orderId from sending site}".
• New Transaction:
  • Created with type='deposit' and transactionMethod='transfer'.
  • This transaction will have a component named "internal-deposit".

Integration & Compliance Checklist

Security & PCI Compliance

Determine Integration Type & Scope:

• Direct API: Confirm your organization is PCI DSS Compliant (typically SAQ D or Level 1 audit) to handle raw card data.
• Hosted Checkout: Confirm you qualify for SAQ A (all card data handling offloaded to xMoney).

Credentials Management:

• Ensure Private Key is never exposed in client-side code (browser/mobile app).

Split Schema Validation (Business Logic)

Amount Verification:

• Sum Check: Total of amount in splitSchema <= Main Order amount.
• Remainder: Confirm that any unallocated remainder is intended to stay on the Sending Site (Marketplace) as commission.

Site ID Rules:

• No Self-Loop: toSite must not equal the Sending Site ID.
• No Duplicates: toSite IDs must be unique within the splitSchema array.

Currency Consistency:

• Ensure all split amounts assume the same currency as the main order (cross-currency splits are not supported in this schema).

Technical Integration

If using Hosted Checkout:

• Payload Structure:
  • transactionOptions is placed inside the root of the jsonRequest object.
• Checksum Calculation:
  • The checksum calculation (HMAC-SHA-512) includes the entire JSON payload, including the new transactionOptions object.
  • Verify the JSON stringification order does not alter the checksum (ensure consistent serialization).

If using Direct API:

• Payload Structure:
  • transactionOptions is a sibling to amount and customerId in the POST body.

Post-Integration Testing

End-to-End Flow:

• Perform a successful transaction using a Test Card.

Verify Sending Site:

• Confirm 1 Order and 1 Transaction (internal-credit) created.

Verify Receiving Site(s):

• Login to vendor dashboard (or use API) to confirm 1 Order and 1 Transaction (internal-deposit) created per split.
• Verify externalOrderId matches the format internal-{parent_order_id}.
• Verify amount matches the specific split value.

Error Handling

• Implement logic to handle 400 Bad Request if the split amount exceeds the total order amount.
• Handle partial failures (e.g., if a vendor account is suspended) based on xMoney's specific error codes.