Split Transactions
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
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

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 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.

Please note, the primary merchant is the merchant specified in the parent Transfer request; outside the split_transfers object.

curl 'https://finix.sandbox-payments-api.com/transfers' \
    -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",
        "split_transfers": [
            {
                "merchant": "MUeDVrf2ahuKc9Eg5TeZugvs",
                "amount": 600,
                "tags": {
                    "key": "value"
                }
            },
            {
                "merchant": "MUeHUEPKybMjqV1STcqrFTSH",
                "amount": 300,
                "fee": 100
            },
            {
                "merchant": "MU3Gh6DT5fCBxVtWB8VJc1St",
                "amount": 100
            }
        ],
        "tags": {
            "test": "sale"
        }
    }'

Example response:

{
    "id": "TR7mf5xW2FwezkGmBPdHXVpi",
    "created_at": "2023-08-10T21:16:41.57Z",
    "updated_at": "2023-08-10T21:16:44.11Z",
    "additional_buyer_charges": null,
    "additional_healthcare_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": [],
    "raw": null,
    "ready_to_settle_at": null,
    "receipt_last_printed_at": null,
    "security_code_verification": null,
    "source": "PIe2YvpcjvoVJ6PzoRPBK137",
    "split_transfers": [
        "split_transfer_7nfcfAAuYNMLjHrZqZ1Yi4",
        "split_transfer_7ng4V9b9wcFqQ6LaUct3HK",
        "split_transfer_7ng5bY47roz8yzush1MPqe"
    ],
    "state": "SUCCEEDED",
    "statement_descriptor": "FNX*DUNDER MIFFLIN",
    "subtype": "API",
    "tags": {
        "test": "sale"
    },
    "trace_id": "ab240c39-e71f-4061-aae0-d55edfd9503a",
    "type": "DEBIT",
    "_links": {
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "self": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TR7mf5xW2FwezkGmBPdHXVpi"
        },
        "merchant_identity": {
            "href": "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg"
        },
        "payment_instruments": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TR7mf5xW2FwezkGmBPdHXVpi/payment_instruments"
        },
        "reversals": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TR7mf5xW2FwezkGmBPdHXVpi/reversals"
        },
        "fees": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TR7mf5xW2FwezkGmBPdHXVpi/fees"
        },
        "disputes": {
            "href": "https://finix.sandbox-payments-api.com/transfers/TR7mf5xW2FwezkGmBPdHXVpi/disputes"
        },
        "source": {
            "href": "https://finix.sandbox-payments-api.com/payment_instruments/PIe2YvpcjvoVJ6PzoRPBK137"
        },
        "fee_profile": {
            "href": "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8"
        }
    }
}

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
`merchant`	string, required	ID of the primary `Merchant` that's processing the `Transfer` for the buyer.
`source`	string, required	ID of the `Payment Instrument` that will be debited
`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)

Request Arguments - Split Transfers Object

Field	Type	Description
`amount`	integer, required	The amount of funds that get split and paid out to the specified`Merchant.` 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)

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.

curl "https://finix.sandbox-payments-api.com/split_transfers/split_transfer_2mrYGrTdRiWiLLQU1dkMWX" \
    -H "Content-Type: application/json" \
    -H "Finix-Version: 2022-02-01" \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Example response:

{
    "id": "split_transfer_2mrYGrTdRiWiLLQU1dkMWX",
    "created_at": "2023-08-08T20:27:49.36Z",
    "updated_at": "2023-08-08T20:27:49.36Z",
    "amount": 600,
    "application_id": "APgPDQrLD52TYvqazjHJJchM",
    "currency": "USD",
    "fee": 0,
    "fee_profile_id": "FPbDSnEPtaT8Nttxj9NJk7eC",
    "identity_id": "IDuqZpDw28f2KK6YuDk4jNLg",
    "merchant_id": "MUeDVrf2ahuKc9Eg5TeZugvs",
    "parent_transfer_id": "TR2kKxKDu2nJCvjD2djuDktv",
    "ready_to_settle_at": "2023-08-08T20:27:50.22Z",
    "tags": {
        "key": "value"
    },
    "type": "DEBIT"
}

Split Transfer Response

Field	Type	Description
`id`	string	The unique ID of the `split_transfer` object.
`created_at`	string	The date and time the `split_transfer` was created.
`updated_at`	string	The date and time the `split_transfer` was last updated.
`amount`	string	The amount allocated to this `Merchant` in the `split_transfer.`
`fee`	integer	The minimum amount of the `Transfer` you'd like to collect as your fee in cents. Defaults to zero (must be less than or equal to the `amount` in the parent `Transfer`).
`currency`	string	ISO 4217 three-letter currency code for the `split_transfer.`
`parent_transfer_id`	string	ID of the original parent `Transfer` where the split was defined.
`ready_to_settle_at`	string	Timestamp of when the `split_transfer` is ready to be settled at.
`merchant_id`	string	The ID of the `Merchant` that received the `split_transfer.`
`fee_profile_id`	string	The `fee_profile` associated to this `split_transfer.`
`application_id`	string	The `application_id` associated to this `split_transfer.`
`tags`	object	Key value pair for annotating custom metadata (e.g. order numbers).

Finix Dashboard

Split Transactions appear on the Finix Dashboard under Payments.

You can identify Split Transactions using the Payment Type in the Amount column:

Click on the individual entry to review the Split Transaction in detail:

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.

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:

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

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:

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

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

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:

{
    "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 specified`Merchant.` 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.

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.

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:

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

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

Settlement Entries

To query all the transactions for a specific settlement, use the following API:

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:

{
    "_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.
Any fees included in split_transfer#fee when the initial Transfer was first created. For more information, see Create a Transfer.
If charge_interchange is enabled in the seller's fee_profile, they'll be charged interchange for the full transaction amount.

Disputes

If a buyer disputes a transaction split across multiple sellers, a Dispute only gets created for the primary Merchant.

For more information, see Disputes.

Split TransactionsCopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from ClaudeConnect to CursorInstall MCP server on CursorConnect to VS CodeInstall MCP server on VS Code

Splitting a Transfer across Sellers

Finix API

HTTP Request

Request Arguments

Request Arguments - Split Transfers Object

Split Transfers

Split Transfer Response

Finix Dashboard

Splitting a Capture across Sellers

Step 1: Create an Authorization

Step 2: Create a Capture

Splitting a Card Present Transaction

HTTP Request

Request Arguments

Request Arguments - Split Transfers Object

Refunding Split Transactions

Settlements and Payouts

Settlement Entries

Response

Fees

Disputes

Was this helpful?

Split Transactions
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
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code