API Reference

Multi-merchant

Merchants who manage multiple sub-merchants can streamline payments using UPay’s charge API and passing Multi-merchant parameter. This feature allows a single payment request to handle payments across multiple sub-merchants.

Multi-Merchant API

Manage payments for multiple sub-merchants with a single API call using UPay’s Multi-Merchant feature—purpose-built for marketplaces, aggregators, and platform-based businesses.

This functionality allows you to process a single transaction and allocate funds to multiple sub-merchants, define individual fees, and handle reconciliation efficiently—all in one go.

⚙️ What is the Multi-Merchant API?

UPay’s Multi-Merchant capability enables platforms to:

  • Process one charge request for multiple sub-merchants
  • Split funds across vendors within a single transaction
  • Assign dynamic fees per sub-merchant based on payment method
  • Simplify settlement and reconciliation

Whether you're managing a marketplace, food delivery app, or service platform, this API helps you route funds accurately and automatically—without manually managing individual transactions.

🎯 Key Benefits

  • One API call to handle many merchants
  • Custom payouts and fees per sub-merchant
  • Supports KNET, Visa, Mastercard, Apple Pay, Samsung Pay, Google Pay
  • Faster settlement and reconciliation
  • Fully compliant with Kuwait’s payment regulations

🛠️ How It Works

To enable multi-merchant functionality, include the "ExtraMerchantsData" array in your Add Charge request. This array defines sub-merchant information, allocation amounts, and fee structures.

Example use cases:

  • Allocate KD 50 to Vendor A and KD 25 to Vendor B
  • Charge a 2% processing fee from Vendor C for Visa transactions
  • Route all Apple Pay payments to Vendor D, minus a flat KD 1 fee

✅ Prerequisites

Before using the Multi-Merchant API:

  1. Verify Your UPay Account

    • Make sure your business profile in the "My Account" section is complete and verified.
    • Verification is required to facilitate secure fund settlements.

  2. Activate the Feature

🚀 Steps to Implement

1. Include the "ExtraMerchantsData" Array

Pass sub-merchant details in your charge request as follows:

"ExtraMerchantsData": [
  {
    "merchantCode": "VENDOR_001",
    "amount": 50,
    "fees": {
      "visa": { "type": "percentage", "value": 2.5 },
      "knet": { "type": "fixed", "value": 1.000 }
    }
  },
  {
    "merchantCode": "VENDOR_002",
    "amount": 25,
    "fees": {
      "applepay": { "type": "fixed", "value": 0.500 }
    }
  }
]

2. Submit the Charge Request

Send the full charge request to the UInterfaceV2 endpoint as you normally would—your "ExtraMerchantsData"will determine how funds are routed and fees are applied.

3. Receive Settlement Per Sub-Merchant

Once processed, each sub-merchant receives their allocated share. Fees are automatically deducted and deposited accordingly.

📞 Need Help?
If you have questions about onboarding, formatting requests, or managing multi-merchant settlements, our support team is here to assist you:
📩 [email protected]