Split Transactions

Learn how to split a transaction across multiple sellers or recipients.

Split Transactions

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

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

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

Finix Dashboard

Split Transactions appear on the Finix Dashboard under Payments.

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

Split

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

Split-1

Splitting a Capture

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.

Copy

Copied

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:

Copy

Copied

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

Copy

Copied

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:

Copy

Copied

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

Copy

Copied

{
  "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 Transaction to Recipients

You can also split the funds from transactions with individuals, small businesses, or non-commercial entities that don't need a full seller account.

Note: Please reach out to your Finix point of contact or the Finix Support team before creating a recipient Identity.

Step 1: Create an Identity for your Recipient

You can create either a personal or business recipient Identity.

Personal Recipient: For personal recipients, first_name , last_name , and personal_address are required when creating a recipient Identity .
Business Recipient: For business recipients, business_name , doing_business_as , and business_address are required when creating a business recipient Identity . In addition, we require a control owner with first_name , last_name , and personal_address .

Personal RecipientBusiness Recipient

Copy

Copied

curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '{
    "identity_roles" : ["RECIPIENT"],
    "entity": {
      "phone": "7145677613",
      "first_name": "John",
      "last_name": "Smith",
      "email": "example@finix.com",
      "personal_address": {
        "city": "San Mateo",
        "country": "USA",
        "region": "CA",
        "line2": "Apartment 7",
        "line1": "741 Douglass St",
        "postal_code": "94114"
      }
    },
    "tags": {
      "key": "value"
    }
  }'

Copy

Copied

curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '{
    "identity_roles" : ["RECIPIENT"],
    "entity": {
      "business_name" : "ABC Corporation",
      "doing_business_as" : "ABC Corp",
      "business_phone" : "+1 (408) 756-4497",
      "business_address" : {
        "line1" : "123 Main Street",
        "line2" : "Suite 101",
        "city" : "San Francisco",
        "region" : "CA",
        "postal_code" : "94114",
        "country" : "USA"
      },
      "phone": "7145677613",
      "first_name": "John",
      "last_name": "Smith",
      "email": "example@finix.com",
      "personal_address": {
        "city": "San Mateo",
        "country": "USA",
        "region": "CA",
        "line2": "Apartment 7",
        "line1": "741 Douglass St",
        "postal_code": "94114"
      }
    },
    "tags": {
      "key": "value"
    }
  }'

Example Response

Copy

Copied

{
  "id" : "IDmu6JXQ3p4KJCygFLq5kFCe",
  "created_at" : "2024-01-10T18:14:36.37Z",
  "updated_at" : "2024-01-10T18:14:36.37Z",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "entity" : {
    "ach_max_transaction_amount" : 0,
    "amex_mid" : null,
    "annual_card_volume" : 0,
    "business_address" : null,
    "business_name" : null,
    "business_phone" : null,
    "business_tax_id_provided" : false,
    "business_type" : null,
    "default_statement_descriptor" : null,
    "discover_mid" : null,
    "dob" : null,
    "doing_business_as" : null,
    "email" : "example@finix.com",
    "first_name" : "John",
    "has_accepted_credit_cards_previously" : false,
    "incorporation_date" : null,
    "last_name" : "Smith",
    "max_transaction_amount" : 0,
    "mcc" : null,
    "ownership_type" : null,
    "personal_address" : {
      "line1" : "741 Douglass St",
      "line2" : "Apartment 7",
      "city" : "San Mateo",
      "region" : "CA",
      "postal_code" : "94114",
      "country" : "USA"
    },
    "phone" : "7145677613",
    "principal_percentage_ownership" : null,
    "short_business_name" : null,
    "tax_authority" : null,
    "tax_id_provided" : false,
    "title" : null,
    "url" : null
  },
  "identity_roles" : [ "RECIPIENT" ],
  "tags" : {
    "key" : "value"
  },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmu6JXQ3p4KJCygFLq5kFCe"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmu6JXQ3p4KJCygFLq5kFCe/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmu6JXQ3p4KJCygFLq5kFCe/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmu6JXQ3p4KJCygFLq5kFCe/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmu6JXQ3p4KJCygFLq5kFCe/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmu6JXQ3p4KJCygFLq5kFCe/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmu6JXQ3p4KJCygFLq5kFCe/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmu6JXQ3p4KJCygFLq5kFCe/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmu6JXQ3p4KJCygFLq5kFCe/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    }
  }
}

Step 2: Add a Bank Account Payment Instrument for each Recipient

Now that we've created an Identity for our recipient, we'll need to create a bank account Payment Instrument using the recipient's card details. When creating Payment Instruments for Payouts, attemptbankaccountvalidationcheck must be set to true.

Copy

Copied

curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
	  {
      "account_number": "123123123",
      "account_type": "PERSONAL_CHECKING",
      "bank_code": "123123123",
      "identity": "IDmu6JXQ3p4KJCygFLq5kFCe",
      "name": "John Smith",
      "type": "BANK_ACCOUNT",
      "attempt_bank_account_validation_check": true
	  }'

Example Response

Copy

Copied

{
  "id" : "PIvpu9E241HkGk1ZPQNp78Eu",
  "created_at" : "2024-01-10T18:18:16.14Z",
  "updated_at" : "2024-01-10T18:18:16.14Z",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "created_via" : "API",
  "currency" : "USD",
  "disabled_code" : null,
  "disabled_message" : null,
  "enabled" : true,
  "fingerprint" : "FPRd5moHxL3Ltuvk4cczxetCg",
  "identity" : "IDmu6JXQ3p4KJCygFLq5kFCe",
  "instrument_type" : "BANK_ACCOUNT",
  "account_type" : "PERSONAL_CHECKING",
  "bank_account_validation_check" : "INCONCLUSIVE",
  "bank_code" : "123123123",
  "country" : "USA",
  "institution_number" : null,
  "masked_account_number" : "XXXXX3123",
  "name" : "John Smith",
  "transit_number" : null,
  "tags" : { },
  "type" : "BANK_ACCOUNT",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvpu9E241HkGk1ZPQNp78Eu"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvpu9E241HkGk1ZPQNp78Eu/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvpu9E241HkGk1ZPQNp78Eu/transfers"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIvpu9E241HkGk1ZPQNp78Eu/verifications"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmu6JXQ3p4KJCygFLq5kFCe"
    }
  }
}%

HTTP Request

POST https://finix.sandbox-payments-api.com/payment_instruments

Request Arguments

Field	Type	Description
`account_number`	string, required	Bank account number
`account_type`	string, required	Either CHECKING or SAVINGS
`attempt_bank_account_validation_check`	boolean, required	Set to true to request a bank account validation.
`bank_code`	string, required	Bank routing number
`country`	string, optional	Country code
`identity`	string, required	ID for the `Identity` resource which the account is associated
`name`	string, required	Account owner's full name (max 40 characters)
`type`	string, required	Type of `Payment Instrument` (for bank accounts use `BANK_ACCOUNT`)

Step 3: Provision Recipient

Copy

Copied

curl https://finix.sandbox-payments-api.com/identities/IDmu6JXQ3p4KJCygFLq5kFCe/merchants \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
	{
	    "processor": "DUMMY_V1" 
	}'

Example Response

Copy

Copied

{
  "id" : "MUcRfcGqNQnkZSW9Lb7re9gd",
  "created_at" : "2024-01-10T18:19:13.87Z",
  "updated_at" : "2024-01-10T18:19:13.87Z",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "card_cvv_required" : false,
  "card_expiration_date_required" : true,
  "convenience_charges_enabled" : false,
  "country" : "USA",
  "creating_transfer_from_report_enabled" : true,
  "currencies" : [ "USD" ],
  "default_partial_authorization_enabled" : false,
  "disbursements_ach_pull_enabled" : false,
  "disbursements_ach_push_enabled" : false,
  "disbursements_card_pull_enabled" : false,
  "disbursements_card_push_enabled" : false,
  "fee_ready_to_settle_upon" : "RECONCILIATION",
  "gateway" : null,
  "gross_settlement_enabled" : false,
  "identity" : "IDmu6JXQ3p4KJCygFLq5kFCe",
  "level_two_level_three_data_enabled" : false,
  "mcc" : null,
  "merchant_name" : "John Smith",
  "merchant_profile" : "MP82v72JXrRs6JGYe2rqHDw7",
  "mid" : null,
  "onboarding_state" : "PROVISIONING",
  "processing_enabled" : false,
  "processor" : "DUMMY_V1",
  "processor_details" : { },
  "ready_to_settle_upon" : "RECONCILIATION",
  "rent_surcharges_enabled" : false,
  "settlement_enabled" : false,
  "settlement_funding_identifier" : "UNSET",
  "surcharges_enabled" : false,
  "tags" : { },
  "verification" : "VI7nqsnnuFZHWddLSULbqfhj",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUcRfcGqNQnkZSW9Lb7re9gd"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDmu6JXQ3p4KJCygFLq5kFCe"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUcRfcGqNQnkZSW9Lb7re9gd/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MP82v72JXrRs6JGYe2rqHDw7"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VI7nqsnnuFZHWddLSULbqfhj"
    }
  }
}%

HTTP Request

POST https://finix.sandbox-payments-api.com/identities/:IDENTITY_ID:/merchants

URL Parameters

`Parameter`	Description
:IDENTITY_ID:	ID of the `Identity`

Request Arguments

Field	Type	Description
`processor`	string, required	Use `DUMMY_V1` for sandbox tests For live transactions, reach out to your Finix point of contact or Finix Support.
`tags`	object, optional	Key value pair for annotating custom metadata (e.g. order numbers)

Step 4: Split a Transaction

Next, when creating the transaction, use the Merchant created from the RECIPIENT Identity in the split_transfers array.

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": 1050,
    "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
      },
      {
        "merchant": "MUcRfcGqNQnkZSW9Lb7re9gd",
        "amount": 50
      }
    ],
    "tags": {
      "test": "sale"
    }
  }'

Example Response

Copy

Copied

{
  "id" : "TRuVoitEfMbrjATNrA38GXa1",
  "created_at" : "2024-01-10T18:20:21.17Z",
  "updated_at" : "2024-01-10T18:20:23.57Z",
  "additional_buyer_charges" : null,
  "additional_healthcare_data" : null,
  "additional_purchase_data" : null,
  "address_verification" : null,
  "amount" : 1050,
  "amount_requested" : 1050,
  "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" : null,
  "receipt_last_printed_at" : null,
  "security_code_verification" : null,
  "source" : "PIe2YvpcjvoVJ6PzoRPBK137",
  "split_transfers" : [ "split_transfer_uWvCFiuJ1Hn1hPQwid9qxy", "split_transfer_uWw3LWFeJLHLhuwKZbReEu", "split_transfer_uWw47W6VQUnAFBoAxgMgN3", "split_transfer_uWwnPoWWzyvBLVUea6aaop" ],
  "state" : "SUCCEEDED",
  "statement_descriptor" : "FNX*DUNDER MIFFLIN",
  "subtype" : "API",
  "tags" : {
    "test" : "sale"
  },
  "trace_id" : "52ebe6bd-c08e-4691-91b8-06c25b5df9db",
  "type" : "DEBIT",
  "_links" : {
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRuVoitEfMbrjATNrA38GXa1"
    },
    "merchant_identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDuqZpDw28f2KK6YuDk4jNLg"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRuVoitEfMbrjATNrA38GXa1/payment_instruments"
    },
    "reversals" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRuVoitEfMbrjATNrA38GXa1/reversals"
    },
    "fees" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRuVoitEfMbrjATNrA38GXa1/fees"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/transfers/TRuVoitEfMbrjATNrA38GXa1/disputes"
    },
    "source" : {
      "href" : "https://finix.sandbox-payments-api.com/payment_instruments/PIe2YvpcjvoVJ6PzoRPBK137"
    },
    "fee_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/fee_profiles/FPvCQUcnsueN3Bc3zR1qCBG8"
    }
  }
}

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

Copy

Copied

 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:

Copy

Copied

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