Split Payments Marketplace

​

Key features

• Split payments: Define how the total payment amount is distributed among different recipients.
• Flexible configuration: Supports both absolute-based and auto-calculation splits.
• Auto Split Configuration: Define rules at the recipient level (percentage, fixed, or mixed) to automate split calculations without specifying amounts in each payment request.
• 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.

​

1. Onboarding

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

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

​

Onboarding flows

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.

​

Workflow

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. Auto Split Configuration

​

Calculation types

​

Rounding mode

​

Implementation

{
  "merchant_recipient_id": "seller-123",
  "split_configuration": {
    "calculation_type": "PERCENTAGE",
    "percentage": 10.5,
    "rounding_mode": "STANDARD",
    "currency": "USD"
  }
}

​

3. Payment split integration

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

{
  "split_marketplace": [
    {
      "recipient_id": "4b31a9b8-4cd2-4e47-93cf-03729241bd68",
      "type": "PURCHASE"
      // The amount is omitted, Yuno uses the recipient's split_configuration
    },
    {
      "recipient_id": "9104911d-5df9-429e-8488-ad41abea1a4b",
      "type": "COMMISSION",
      "amount": {
        "value": 50,
        "currency": "USD"
      }
    }
  ]
}

​

3. Onboarding transfer

1. Recipient and onboarding (before any transfer): Create recipient, then create onboarding.

2. 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.
3. 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.
4. Reverse the transfer (optional): Use reverse onboarding to revert the previous transfer, providing the same recipient_id and onboarding_id.

​

4. Standalone Transfers

• 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

​

Transactions and Reversals

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

​

Validations

• Total Split Matching: The sum of all splits must match the overall payment amount.
• Recipient Existence: Every recipient_id included in the split must correspond to a successfully onboarded recipient.
• Auto Split Currency: If a recipient has a split_configuration, its currency must exactly match the payment’s amount.currency.
• Amount Consistency: If you provide an amount.value for a recipient with split_configuration, it must match the result of the automatic calculation.
• Individual Split Limits: Each individual split’s resolved value must be greater than zero and less than or equal to the total payment amount.
• Minimum Precision: For PERCENTAGE splits, the calculated value must be at least 0.0001 (platform minimum).
• Required Fields:
  • For manual splits (no split_configuration): amount.value and amount.currency are mandatory.
  • If split_configuration is provided during recipient creation: calculation_type and currency are always mandatory.
• Exclusion Rule: You must include either recipient_id or provider_recipient_id for each split item, but never both.
• Multiple Providers: For recipients linked to multiple payment providers, use the recipients object to manage the split logic across connections.

​

API endpoints involved

• Create recipients: POST: https://api-sandbox.y.uno/v1/recipients
• Create onboarding: POST: https://api-sandbox.y.uno/v1/recipients/{recipient_id}/onboardings
• Continue onboarding: POST: https://api-sandbox.y.uno/v1/recipients/{recipient_id}/onboardings/{onboarding_id}/continue
• Create payment: POST: https://api-sandbox.y.uno/v1/payments
• Capture authorization: POST: https://api-sandbox.y.uno/v1/payments/{id}/transactions/{transaction_id}/capture
• Refund payment: POST: https://api-sandbox.y.uno/v1/payments/{id}/transactions/{transaction_id}/refund
• Cancel or refund a payment: POST: https://api-sandbox.y.uno/v1/payments/{id}/cancel-or-refund
• Cancel or refund a payment with transaction: POST: https://api-sandbox.y.uno/v1/payments/{id}/transactions/{transaction_id}/cancel-or-refund
• Transfer onboarding: POST: https://api-sandbox.y.uno/v1/recipients/{recipient_id}/onboardings/{onboarding_id}/transfer
• Reverse onboarding transfer: POST: https://api-sandbox.y.uno/v1/recipients/{recipient_id}/onboardings/{onboarding_id}/reverse-transfer
• Create standalone transfer: POST: https://api-sandbox.y.uno/v1/split-marketplace/transfers
• Get standalone transfer: GET: https://api-sandbox.y.uno/v1/split-marketplace/transfers/{transfer_id}
• Reverse standalone transfer: POST: https://api-sandbox.y.uno/v1/split-marketplace/transfers/{transfer_id}/reverse