Skip to main content
This feature allows merchants to split payments among multiple recipients, which is particularly useful 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 depends on the support of the selected payment provider. Yuno acts solely as the orchestrator of the payment, not the processor. Ensure your provider supports split payments before using this functionality.

​
Key features

The key features of the split payments marketplace include:
  • Split payments: Define how the total payment amount is distributed among different recipients.
  • Flexible configuration: Supports 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.
  • Onboarding transfer: Allows the transfer of onboardings between different recipients.
To use this feature, you must first onboard your recipients for the payment split, and then create the payment specifying the necessary information.

​
1. Onboarding

Yuno’s onboarding model is crafted to assist marketplaces in seamlessly connecting and managing their submerchants across multiple payment providers. Central to 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 offers two onboarding flows for submerchants, providing flexibility based on the submerchant’s current status with payment providers.
  1. Pre-onboarded accounts: If a submerchant has already completed the onboarding process with a specific provider (e.g., through an external dashboard or platform), the marketplace can supply the corresponding recipient_id during creation. In this scenario, no further onboarding is required, and the status will be immediately set to SUCCEEDED (onboardings.type=PREVIOUSLY_ONBOARDED).
  2. Dynamic onboarding: If no credentials are provided, Yuno will initiate the onboarding process for the chosen provider (onboardings.type=ONE_STEP_ONBOARDING or TWO_STEP_ONBOARDING). This process may include:
    1. Form submission or redirection to a hosted onboarding page.
    2. Uploading legal or financial documentation.
    3. Completing KYC/KYB validation steps.
Throughout the onboarding lifecycle, a recipient may experience various statuses that reflect the current state of the process:
StatusDescription
CREATEDInitial state after creation; onboarding process not yet started.
PENDINGAwaiting provider review after data submission.
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 assist the marketplace in understanding the onboarding lifecycle and implementing appropriate retry, alert, or fallback mechanisms when necessary. This flexible approach allows marketplaces to tailor the onboarding process to their operational needs, maintaining control and visibility.

​
Workflow

The onboarding workflow follows a structured process that ensures submerchants are properly integrated into the marketplace ecosystem. The diagram below illustrates the complete flow from initial setup to payment processing.
Workflow Steps:
  1. Organization & Account Setup: The marketplace owner creates an organization in Yuno and configures accounts with payment provider connections.
  2. Recipient Creation: For each submerchant, the marketplace creates a recipient using the Create Recipients API endpoint, specifying either:
    • provider_recipient_id for pre-onboarded submerchants
    • Provider connection details for new onboarding
  3. Onboarding Execution:
    • Pre-onboarded: Status immediately becomes SUCCEEDED
    • New onboarding: Yuno initiates provider-specific flow with status progression from CREATED → PENDING → SUCCEEDED
  4. Payment Creation: Once recipients are successfully onboarded (SUCCEEDED status), the marketplace can create payments with the split_marketplace object.
  5. Split Processing: The payment provider executes the split according to the defined distribution, transferring funds to each recipient’s designated share.

​
2. Payment split integration

In this section, we explore how the split_marketplace object is used to divide a payment among multiple recipients. This object is an array where each entry specifies a recipient and their corresponding share of the payment.
In this step, reference recipients created in Step 1 (Onboarding).For type = PURCHASE or MARKETPLACE, include the recipient_id of that recipient.For PAYMENTFEE, VAT and COMMISSION, recipient_id is optional.
FieldTypeDescriptionMandatoryExample Value
recipient_idstringThe unique identifier for the recipient within theUse the ID of a recipient created in Step 1 (Onboarding) when type is PURCHASE or MARKETPLACE.Conditionalrec_test123
provider_recipient_idstringThe recipient’s ID as provided by the payment provider, if applicable.Conditionalprov_rec_abc
Note:You must provide either recipient_id or provider_recipient_id.For marketplace owners (type=COMMISSION), provider_recipient_id is optional if not required by the provider.
type*enumThe transaction detail item type. Options include PURCHASE, PAYMENTFEE, VAT, COMMISSION, MARKETPLACE.recipient_id is mandatory for PURCHASE and MARKETPLACE.ConditionalPURCHASE
Note:Propagation considerations
  • Items are sent to the provider only if it supports transmitting details
  • These types do not affect fund disbursement, they are merely informational when the provider allows it

merchant_referencestringAn identifier for the payment transaction. This is optional. If not specified, the main payment’s merchant reference will be used for all split transactions. (MAX 255; MIN 3 characters).NoAAB01-432245
amount*structSpecifies the amount for the split.Yes
    value*numberThe monetary value of the split (e.g., 7500 for 75.00).Yes7500
    currency*enumThe currency in which the payment is made (ISO 4217, 3 characters).YesCOP
liabilitystructInformation about the recipient’s liability for fees and chargebacks, if applicable.No
    processing_feeenumSpecifies who is responsible for the transaction fee: MERCHANT, RECIPIENT, SHARED.NoMERCHANT
    chargebacksbooleanIndicates if the recipient is liable for chargebacks (true if they are responsible).Nofalse

Example using provider recipients directly
{
  "split_marketplace": [
    {
      "provider_recipient_id": "recipient_123",
      "type": "PURCHASE",
      "amount": {
        "value": 750,
        "currency": "EUR"
      }
    },
    {
      "type": "COMMISSION",
      "amount": {
        "value": 30,
        "currency": "EUR"
      }
    }
  ]
}
Example using Yuno recipients
{
  "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"
      }
    }
  ]
}

​
3. Onboarding transfer

The goal of this flow is to allow the transfer of onboardings between recipients in a controlled and reversible way. The process has several stages. First, the initial recipient is created with its onboarding (a prior step). Later, when a transfer is required, follow the steps to create the new recipient, use the transfer service, and, if needed, reverse the operation.
  1. Recipient and onboarding (before any transfer): Create recipient, then create onboarding.
This step happens in advance when a new recipient is created and its onboarding is assigned. It is not part of the transfer itself.
If you decide to transfer the onboarding to another recipient, continue the flow:
  1. Create the new recipient and onboarding: Use the create recipient and create onboarding endpoints to set up the recipient and onboarding that will receive the transfer.
  2. Transfer the onboarding: Use transfer onboarding and include:
    • recipient_id: the target recipient ID
    • onboarding_id: the onboarding to transfer
    The onboarding will be transferred to the new recipient.
  3. Reverse the transfer (optional): Use reverse onboarding to revert the previous transfer, providing the same recipient_id and onboarding_id.
The onboarding object includes a history element that stores the complete traceability of the onboarding. This history includes not only updates to the object but also events related to transfers between recipients, ensuring full lifecycle visibility.

​
4. Standalone Transfers

Merchants often need to send funds to recipients (sellers, vendors, contractors) independently of a payment lifecycle, directly from their organization balance. This is known as a Standalone Transfer or Forward Transfer. This feature allows you to:
  • Distribute sales proceeds to sellers in a Marketplace.
  • Pay contractors after completed jobs (Gig Economy).
  • Manage revenue sharing for subscriptions or commission payments for affiliates.
  • Execute bulk payouts to multiple recipients.

​
Transfer Statuses

A standalone transfer flow goes through multiple states depending on the provider’s response and any subsequent reversals:
StatusDescriptionTerminal?
CREATEDTransfer flow created, not yet sent to provider.No
PENDINGSent to provider, awaiting confirmation.No
SUCCEEDEDForward transfer completed successfully.No
DECLINEDProvider declined the transfer.Yes
ERRORProvider error during processing.Yes
REVERSEDReverse transaction completed successfully.Yes

​
Transactions and Reversals

In the Standalone Transfer Flow, forward and reverse operations are treated as identical independent transactions to maintain an explicit audit trail. This means:
  1. Forward Transfer (SPLIT_TRANSFER): You create a transfer moving funds from your balance to the recipient’s connection.
  2. Reverse Transfer (SPLIT_TRANSFER_REVERSE): You can fully or partially reverse the SPLIT_TRANSFER to return the funds to your balance. The original forward transfer must be in SUCCEEDED status for a reverse to take place.

​
Idempotency

Both the creation and reversal of standalone transfers require an Idempotency Key via the X-Idempotency-Key header. This allows you to safely retry requests without accidentally duplicating fund distribution. These keys are retained for 24 hours. Duplicate requests using the same combination of account_id and idempotency key will return the original transfer object.

​
Validations

In this section, we outline the necessary validations to ensure successful split payments.
  • The total of all splits must match the overall payment amount.
  • For each split, an object must be sent for every participant, ensuring the sum of amounts equals the total payment amount.
  • In scenarios where a direct recipient ID is not needed for the marketplace owner (e.g., with Adyen), the type field can serve as a flag (e.g., COMMISSION) to denote the marketplace owner’s share, making the provider_recipient_id optional for that specific split.
  • Either recipient_id or provider_recipient_id must be included for the split, but not both.
  • If any required fields are missing or invalid, the request will result in an error.
  • If using multiple payment providers for split payments, we recommend utilizing the recipients object, as it allows defining more than one provider for each recipient.

​
API endpoints involved

This section lists the API endpoints involved in managing split payments.