Split Payments Marketplace

Overview

This feature allows merchants to split payments between multiple recipients. This is especially useful for marketplace models, where a transaction needs to be divided among different sellers or stakeholders. By utilizing this functionality, merchants can define how the payment is split, including the amounts, recipients, and any applicable fees.

The split payment functionality depends on whether the selected payment provider supports it. Yuno acts solely as the orchestrator of the payment, not the processor. Make sure your provider supports split payments before attempting to use this functionality. At the moment, this feature is only available for the following providers:

  • Pagarme

Key Features

  • Split Payments: Define how the total payment amount is distributed among different recipients.
  • Flexible Configuration: Support for both absolute and percentage-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.

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.

FieldTypeDescription
recipient_idstringThe ID of the recipient in the Yuno system. [Conditional - Either the recipient_id or the provider_recipient_id should be sent in the payment creation]
provider_recipient_idstringThe recipient ID from the payment provider, if applicable. [Conditional - Either the recipient_id or the provider_recipient_id should be sent in the payment creation]
typeenumThe type of split (PURCHASE, PAYMENTFEE, VAT, COMMISSION, MARKETPLACE, SHIPPING). [Mandatory]
merchant_referencestringOptional unique identifier for the split transaction.
amountstructDefines the amount or percentage of the split. [Mandatory]
- valuenumberAmount of the split
- currencyenumThe currency used to make the payment (ISO 4217 MAX 3; MIN 3)
liabilitystructOptional information regarding the recipient’s liability for fees and chargebacks.
- processing_feeenumIndicates who will be charged the transaction fee. MERCHANT, RECIPIENT, SHARED
- chargebacksbooleanThe recipient is responsible in case of a chargeback
{
  "split_marketplace": [
    {
      "provider_recipient_id": "recipient_123",
      "type": "PURCHASE",
      "amount": {
        "value": 750,
        "currency": "EUR"
      },
      "liability": {
        "processing_fee": "MERCHANT",
        "chargebacks": false
      }
    },
    {
      "provider_recipient_id": "recipient_456",
      "type": "COMMISSION",
      "amount": {
        "value": 30,
        "currency": "EUR"
      },
      "liability": {
        "processing_fee": "RECIPIENT",
        "chargebacks": true
      }
    }
  ]
}

Rules

  • The sum of all splits must equal the total payment amount.
  • Either recipíent_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.

API Endpoints Involved

  • 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