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:

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.
Activate the Feature
- Contact support@upayments.com to enable Multi-Merchant access on your account.

🚀 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:
📩 support@upayments.com