# Overview 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](/api/reference/order) or the Hosted [Checkout solution](/guides/checkout/hosted-checkout). ### Direct API (POST /order) Use this method if you are integrating directly via the `POST /order` endpoint. PCI DSS Compliance Requirement Because this integration method requires you to collect and transmit raw card details (PAN, CVV) directly in the API request, **your organization must be fully PCI DSS compliant.** If you are not PCI DSS compliant, you strictly cannot use this method for card payments. Please utilize the [Hosted Checkout](/guides/checkout/hosted-checkout) solution instead, which offloads compliance requirements by handling card data on our secure payment pages. #### Request Structure In addition to the standard [Create Order](/api/reference/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. ```JSON { "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](/guides/checkout/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. Ensure that your checksum calculation includes this new `transactionOptions` field, as the entire JSON payload is used to generate the signature. **Example `jsonRequest`** ```JSON { "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 | Field | Type | Description | | --- | --- | --- | | `splitPayment` | Object | The root object for the split configuration. | | `splitPayment.splitSchema` | Array | A list of objects defining where funds should be routed. | `splitSchema` Item Details | Field | Type | Description | | --- | --- | --- | | `toSite` | Integer | The Site ID of the vendor receiving the funds. **Note**: Do not use the sending site's ID here | | `amount` | Float | The amount to be transferred to this site | | `description` | String | A description for this specific portion of the payment. | | `tag` | Array | Optional tags for categorization or reconciliation. | Validation Note The sum of amount in the split schema must not exceed the total amount of the main order. Any remainder stays on the sending site. # 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](/guides/general/get-started#test-cards). 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.