# Split Transactions Learn how to split a transaction across multiple sellers. When processing an online payment or transaction, you can split the funds that get paid out across several different sellers. Specifically, the funds from `Transfers` can be split across any number of approved `Merchants.` Please note: - `Transfers` can only be split between `Merchants` created under the same `Application.` - Each `split_transfer` is placed into the `Settlement` of the `split_transfers#merchant.` - No changes need to be made to your `Application` or `Merchants` to enable Split Transactions. ## Splitting a Transfer across Sellers ### Finix API To split a transaction, [when creating the `Transfer`](/api/transfers/createtransfer) include: - The **ID** of the `Merchants` that the funds will get split across. - The `amount` to distribute into the `Settlements` of each `Merchant.` The combined `amounts` in the `split_transfers` object must be equal to the `amount` of the `Transfer.` In the following example, a $10.00 `Transfer` is split so: - The primary merchant receives $6.00 (before subtracting processing fees) - The second merchant receives $3.00 (before subtracting processing fees) - The third merchant receives $1.00 (before subtracting processing fees) Processing fees get deducted when `Merchants` receive their payouts. For more details, see [Payouts](/guides/platform-payments/seller-payouts). Please note, the primary merchant is the `merchant` specified in the parent `Transfer` request; outside the `split_transfers` object. Example API Definition Example response: Example Split Transaction ```json Split Transaction { "id": "TR4juLvWuH9X3NNoQoNgV7Lb", "created_at": "2026-01-12T22:57:43.97Z", "updated_at": "2026-01-12T22:57:43.97Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 1000, "amount_requested": 1000, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "currency": "USD", "destination": null, "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FPuizPqrhzYLbmJm88u7aqfj", "idempotency_id": null, "ip_address_details": null, "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "messages": [], "network_details": null, "operation_key": "CARD_NOT_PRESENT_SALE", "parent_transfer": null, "parent_transfer_trace_id": null, "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": "PI5benj4eVhCL4ALMv6SFxJG", "split_transfers": [ "split_transfer_4jMxFDBZkDF2q5FnxDCvPC", "split_transfer_4jMUn4atFyP6i7vrAT7ina", "split_transfer_4jMUKxw1isVpuzwAmgaPV4" ], "state": "PENDING", "statement_descriptor": "FLX*FINIX FLOWERS", "subtype": "API", "supplemental_fee": null, "tags": {}, "third_party_details": null, "tip_amount": null, "trace_id": "fb74de16-da43-4a44-9524-f2057b5f6083", "type": "DEBIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TR4juLvWuH9X3NNoQoNgV7Lb" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TR4juLvWuH9X3NNoQoNgV7Lb/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TR4juLvWuH9X3NNoQoNgV7Lb/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/fees?linked_to=TRuzLCSCgBn6FjGdgiY2SUou" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TR4juLvWuH9X3NNoQoNgV7Lb/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI5benj4eVhCL4ALMv6SFxJG" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPuizPqrhzYLbmJm88u7aqfj" } } } ``` API Definition #### Split Transfers The `split_transfers` array returned in the response contains the resource **IDs** of the `split_transfers` generated from the `Transfer` that was split. Use the **ID** to review how the transaction was split for the specified `Merchant.` Example response: Example Split Transfer ```json Split Transfer { "id": "split_transfer_97gaitUpcmzqjYYpQbei9j", "created_at": "2026-01-12T22:15:51.99Z", "updated_at": "2026-01-12T22:15:51.99Z", "amount": 400, "application_id": "APc9vhYcPsRuTSpKD9KpMtPe", "currency": "USD", "fee": 100, "fee_profile_id": "FPryaDMUDq9Tcc5epVpro1Jj", "identity_id": "IDjvxGeXBLKH1V9YnWm1CS4n", "merchant_id": "MU7noQ1wdgdAeAfymw2rfBMq", "parent_transfer_id": "TR96ZCp2GLvDHPPTMpcsabZi", "ready_to_settle_at": "2026-01-13T22:16:03.67Z", "tags": {}, "type": "DEBIT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/split_transfers/split_transfer_97gaitUpcmzqjYYpQbei9j" } } } ``` API Definition ### Finix Dashboard Split Transactions appear on the Finix Dashboard under **Payments**. You can identify Split Transactions using the **Payment Type** in the **Amount** column: Identify split transactions Click on the individual entry to review the Split Transaction in detail: View split transactions ## Splitting a Capture across Sellers ### Step 1: Create an Authorization The first step is to create an Authorization. If you are interested in learning more about Authorizations, you can read our guide [here](/guides/online-payments/payment-features/auth-and-captures). ```shell curl 'https://finix.sandbox-payments-api.com/authorizations' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -X POST \ -d '{ "amount": 1000, "currency": "USD", "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "source": "PIe2YvpcjvoVJ6PzoRPBK137" }' ``` Example Response: ```json { "id": "AUirsgFc8drp1LPzNFcxP2r", "created_at": "2024-03-15T20:47:09.60Z", "updated_at": "2024-03-15T20:47:09.60Z", "3ds_redirect_url": null, "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": "POSTAL_CODE_AND_STREET_MATCH", "amount": 1000, "amount_requested": 1000, "application": "APgPDQrLD52TYvqazjHJJchM", "currency": "USD", "expires_at": "2024-03-22T20:47:09.60Z", "failure_code": null, "failure_message": null, "idempotency_id": null, "is_void": false, "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDuqZpDw28f2KK6YuDk4jNLg", "messages": [], "raw": null, "receipt_last_printed_at": null, "security_code_verification": "MATCHED", "source": "PIe2YvpcjvoVJ6PzoRPBK137", "state": "SUCCEEDED", "tags": {}, "trace_id": "a4f7612f-a09e-4c35-ae92-9a1f44fcd2a7", "transfer": null, "void_state": "UNATTEMPTED", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/authorizations/AUirsgFc8drp1LPzNFcxP2r" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg" } } } ``` ### Step 2: Create a Capture When you capture an `Authorization`, Finix creates a `Transfer` resource. You can capture an Authorization by using the following API. The `split_transfers` array is optional. If you omit the `split_transfer` array, the Capture will not be split. ```shell curl 'https://finix.sandbox-payments-api.com/authorizations/AUirsgFc8drp1LPzNFcxP2r' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -X PUT \ -d '{ "capture_amount": 1000, "split_transfers": [ { "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "amount": 600, "tags": { "key": "value" } }, { "merchant": "MUeHUEPKybMjqV1STcqrFTSH", "amount": 300, "fee": 100 }, { "merchant": "MU3Gh6DT5fCBxVtWB8VJc1St", "amount": 100 } ] }' ``` **Example Authorization Response:** ```json { "id": "AUirsgFc8drp1LPzNFcxP2r", "created_at": "2024-03-15T20:47:09.60Z", "updated_at": "2024-03-15T20:56:38.31Z", "3ds_redirect_url": null, "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": "POSTAL_CODE_AND_STREET_MATCH", "amount": 1000, "amount_requested": 1000, "application": "APgPDQrLD52TYvqazjHJJchM", "currency": "USD", "expires_at": "2024-03-22T20:47:09.60Z", "failure_code": null, "failure_message": null, "idempotency_id": null, "is_void": false, "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDuqZpDw28f2KK6YuDk4jNLg", "messages": [], "raw": null, "receipt_last_printed_at": null, "security_code_verification": "MATCHED", "source": "PIe2YvpcjvoVJ6PzoRPBK137", "state": "SUCCEEDED", "tags": {}, "trace_id": "a4f7612f-a09e-4c35-ae92-9a1f44fcd2a7", "transfer": "TRs2sPQ9pd8nr4BRprsXy78H", "void_state": "UNATTEMPTED", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/authorizations/AUirsgFc8drp1LPzNFcxP2r" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "transfer": { "href": "https://finix.sandbox-payments-api.com/transfers/TRs2sPQ9pd8nr4BRprsXy78H" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg" } } } ``` The `authorization#transfer` field returns the `Transfer` created from the captured `Authorization`. **Example Transfer Response:** ```json { "id": "TRs2sPQ9pd8nr4BRprsXy78H", "created_at": "2024-03-15T20:56:38.16Z", "updated_at": "2024-03-15T20:57:00.73Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 1000, "amount_requested": 1000, "application": "APgPDQrLD52TYvqazjHJJchM", "currency": "USD", "destination": null, "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "idempotency_id": null, "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDuqZpDw28f2KK6YuDk4jNLg", "messages": [], "parent_transfer": null, "parent_transfer_trace_id": null, "raw": null, "ready_to_settle_at": "2024-03-15T20:57:00.82Z", "receipt_last_printed_at": null, "security_code_verification": null, "source": "PIe2YvpcjvoVJ6PzoRPBK137", "split_transfers": [ "split_transfer_hkckq21uy6qWWYzcS2e14r", "split_transfer_hkdqpd4mSGTGbAhsPuFubF", "split_transfer_hkdqFSfgCtWdRcVjwWxfyZ" ], "state": "SUCCEEDED", "statement_descriptor": "FNX*DUNDER MIFFLIN", "subtype": "API", "tags": {}, "trace_id": "a4f7612f-a09e-4c35-ae92-9a1f44fcd2a7", "type": "DEBIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRs2sPQ9pd8nr4BRprsXy78H" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRs2sPQ9pd8nr4BRprsXy78H/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRs2sPQ9pd8nr4BRprsXy78H/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/transfers/TRs2sPQ9pd8nr4BRprsXy78H/fees" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRs2sPQ9pd8nr4BRprsXy78H/disputes" }, "source": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIe2YvpcjvoVJ6PzoRPBK137" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8" } } } ``` Inside the `Transfer`, the `transfers#split_transfers` array contains the `split_transfers` when you captured the Authorization. ## Splitting a Card Present Transaction ```shell curl 'https://finix.sandbox-payments-api.com/transfers' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \ -X POST \ -d '{ "amount": 300, "currency": "USD", "device": "DVae7HFLS7BXNaFpKhdH1K6x", "operation_key": "CARD_PRESENT_SALE", "split_transfers": [ { "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "amount": 200, "tags": { "key": "value" } }, { "merchant": "MUcgYZswyRfqSSbvMsxuaHxZ", "amount": 100, "fee": 10 } ], "tags": { "test": "sale" } }' ``` Example response: ```json { "id": "TRtAsvgPKhGcJJtrV8fAXUgC", "created_at": "2025-03-04T16:08:12.55Z", "updated_at": "2025-03-04T16:08:12.55Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "additional_purchase_data": null, "address_verification": null, "amount": 300, "amount_requested": 300, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "card_present_details": { "emv_data": { "application_identifier": "A0000000031010", "application_label": "VISA CREDIT", "application_preferred_name": null, "application_transaction_counter": "00D0", "cryptogram": "ARCQ 99902411B7B0B26E", "issuer_code_table_index": null, "network_emv_response": null, "pin_verified": false, "tags": null }, "masked_account_number": "476173******0010", "name": null, "brand": "VISA", "entry_mode": "CONTACTLESS", "payment_type": "CREDIT", "approval_code": "956682", "digital_signature_file_id": null }, "currency": "USD", "destination": null, "device": "DVae7HFLS7BXNaFpKhdH1K6x", "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "fee_profile": "FPuizPqrhzYLbmJm88u7aqfj", "idempotency_id": null, "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "messages": [], "operation_key": "CARD_PRESENT_SALE", "parent_transfer": null, "parent_transfer_trace_id": null, "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": "PIkXKGqRMswqxKN9YbnRir26", "split_transfers": [ "split_transfer_tAVzHxjXfXFdTx7XtLZgUZ", "split_transfer_tAVJEs5ZaNu6iAJDbtdTYs" ], "state": "SUCCEEDED", "statement_descriptor": "FLX*FINIX FLOWERS", "subtype": "API", "supplemental_fee": null, "tags": { "test": "sale" }, "tip_amount": 0, "trace_id": "e3ecb181-3c00-4ade-805b-6b35bb85eb61", "type": "DEBIT", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APc9vhYcPsRuTSpKD9KpMtPe" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TRtAsvgPKhGcJJtrV8fAXUgC" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/ID6UfSm1d4WPiWgLYmbyeo3H" }, "device": { "href": "https://finix.sandbox-payments-api.com/devices/DVae7HFLS7BXNaFpKhdH1K6x" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TRtAsvgPKhGcJJtrV8fAXUgC/payment_instruments" }, "reversals": { "href": "https://finix.sandbox-payments-api.com/transfers/TRtAsvgPKhGcJJtrV8fAXUgC/reversals" }, "fees": { "href": "https://finix.sandbox-payments-api.com/transfers/TRtAsvgPKhGcJJtrV8fAXUgC/fees" }, "disputes": { "href": "https://finix.sandbox-payments-api.com/transfers/TRtAsvgPKhGcJJtrV8fAXUgC/disputes" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPuizPqrhzYLbmJm88u7aqfj" } } } ``` ##### HTTP Request `POST https://finix.sandbox-payments-api.com/transfers` ##### Request Arguments | Field | Type | Description | | --- | --- | --- | | `amount` | *integer*, **required** | The total amount that will be debited in cents (e.g. 100 cents to debit $1.00) | | `currency` | *string*, **required** | 3-letter ISO code designating the currency of the `Transfers` (e.g. USD) | | `idempotency_id` | *string*, **optional** | A randomly generated value that you want to be associated with the request | | `device` | *string*, **required** | ID of the primary `Device` that's processing the `Transfer` for the buyer | | `split_transfers` | *array*, **required** | An array of objects you use to detail how the Transfer will get split and the amount Merchants should receive.The sum of the `split_transfer#amounts` must be equal to the amount submitted in the Transfer request. | | `tags` | *object*, **optional** | Key value pair for annotating custom metadata (e.g. order numbers) | | `operation_key` | *string*, **required** | The operation key for the `Transfer` | ##### Request Arguments - Split Transfers Object | Field | Type | Description | | --- | --- | --- | | `amount` | *integer*, **required** | The amount of funds that get split and paid out to the specifiedMerchant.Must be less than or equal to the `amount` of the Transfer.The sum of the `split_transfer#amounts` must equal the `amount` in the parent `Transfer.` | | `fee` | *integer*, **optional** | The minimum amount of the `split_transfer` you'd like to collect as your fee in cents. Defaults to zero (must be less than or equal to the `amount` being split for the specified `Merchant`).Please note, for split transaction,`fees` are only supported when included in the `split_transfers` object. | | `merchant` | *string*, **required** | The ID of the Merchant that will receive the specified `amount` under the `split_transfers` object.In Split Transfers, the primary Merchants is specified outside the split_transfers object. | | `tags` | *object*, **optional** | Key value pair for annotating custom metadata (e.g. order numbers) | ## Refunding Split Transactions Refund Split Transactions by following the usual steps to refund transactions in Finix. For more information, see [Refund](/guides/after-the-payment/refunds/). When processing a refund, you can split the funds across the `Merchants` included in the original `Transfer` so they get paid off across the different sellers. Please note, the `amount` refunded to each seller can't exceed the `amount` in the parent `Transfer.` ```shell curl 'https://finix.sandbox-payments-api.com/transfers/TR2kKxKDu2nJCvjD2djuDktv/reversals' \ -H 'Content-Type: application/json' \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -X POST \ -d '{ "refund_amount": 1000, "split_transfers": [ { "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "amount": 600, "tags": { "key": "value" } }, { "merchant": "MUeHUEPKybMjqV1STcqrFTSH", "amount": 300 }, { "merchant": "MU3Gh6DT5fCBxVtWB8VJc1St", "amount": 100 } ], "tags": { "test": "refund" } }' ``` Example response: ```json { "id": "TR7KSrpZWc9UoB6bcxqYu978", "created_at": "2023-08-08T20:29:14.88Z", "updated_at": "2023-08-08T20:29:14.98Z", "additional_buyer_charges": null, "additional_healthcare_data": null, "address_verification": null, "amount": 1000, "amount_requested": 1000, "application": "APgPDQrLD52TYvqazjHJJchM", "currency": "USD", "destination": "PIe2YvpcjvoVJ6PzoRPBK137", "externally_funded": "UNKNOWN", "failure_code": null, "failure_message": null, "fee": 0, "idempotency_id": null, "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs", "merchant_identity": "IDuqZpDw28f2KK6YuDk4jNLg", "messages": [], "raw": null, "ready_to_settle_at": null, "receipt_last_printed_at": null, "security_code_verification": null, "source": null, "split_transfers": [ "split_transfer_8DUfRhXpZDiM6rZcyfNGGD", "split_transfer_8DUgkBtytEtSPQKKCCmG3m", "split_transfer_8DUgvBbUwJiN2pWw6P4cMH" ], "state": "PENDING", "statement_descriptor": "FNX*DUNDER MIFFLIN", "subtype": "API", "tags": { "test": "refund" }, "trace_id": "dfc18365-d862-46e0-8acb-9c290a1aed7b", "type": "REVERSAL", "_links": { "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "self": { "href": "https://finix.sandbox-payments-api.com/transfers/TR7KSrpZWc9UoB6bcxqYu978" }, "parent": { "href": "https://finix.sandbox-payments-api.com/transfers/TR2kKxKDu2nJCvjD2djuDktv" }, "destination": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIe2YvpcjvoVJ6PzoRPBK137" }, "merchant_identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg" }, "payment_instruments": { "href": "https://finix.sandbox-payments-api.com/transfers/TR7KSrpZWc9UoB6bcxqYu978/payment_instruments" }, "fee_profile": { "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8" } } } ``` Example response: ```json { "id": "split_transfer_8DUfRhXpZDiM6rZcyfNGGD", "created_at": "2023-08-08T20:29:15.08Z", "updated_at": "2023-08-08T20:29:15.08Z", "amount": 600, "application_id": "APgPDQrLD52TYvqazjHJJchM", "currency": "USD", "fee": 0, "fee_profile_id": "FPbDSnEPtaT8Nttxj9NJk7eC", "identity_id": "IDuqZpDw28f2KK6YuDk4jNLg", "merchant_id": "MUeDVrf2ahuKc9Eg5TeZugvs", "parent_transfer_id": "TR7KSrpZWc9UoB6bcxqYu978", "ready_to_settle_at": null, "tags": { "key": "value" }, "type": "CREDIT" } ``` ## Settlements and Payouts Every `split_transfer` gets placed into a `Settlement.` `Merchants` get paid out when `Settlements` are approved. For more information, see our Platform Payments guide on [Payouts](/guides/platform-payments/seller-payouts). ### Settlement Entries To query all the transactions for a specific settlement, use the following API: ```shell curl "https://finix.sandbox-payments-api.com/settlements/STivxR2KrnVdD75TQtitnsG8/entries" \ -H "Finix-Version: 2022-02-01" \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e ``` Example Response: ```json { "_embedded": { "settlement_entries": [ { "id": "SEix6ptbScYkWFN1id25KbN5", "created_at": "2022-08-12T21:41:42.36Z", "updated_at": "2022-08-12T21:41:42.36Z", "amount": 100, "currency": "USD", "entity_id": "TR8yiKY6ju988aUZhfqJFjag", "entity_type": "TRANSFER", "should_fund": true, "subtype": "FEE", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/STivxR2KrnVdD75TQtitnsG8/entries/SEix6ptbScYkWFN1id25KbN5" }, "entries": { "href": "https://finix.sandbox-payments-api.com/settlement_engine/settlement/STivxR2KrnVdD75TQtitnsG8" } } }, { "id": "SEiwmJxC3u8gfPuLiwMSrn1a", "created_at": "2022-08-12T21:41:42.18Z", "updated_at": "2022-08-12T21:41:42.18Z", "amount": 2, "currency": "USD", "entity_id": "TRwgubpxAJWbaDZE1kKP6SSi", "entity_type": "TRANSFER", "should_fund": true, "subtype": "FEE", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/STivxR2KrnVdD75TQtitnsG8/entries/SEiwmJxC3u8gfPuLiwMSrn1a" }, "entries": { "href": "https://finix.sandbox-payments-api.com/settlement_engine/settlement/STivxR2KrnVdD75TQtitnsG8" } } }, { "id": "SEivAwLLW6c62Nbvvj7TcDAN", "created_at": "2022-08-12T21:41:41.99Z", "updated_at": "2022-08-12T21:41:41.99Z", "amount": 100, "currency": "USD", "entity_id": "TRm9ppvqX43CbwmNzhckf2gb", "entity_type": "TRANSFER", "should_fund": true, "subtype": "DEBIT", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/STivxR2KrnVdD75TQtitnsG8/entries/SEivAwLLW6c62Nbvvj7TcDAN" }, "entries": { "href": "https://finix.sandbox-payments-api.com/settlement_engine/settlement/STivxR2KrnVdD75TQtitnsG8" } } } ] }, "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/settlements/STivxR2KrnVdD75TQtitnsG8/entries" }, "next": { "href": "https://finix.sandbox-payments-api.com/settlements/STivxR2KrnVdD75TQtitnsG8/entries?after_cursor=SEivAwLLW6c62Nbvvj7TcDAN" } }, "page": { "limit": 100, "next_cursor": "SEivAwLLW6c62Nbvvj7TcDAN" } } ``` #### Response | Field | Type | Description | | --- | --- | --- | | `id` | *string*, | ID of the `Settlement Entry` | | `amount` | *integer* | Amount of the `Entry` | | `attempt_bank_account_validation_check` | *boolean*, **required** | Set to **true** to request a bank account validation. | | `currency` | *string* | Currency of the `Entry` | | `entity_id` | *string* | ID of the entity. For example, this can be the `id` of a `Transfer` or `Split Transfer`. | | `should_fund` | *boolean* | Whether this entry will get paid out as part of the `funding_transfer` calculations. | | `entity_type` | *string* | Type of Entity. Values include `TRANSFER`, `SPLIT_TRANSFER`, `CUSTOM_FEE`. | | `sub_type` | *string* | Subtype of the Entity. Values include `DEBIT`, `CREDIT`, `CUSTOM`, `FEE`, `REVERSAL`, `ADJUSTMENT`, and `DISPUTE`. | ## Fees Processing fees for split transactions get created according to: - The fee profile created for the `Merchant.` For more details, see [Fee Profiles](/api/fee-profiles). - Any fees included in `split_transfer#fee` when the initial `Transfer` was first created. For more information, see [Create a Transfer.](/api/transfers/createtransfer) - If `charge_interchange` is enabled in the seller's `fee_profile,` they'll be charged interchange for the full transaction amount. ## Disputes There are two ways you can handle disputes with Split Transactions. ### Option 1 - Full amount of dispute debited to Primary Merchant (Default Behavior) This is the default behavior for split transactions and operates the same as if you get a dispute in a regular sale. The primary merchant will be debited the full amount of the dispute. ### Option 2: Disputes are split proportionally to the amount of the original sale To enable this option, reach out to [Finix Support](mailto:support@finix.com). When a buyer disputes a split transaction, the `Dispute` › `amount` is split proportionally among all participants based on their share of the original sale. Consider a split transaction where a $10.00 sale is split between two merchants: - Merchant A (primary): $6.00 (60%) - Merchant B: $4.00 (40%) When the buyer disputes this transaction, the following occurs: #### 1. Dispute Created A `Dispute` resource is created for the primary `Merchant` defined at the root level of the split transaction. #### 2. Adjustment Transfer Created When Finix pulls funds (chargeback), a dispute adjustment `Transfer` is created for the full `Dispute` › `amount`. This `Transfer` includes a `split_transfers` array containing IDs for each participant. The dispute adjustment will not be put in a settlement. **Key fields on the adjustment transfer:** - `type: DISPUTE` — Indicates this is a dispute adjustment `Transfer` - `subtype: MERCHANT_DEBIT` — Funds are being pulled from merchants (proportionally from all merchants, not just the primary) - `split_transfers` — Array of `Split Transfer` IDs representing each participant's proportional share ```json { "id": "TRpxCZRBtMbcGYbtvCxVYSpe", "created_at": "2025-06-25T18:46:18.52Z", "updated_at": "2025-06-25T18:46:18.52Z", "amount": 1000, // [!code highlight] "amount_requested": 1000, "application": "APc9vhYcPsRuTSpKD9KpMtPe", "currency": "USD", "destination": null, "fee": 0, "merchant": "MUmfEGv5bMpSJ9k5TFRUjkmm", "merchant_identity": "ID6UfSm1d4WPiWgLYmbyeo3H", "split_transfers": [ // [!code highlight] "split_transfer_6iVWXfDjxm84cvTeNZNXPc", // [!code highlight] "split_transfer_6iW81ie9XwDyttX4sWK3cg" // [!code highlight] ], // [!code highlight] "state": "SUCCEEDED", "subtype": "MERCHANT_DEBIT", // [!code highlight] "type": "DISPUTE", // [!code highlight] ... } ``` #### 3. Split Transfers Created Each `Split Transfer` has `type: DISPUTE_MERCHANT_DEBIT` and an amount proportional to the merchant's share of the original sale. **Split Transfer for Merchant A (primary) - 60% of $10.00 = $6.00**: ```json { "id": "split_transfer_6iVWXfDjxm84cvTeNZNXPc", "amount": 600, // [!code highlight] "currency": "USD", "merchant_id": "MUmfEGv5bMpSJ9k5TFRUjkmm", "parent_transfer_id": "TRpxCZRBtMbcGYbtvCxVYSpe", "type": "DISPUTE_MERCHANT_DEBIT", // [!code highlight] ... } ``` **Split Transfer for Merchant B - 40% of $10.00 = $4.00**: ```json { "id": "split_transfer_6iW81ie9XwDyttX4sWK3cg", "amount": 400, // [!code highlight] "currency": "USD", "merchant_id": "MU7noQ1wdgdAeAfymw2rfBMq", "parent_transfer_id": "TRpxCZRBtMbcGYbtvCxVYSpe", "type": "DISPUTE_MERCHANT_DEBIT", // [!code highlight] ... } ``` #### 4. Settlement Entries Created `Settlement Entries` are created for each `Split Transfer`. The adjustment `Transfer` itself is **not** placed in a settlement—instead, `Settlement Entries` reference each `Split Transfer`. **Key fields on the settlement entry:** - `entity_type: SPLIT_TRANSFER` — Indicates this entry is for a `Split Transfer` - `subtype: DISPUTE_MERCHANT_DEBIT` — Mirrors the `Split Transfer` › `type`, indicating funds are being pulled due to a `Dispute` **Settlement Entry for Merchant A's Split Transfer ($6.00)**: ```json { "id": "SEmA6iVWXfDjxm84cvTeNZNX", "amount": 600, // [!code highlight] "currency": "USD", "entity_id": "split_transfer_6iVWXfDjxm84cvTeNZNXPc", "entity_type": "SPLIT_TRANSFER", // [!code highlight] "subtype": "DISPUTE_MERCHANT_DEBIT", // [!code highlight] "should_fund": true, ... } ``` **Settlement Entry for Merchant B's Split Transfer ($4.00)**: ```json { "id": "SEmB6iW81ie9XwDyttX4sWK3", "amount": 400, // [!code highlight] "currency": "USD", "entity_id": "split_transfer_6iW81ie9XwDyttX4sWK3cg", "entity_type": "SPLIT_TRANSFER", // [!code highlight] "subtype": "DISPUTE_MERCHANT_DEBIT", // [!code highlight] "should_fund": true, ... } ``` #### Rounding When proportional calculations result in amounts that don't divide evenly, the primary merchant absorbs the rounding difference to ensure the total equals exactly the dispute amount. #### Dispute Outcomes - **Ruled in favor of buyer**: No additional money movement occurs - **Ruled in favor of merchant**: A `MERCHANT_CREDIT` adjustment `Transfer` is created with `Split Transfers` of `type: DISPUTE_MERCHANT_CREDIT`, returning funds proportionally to each `Merchant`. For more information on disputes in general, see [Disputes](/guides/after-the-payment/disputes/how-disputes-work). ## ACH Returns How ACH returns for split transactions are handled is configured on the Application-level by Finix. To view how your Application is configured, use the [Retrieve an Application](https://finix.com/docs/api/applications/getapplication) endpoint. The `split_transfer_configuration` object shows how ACH returns are handled for the `Application`. By default, the primary merchant will be debited for the return. To change the default behavior, contact your Finix point of contact or email [Finix Support](/guides/getting-started/support-at-finix). There are two options for how the return can be handled: ### Option 1 - Primary Merchant-only Debited for ACH Return (default) The default behavior is to apply the return amount to the primary merchant only. The `Application` › `split_transfer_configuration` ACH settings are set to `PRIMARY_MERCHANT` for all ACH returns. ```json { "id": "AP7jSy5H46TXXo8MsTWHcfNK", "created_at": "2025-03-21T16:03:17.13Z", "updated_at": "2025-05-20T22:21:01.35Z", ... "split_transfer_configuration": { // [!code highlight] "ach_debit_return_strategy": "PRIMARY_MERCHANT", // [!code highlight] "ach_credit_return_strategy": "PRIMARY_MERCHANT", // [!code highlight] } // [!code highlight] ... } ``` ### Option 2 - Proportionally Distribute Amounts against Original Merchants Ratio To enable this option, reach out to [Finix Support](mailto:support@finix.com). The other option is to proportionally distribute the return amount against the original merchants ratio. For example, if Merchant A and Merchant B are 60/40 and the return is $10.00, Merchant A would be debited $6.00 and Merchant B would be debited $4.00. The `Application` › `split_transfer_configuration` ACH settings are set to `PROPORTIONALLY_DISTRIBUTE_AMOUNTS_AGAINST_ORIGINAL_MERCHANTS_RATIO` for all ACH returns. ```json { "id": "AP7jSy5H46TXXo8MsTWHcfNK", "created_at": "2025-03-21T16:03:17.13Z", "updated_at": "2025-05-20T22:21:01.35Z", ... "split_transfer_configuration": { // [!code highlight] "ach_debit_return_strategy": "PROPORTIONALLY_DISTRIBUTE_AMOUNTS_AGAINST_ORIGINAL_MERCHANTS_RATIO", // [!code highlight] "ach_credit_return_strategy": "PROPORTIONALLY_DISTRIBUTE_AMOUNTS_AGAINST_ORIGINAL_MERCHANTS_RATIO", // [!code highlight] } // [!code highlight] ... } ``` #### 1. ACH Return When an ACH Direct Debit fails, Finix automatically creates an ACH Return to recover the original payment amount. The `Transfer` will have: - `split_transfers` array containing IDs for each participant. - `subtype: SYSTEM` to indicate that the `Transfer` was created by Finix. - The return reason code will appear in the `tags` field (e.g., `"result_message_0": "ReasonCode: R04")`. - `type: REVERSAL` to indicate that the `Transfer` is a reversal of the original `Transfer`. ```json ACH Return For Split Transaction { "id": "TR8K7zFd9wvEwAG7AvCMLShg", "created_at": "2025-07-29T17:19:11.26Z", "updated_at": "2025-07-29T17:20:02.68Z", ... "parent_transfer": "TRjAnCNNSxDCW8GDsxYobHHe", // [!code highlight] "split_transfers": [ // [!code highlight] "split_transfer_6iVWXfDjxm84cvTeNZNXPc", // [!code highlight] "split_transfer_6iW81ie9XwDyttX4sWK3cg" // [!code highlight] ], // [!code highlight] "subtype": "SYSTEM", // [!code highlight] "supplemental_fee": null, "tags": { "result_message_0": "ReasonCode: R04", // [!code highlight] "result_message_1": "ReasonDescription: Invalid Account Number", // [!code highlight] }, "third_party_details": null, "tip_amount": null, "trace_id": "2cdfa359-b9d5-4185-aa66-252a00001ea5", "type": "REVERSAL", // [!code highlight] ... } ``` #### 2. Split Transfers Created Each `Split Transfer` has `type: CREDIT` and an amount proportional to the merchant's share of the original sale. **Split Transfer for Merchant A (primary) - 60% of $10.00 = $6.00**: ```json { "id": "split_transfer_6iVWXfDjxm84cvTeNZNXPc", "amount": 600, // [!code highlight] "currency": "USD", "merchant_id": "MUmfEGv5bMpSJ9k5TFRUjkmm", "parent_transfer_id": "TR8K7zFd9wvEwAG7AvCMLShg", "type": "CREDIT", // [!code highlight] ... } ``` **Split Transfer for Merchant B - 40% of $10.00 = $4.00**: ```json { "id": "split_transfer_6iW81ie9XwDyttX4sWK3cg", "amount": 400, // [!code highlight] "currency": "USD", "merchant_id": "MU7noQ1wdgdAeAfymw2rfBMq", "parent_transfer_id": "TR8K7zFd9wvEwAG7AvCMLShg", "type": "CREDIT", // [!code highlight] ... } ``` #### 3. Settlement Entries Created `Settlement Entries` are created for each `Split Transfer`. The adjustment `Transfer` itself is **not** placed in a settlement—instead, `Settlement Entries` reference each `Split Transfer`. **Key fields on the settlement entry:** - `entity_type: SPLIT_TRANSFER` — Indicates this entry is for a `Split Transfer` - `subtype: CREDIT` — Mirrors the `Split Transfer` › `type` indicates this is a credit entry. **Settlement Entry for Merchant A's Split Transfer ($6.00)**: ```json { "id": "SEmA6iVWXfDjxm84cvTeNZNX", "amount": 600, // [!code highlight] "currency": "USD", "entity_id": "split_transfer_6iVWXfDjxm84cvTeNZNXPc", "entity_type": "SPLIT_TRANSFER", // [!code highlight] "subtype": "CREDIT", // [!code highlight] "should_fund": true, ... } ``` **Settlement Entry for Merchant B's Split Transfer ($4.00)**: ```json { "id": "SEmB6iW81ie9XwDyttX4sWK3", "amount": 400, // [!code highlight] "currency": "USD", "entity_id": "split_transfer_6iW81ie9XwDyttX4sWK3cg", "entity_type": "SPLIT_TRANSFER", // [!code highlight] "subtype": "CREDIT", // [!code highlight] "should_fund": true, ... } ``` #### Rounding When proportional calculations result in amounts that don't divide evenly, the primary merchant absorbs the rounding difference to ensure the total equals exactly the ACH return amount.