Split Payments Marketplace

This feature enables merchants to split payments among multiple recipients, which is particularly beneficial for marketplace models where transactions need to be divided among different sellers or stakeholders. Merchants can specify how the payment is split, including the amounts, recipients, and any applicable fees.

The split payment functionality is contingent on the support of the selected payment provider. Yuno serves solely as the orchestrator of the payment, not the processor. Ensure your provider supports split payments before using this functionality.

Key features

• Split payments: Define how the total payment amount is distributed among different recipients.
• Flexible configuration: Support for absolute-based splits.
• Integration with providers: Splits can be executed by payment providers that support this functionality.
• Detailed handling of fees: The system allows for fine-tuning of how transaction fees and chargebacks are managed.

First you'll need to onboard your recipients for the payment split, and then create the payment specifying the necessary information.

1- Onboardings

Yuno’s onboarding model is designed to help marketplaces seamlessly connect and manage their submerchants across multiple payment providers. At the core of this system is the Recipient object, which represents each individual submerchant within the marketplace ecosystem.

• Each Marketplace Owner is represented in Yuno as an Organization.
• Within an organization, one or more Accounts can be created, each configured with its own set of Connections to payment providers (e.g., Stripe, Adyen, dLocal).
• For every account, the marketplace can register one or more Recipients — these are the submerchants to be onboarded.
• Each Recipient is then linked individually to one or more Connections, depending on which payment processors they will use.

This architecture enables:

• A single, unified onboarding process.
• Independent status tracking per provider.
• Easy scaling of submerchant operations across providers.

This design ensures flexibility, transparency, and full traceability throughout the onboarding lifecycle. The /recipients endpoint is used to create and manage each submerchant profile, and to trigger the corresponding provider-specific onboarding workflows.

Onboarding flows

Yuno supports two onboarding flows for submerchants:

1. Pre-onboarded Accounts: If the submerchant has already completed the onboarding process with a given provider (e.g., via an external dashboard or platform), the marketplace can provide the corresponding recipient_id at the time of creation. In this case, no further onboarding is needed, and the status will immediately be set to SUCCEEDED. (onboardings.type='PREVIOUSLY_ONBOARDED')
2. Dynamic Onboarding: If no credentials are provided, Yuno will initiate the onboarding process for the selected provider. (onboardings.type='ONBOARD_ONTO_PROVIDER'). Depending on the provider’s requirements, this may involve:
   1. Form submission or redirection to hosted onboarding.
   2. Upload of legal or financial documentation.
   3. KYC/KYB validation steps.

During the onboarding lifecycle, a Recipient may go through several statuses which indicate the current state of the process:

These statuses help the marketplace understand the onboarding lifecycle and implement appropriate retry, alert, or fallback mechanisms when required.

This flexibility allows marketplaces to adapt the onboarding process to their operational needs, without sacrificing control or visibility.

2- Payment Split Integration

The split_marketplace object defines how a payment should be split between recipients. It is an array of objects, where each object represents a recipient and their share of the payment.

{
  "split_marketplace": [
    {
      "provider_recipient_id": "recipient_123",
      "type": "PURCHASE",
      "amount": {
        "value": 750,
        "currency": "EUR"
      }
    },
    {
      "type": "COMMISSION",
      "amount": {
        "value": 30,
        "currency": "EUR"
      }
    }
  ]
}

{
  "split_marketplace": [
    {
      "recipient_id": "4b31a9b8-4cd2-4e47-93cf-03729241bd68",
      "type": "PURCHASE",
      "amount": {
        "value": 750,
        "currency": "EUR"
      }
    },
    {
      "recipient_id": "9104911d-5df9-429e-8488-ad41abea1a4b",
      "type": "COMMISSION",
      "amount": {
        "value": 30,
        "currency": "EUR"
      }
    }
  ]
}

Validations

• The sum of all splits must equal the total payment amount.
• For each split, you must send an object for every participant, and the sum of amounts must equal the total payment amount.
• For scenarios where a direct recipient ID is not required for the marketplace owner (e.g., with Adyen), the type field can be used as a flag (e.g., COMMISSION) to indicate the marketplace owner's share, and the provider_recipient_id will be optional for that specific split.
• Either recipient_id or provider_recipient_id must be provided for the split, but not both.
• If any required fields are missing or invalid, the request will return an error.
• In case you use more than one payment provider for the split payments, we recommend using the recipients object, as it lets you define more than one provider for each recipient.

API endpoints involved

• Recipients: POST /v1/recipients
• Payment Creation: POST /v1/payments
• Full and Partial Capture: POST /v1/payments/:id/transactions/:transaction_id/capture
• Full or Partial Refund:
  • POST /v1/payments/:id/transactions/:transaction_id/refund
  • POST /v1/payments/:id/cancel-or-refund
  • POST /v1/payments/:id/transactions/:transaction_id/cancel-or-refund