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:

StatusDescription
CREATEDInitial state after creation; onboarding process not yet started.
PENDINGAwaiting provider review after data was submitted.
SUCCEEDEDThe recipient is fully onboarded and active.
DECLINEDThe onboarding was rejected by the provider and cannot be retried.
BLOCKEDThe provider has explicitly blocked the onboarding due to compliance issues.
CANCELEDThe onboarding process was voluntarily canceled before completion.
REJECTEDThe onboarding failed due to incorrect data or failed validations.
ERRORA technical error occurred during the onboarding flow.

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.

FieldTypeDescriptionMandatoryExample Value
recipient_idstringThe ID of the recipient in the Yuno system.Conditionalrec_test123
provider_recipient_idstringThe recipient ID from the payment provider, if applicable.Conditionalprov_rec_abc
Note:Either recipient_id or provider_recipient_id must be provided. For marketplace owners (type='COMMISSION'), provider_recipient_id can be optional if not applicable for the specific provider.
type*enumSplit type. Could be PURCHASE, PAYMENTFEE, VAT, COMMISSION, MARKETPLACE, SHIPPING.YesPURCHASE
merchant_referencestringIdentification of the payment transaction. Optional. If not defined, the same value as the main payment's merchant reference will be used for all split transactions. (MAX 255; MIN 3 characters).NoAAB01-432245
amount*structDefines the amount of the split.Yes
    value*numberAmount of the split (e.g., 7500 for 75.00).Yes7500
    currency*enumThe currency used to make the payment (ISO 4217, 3 characters).YesCOP
liabilitystructOptional information regarding the recipient’s liability for fees and chargebacks.No
    processing_feeenumIndicates who will be charged the transaction fee: MERCHANT, RECIPIENT, SHARED.NoMERCHANT
    chargebacksbooleanIf true, the recipient is responsible in case of a chargeback.Nofalse

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