Accept split payments

Split Payments lets platforms and marketplaces distribute the funds of a single payment across multiple recipients. When a customer pays through a Checkout Session, Fintoc splits the payout according to your rules and transfers each share to the recipient’s own bank account. You do not need manual transfers or reconciliation on your side. Each recipient is an Entity: the legal holder that receives a share of the payment. An Entity declares the account where it gets paid as part of its onboarding, so there is no separate account resource to manage. There are three steps to accept split payments:

Create an Entity for each recipient
Onboard the Entity, including the account where it will be paid
Create a Checkout Session with a split array, then send the customer to its redirect_url

Before you begin

Before you start, make sure you have:

A Fintoc account with Collects enabled
Your Secret Key and Public Key
Recipient business and bank account information for each Entity you need to onboard

Step 1: Create an Entity

An Entity represents the legal holder that receives a share of a payment, such as a seller, a partner, a professional, or a business unit.

curl --request POST "https://api.fintoc.com/v2/entities" \
--header 'Authorization: YOUR_TEST_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "country_code": "CL",
  "holder_name": "Test Merchant 1 SpA",
  "holder_id": "111111111"
}'

Param	Type	Required	Description
`country_code`	string	Yes	ISO 3166-1 alpha-2 country code. One of `CL` (Chile) or `MX` (Mexico).
`holder_name`	string	Yes	Legal name of the entity holder.
`holder_id`	string	Yes	Tax ID without formatting. Chilean tax ID (RUT) in Chile, Mexican tax ID (RFC) in Mexico. Must be unique within your organization.

{
  "id": "ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN",
  "object": "entity",
  "country_code": "cl",
  "holder_id": "111111111",
  "holder_name": "Test Merchant 1 SpA",
  "is_root": false,
  "mode": "live",
  "status": "waiting_initialization",
  "capabilities": {
    "settlement_recipient": {
      "status": "waiting_initialization"
    },
    "account_holder": {
      "status": "waiting_initialization"
    }
  }
}

A new Entity’s settlement_recipient capability starts in waiting_initialization. It cannot receive a split until capabilities.settlement_recipient.status reaches operational. Fintoc sets this status after it approves the onboarding. The top-level status reflects the Entity’s most advanced capability. Use the capability status to determine whether the Entity is available for Split Payments.

If the recipient already exists as an Entity in your organization, reuse its id. Creating a second Entity with the same holder_id returns 409 entity_holder_id_already_exists_for_organization.

List and retrieve entities with GET /v2/entities, which accepts holder_id, status, and is_root filters, and GET /v2/entities/{id}.

Step 2: Onboard the Entity

During onboarding, the Entity declares who it is and the bank account where Fintoc pays split funds. Fintoc reviews the onboarding. After approval, the Entity’s settlement_recipient capability becomes operational. You complete onboarding through the API in Chile and Mexico.

Create the onboarding

curl --request POST "https://api.fintoc.com/v2/entities/ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN/onboardings" \
--header 'Authorization: YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "type": "settlement_recipient",
  "data": {
    "company_information": {
      "business_activity": "Servicios de arquitectura",
      "business_address": "Av. Apoquindo 100, Santiago, Region Metropolitana, 7550000, Chile",
      "phone": "+56 9 1111 1111",
      "settlement_account": {
        "institution_id": "cl_banco_de_chile",
        "account_number": "123456789",
        "account_type": "checking_account"
      }
    },
    "legal_representatives": [
      {
        "first_name": "Test",
        "last_name": "Customer 1",
        "email": "test@mail.com",
        "nationality": "CL",
        "identification_number": "111111111",
        "position": "Representante legal"
      }
    ]
  }
}'

Onboarding type

type is required when you create the onboarding. It declares what the Entity will do with Fintoc and determines how much information the onboarding asks for. You cannot change it after creation. settlement_recipient: The Entity only receives money. Fintoc transfers its share of each split to the bank account in settlement_account. The Entity does not hold a balance at Fintoc, receive transfers from third parties, or send money out. Because the Entity only gets paid, the onboarding asks for the minimum needed to identify who is being paid. This is the value to use for Split Payments. account_holder: the Entity operates an account at Fintoc. It can receive incoming transfers, send outgoing ones, and hold a balance. That capability carries a higher risk profile, so the onboarding requires the full set of information: transactional profile, ownership structure, and supporting documents.

The settlement account

Fintoc transfers each recipient’s share of every split to data.company_information.settlement_account. The settlement_account field is the only Split Payments addition to the onboarding. Required settlement_account fields depend on the recipient’s country_code.

Chile

Param	Type	Required	Description
`institution_id`	string	Yes	Bank identifier. See Chile institution codes.
`account_number`	string	Yes	Account number.
`account_type`	string	Yes	One of `checking_account` or `sight_account`.

Mexico

Param	Type	Required	Description
`account_number`	string	Yes	Standardized Mexican bank account number (CLABE), 18 digits. Fintoc derives the bank identifier from the CLABE. Do not send `institution_id` or `account_type`.

The settlement_account field carries no holder fields. The account holder is the Entity being onboarded, so the tax ID is already known.

An Entity has exactly one settlement account. To change it, create a new onboarding. See Changing the settlement account.

Onboarding fields

Block	Required	What it declares
`type`	Yes	Onboarding type. One of `settlement_recipient` (receives split payments) or `account_holder` (operates a Fintoc account). Use `settlement_recipient` for Split Payments.
`data`	Yes	Container for `company_information` and any optional onboarding blocks.
`data.company_information`	Yes	Business information for the Entity.
`data.company_information.settlement_account`	Yes	Account that receives the Entity’s split funds. Required for natural-person and company Entities.
`data.company_information.business_activity`	Required for Mexican companies. Optional for Chilean companies.	Business activity of the Entity.
`data.company_information.business_address`	Required for Mexican companies. Optional for Chilean companies.	Business address of the Entity.
`data.company_information.phone`	Required for Mexican companies. Optional for Chilean companies.	Contact phone number of the Entity.
`data.legal_representatives[]`	No	Name, email, nationality, identification number, and position of each legal representative. Only processed for company Entities.
`data.transactional_profile`	No	Expected monthly volume, number of operations, and origin of funds. Only processed for company Entities.
`data.shareholders[]`	No	Ownership structure, with each shareholder’s tax ID and participation percentage. Only processed for company Entities.
Documents	No	Supporting files, uploaded per slot with `PUT`. Up to 20 MB each; re-uploading a slot replaces the file.

For Chilean company Entities, business_activity, business_address, and phone are optional. You can omit them from the example above. Mexican company Entities must still send all three.

Submit the onboarding

Once the information is complete, submit it for review:

curl --request POST "https://api.fintoc.com/v2/entities/ent_2daFu0zqqDtZGJaSi2TGI2Mm1nN/onboardings/onbprc_9kQ2mZpLtR4vXn/submit" \
--header 'Authorization: YOUR_SECRET_KEY'

Automatic settlement account validation. When you submit the onboarding, Fintoc validates settlement_account by sending a micro-deposit (1 CLP for Chilean Entities or 0.01 MXN for Mexican Entities). The micro-deposit confirms that the account is active and that its holder matches the Entity’s holder_id. Fintoc runs this validation automatically for every settlement_recipient onboarding submission; you do not need to trigger it separately.

The onboarding moves through these statuses:

Status	Meaning
`pending`	Created, nothing submitted yet.
`in_progress`	Being completed. Fields and documents can still be edited.
`submitted`	Under review by Fintoc. No further edits.
`approved`	Review passed. The Entity’s `settlement_recipient` capability is now `operational` and can receive splits.
`rejected`	Review failed. Create a new onboarding to retry.

Two webhooks tell you the outcome:

entity.onboarding.approved: the Entity is ready to receive splits.
entity.onboarding.rejected: the review failed.

Compliance review typically takes one to two business days. Design your flow so the recipient can be created and shown as pending while the review runs.

Changing the settlement account

Create a new onboarding for the same Entity with the new account. While the new onboarding is under review, the previous account stays in effect and the Entity keeps receiving splits. When Fintoc approves the new onboarding, the new account replaces the previous one. If Fintoc rejects the new onboarding, nothing changes.

Step 3: Create a Checkout Session with `split`

Add a split array to the Checkout Session. Each entry names an Entity and its share.

curl --request POST "https://api.fintoc.com/v2/checkout_sessions" \
--header 'Authorization: YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "amount": 150000,
  "currency": "CLP",
  "customer_email": "buyer@example.com",
  "success_url": "https://merchant.example/success",
  "cancel_url": "https://merchant.example/cancel",
  "metadata": { "order_id": "ORD-1234" },
  "split": [
    { "entity_id": "ent_3fXq9tLbnKmWzR4dHs2VcJ7yP5N", "type": "flat", "amount": 50000 },
    { "entity_id": "ent_5jMw7rTkqZbNxH3cLs9YdV2pF8Q", "type": "flat", "amount": 45000 },
    { "entity_id": "ent_9hPz4mVtkXbLwN6cRs1YdJ5qG3T", "type": "flat", "amount": 30000 },
    { "entity_id": "ent_1cKp8sWnvYbMtQ5hLr7XdF3jZ2R", "type": "flat", "amount": 25000,
      "charge_processing_fee": true }
  ]
}'

Field	Type	Required	Description
`split`	array	No	Rules used to divide the payment. Omit it and 100% of the payout goes to you. When present, it must contain between 1 and 10 entries.
`split[].entity_id`	string	Yes	ID of an Entity whose `settlement_recipient` capability is `operational`.
`split[].type`	string	Yes	`flat` or `percentage`. Every entry must use the same type.
`split[].amount`	integer	Yes	For `flat`, the amount in the smallest currency unit (for example, `150000` for CLP 150,000; CLP has no minor unit). For `percentage`, basis points where `10000` = 100%.
`split[].charge_processing_fee`	boolean	Yes, on exactly one entry	The recipient that absorbs the payment’s processing fee.
`split[].metadata`	object	No	Key-value data attached to this rule. Returned in webhooks.

Split rules must add up to the payment amount exactly. No residual remains. If you keep part of the payment, declare your own root Entity as another entry, as in the example above. Retrieve your root Entity with GET /v2/entities?is_root=true.

Percentages are expressed in basis points. 10000 = 100%, 1000 = 10%, 1 = 0.01%. To assign 90%, send 9000.

The response echoes the split array as you sent it, along with the redirect_url of the payment page. Send the customer there to complete the payment. In webhook payloads (see Step 4), each split entry includes metadata (even when empty) and an explicit charge_processing_fee. Entries that do not absorb the fee return charge_processing_fee: false. At creation time, metadata remains optional and charge_processing_fee only needs to be sent on the entry that absorbs the fee.

Step 4: Handle post-payment events

checkout_session.finished and payment_intent.succeeded include a split_applied array with the amount resolved for each recipient.

{
  "id": "evt_a4xK32BanKWYn",
  "object": "event",
  "type": "checkout_session.finished",
  "data": {
    "id": "cs_li5531onlFDi235",
    "object": "checkout_session",
    "amount": 150000,
    "currency": "CLP",
    "status": "finished",
    "metadata": { "order_id": "ORD-1234" },
    "split": [
      { "entity_id": "ent_3fXq9tLbnKmWzR4dHs2VcJ7yP5N", "type": "flat", "amount": 50000, "charge_processing_fee": false, "metadata": {} },
      { "entity_id": "ent_5jMw7rTkqZbNxH3cLs9YdV2pF8Q", "type": "flat", "amount": 45000, "charge_processing_fee": false, "metadata": {} },
      { "entity_id": "ent_9hPz4mVtkXbLwN6cRs1YdJ5qG3T", "type": "flat", "amount": 30000, "charge_processing_fee": false, "metadata": {} },
      { "entity_id": "ent_1cKp8sWnvYbMtQ5hLr7XdF3jZ2R", "type": "flat", "amount": 25000, "charge_processing_fee": true, "metadata": {} }
    ],
    "split_applied": [
      {
        "entity_id": "ent_3fXq9tLbnKmWzR4dHs2VcJ7yP5N",
        "calculated_amount": 50000,
        "charge_processing_fee": false
      },
      {
        "entity_id": "ent_5jMw7rTkqZbNxH3cLs9YdV2pF8Q",
        "calculated_amount": 45000,
        "charge_processing_fee": false
      },
      {
        "entity_id": "ent_9hPz4mVtkXbLwN6cRs1YdJ5qG3T",
        "calculated_amount": 30000,
        "charge_processing_fee": false
      },
      {
        "entity_id": "ent_1cKp8sWnvYbMtQ5hLr7XdF3jZ2R",
        "calculated_amount": 25000,
        "charge_processing_fee": true
      }
    ],
    "payment_resource": {
      "payment_intent": {
        "id": "pi_38DNJo3rbvGUzKFvCGZ6dxR1Kxx",
        "object": "payment_intent",
        "status": "succeeded",
        "split_applied": [
          {
            "entity_id": "ent_3fXq9tLbnKmWzR4dHs2VcJ7yP5N",
            "calculated_amount": 50000,
            "charge_processing_fee": false
          },
          {
            "entity_id": "ent_5jMw7rTkqZbNxH3cLs9YdV2pF8Q",
            "calculated_amount": 45000,
            "charge_processing_fee": false
          },
          {
            "entity_id": "ent_9hPz4mVtkXbLwN6cRs1YdJ5qG3T",
            "calculated_amount": 30000,
            "charge_processing_fee": false
          },
          {
            "entity_id": "ent_1cKp8sWnvYbMtQ5hLr7XdF3jZ2R",
            "calculated_amount": 25000,
            "charge_processing_fee": true
          }
        ]
      }
    }
  }
}

split_applied appears twice on checkout_session.finished: once on the checkout_session itself and once inside data.payment_resource.payment_intent. Both arrays carry the exact same content, so you can read either one. The nested copy is the same array delivered by payment_intent.succeeded, which fires alongside checkout_session.finished.

checkout_session.finished can arrive before the payment has reached a final state. Mark the order as paid only when data.payment_resource.payment_intent.status is succeeded.

Events to handle:

Event	When
`checkout_session.finished`	The session reached a final state. Includes `split` and `split_applied`.
`checkout_session.expired`	The session expired before payment.
`payment_intent.succeeded`	The payment succeeded.
`payment_intent.failed`	The payment failed.
`payment_intent.requires_action`	The payment needs an extra action from the payer.
`payout.created`	A payout to a recipient was created for the settlement cycle.
`payout.succeeded`	The payout reached the recipient’s account.
`payout.canceled`	The payout was canceled and will not be sent.
`payout.returned`	The bank returned a successful payout. Mexico only.
`entity.onboarding.approved`	The Entity passed review and can receive splits.
`entity.onboarding.rejected`	The review failed.

How and when recipients are paid

Payouts follow your organization’s settlement schedule. In each cycle, Fintoc groups every share owed to the same Entity into one transfer to its settlement account. For example, a recipient that appears in 200 payments during a cycle receives a single transfer. Retrieve a payout with GET /v1/payouts/{id}, list them with GET /v1/payouts, and get the payments it covers with GET /v1/payouts/{id}/resources.

payout.* events fire only in live mode. Payouts settle against real balances, so test mode does not emit payout.created, payout.succeeded, payout.canceled, or payout.returned.

Rules and validations

Fintoc validates the split array when you create a Checkout Session. The request fails with 400 Bad Request and invalid_request_error if the split array violates any rule. Per entry

entity_id must reference an Entity whose capabilities.settlement_recipient.status is operational.
The Entity object’s country_code must match the payment currency.
For flat, amount must be greater than 0 and less than or equal to the Checkout Session amount.
For percentage: 0 < amount <= 10000.

Global

Between 1 and 10 entries.
No duplicate entity_id values.
Every entry must use the same type.
The sum of all split[].amount values, after converting percentages, must equal the Checkout Session amount exactly.
For percentage, the values must add up to exactly 10000 bps.

Rounding. Fintoc calculates percentage amounts as floor(amount_total * amount / 10000). Fintoc assigns the accumulated rounding difference to the entry with charge_processing_fee: true.

Errors

Code	Meaning
`ENTITY_NOT_FOUND`	The `entity_id` does not exist in your organization.
`ENTITY_NOT_OPERATIONAL`	The Entity has not completed its onboarding.
`DUPLICATE_ENTITY_IN_SPLIT`	The same `entity_id` appears more than once.
`MIXED_SPLIT_TYPES`	The array mixes `flat` and `percentage`.
`SPLIT_SUM_MISMATCH`	The amounts do not add up to `amount` exactly.
`MISSING_CHARGE_PROCESSING_FEE`	No entry sets `charge_processing_fee` to `true`. Exactly one entry must set it.
`MULTIPLE_CHARGE_PROCESSING_FEE`	More than one entry sets `charge_processing_fee` to `true`.

{
  "error": {
    "type": "invalid_request_error",
    "message": "Split rules must add up to the total amount",
    "code": "SPLIT_SUM_MISMATCH",
    "param": "split"
  }
}

​Before you begin

​Step 1: Create an Entity

​Step 2: Onboard the Entity

​Create the onboarding

​Onboarding type

​The settlement account

​Chile

​Mexico

​Onboarding fields

​Submit the onboarding

​Changing the settlement account

​Step 3: Create a Checkout Session with split

​Step 4: Handle post-payment events

​How and when recipients are paid

​Rules and validations

​Errors

Before you begin

Step 1: Create an Entity

Step 2: Onboard the Entity

Create the onboarding

Onboarding type

The settlement account

Chile

Mexico

Onboarding fields

Submit the onboarding

Changing the settlement account

Step 3: Create a Checkout Session with `split`

Step 4: Handle post-payment events

How and when recipients are paid

Rules and validations

Errors