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 get split between Merchants created under the same Application.
  • Each split_transfer get placed into the Settlement of the split_transfers#merchant.
  • No changes need to be made to your Application or Merchants to enable Split Transactions.
Attention

Split Transactions are only available for Finix Flex customers in sandbox environments (DUMMY_V1). Additionally, Split Transactions is currently in early access and subject to further changes. For more information, reach out to the Finix Support team.

Splitting a Transfer

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.

Copy
Copied
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

Copy
Copied
{
  "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 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)

Split Transfers

The split_transfers array returned in the response contains the resource IDs of the split_transfers that got created from the Transfer that was split.

Use the ID to review how the transaction was split for the specified Merchant.

Copy
Copied
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

Copy
Copied
{
  "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).

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.

Copy
Copied
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

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

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

Just like regular Transfers, every split_transfer gets placed into a Settlement.

Merchants get paid out when Settlements are approved. For more information, see Payouts.

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.