Multi-Vendors

Introduction

Base on the integration types that MyFatoorah supports now, we have added a great feature that allows you to add **submerchants **(known as **suppliers **in MyFatoorah system) under your account. So that you will be able to add them, specify the rate of each supplier, and start collecting payments for them.

❗️
Approval is Needed
Kindly contact your account manager or sales representative to activate the Multi-Vendors feature.

How it works

📘
Portal Account
The below steps describe how to integrate the Multi-Vendors API feature into your application. Also, you can use your portal account to configure multiple suppliers (Multi-Vendors) as described in the Supplier Information section.

Kindly follow the steps below to fulfill the multi-vendors integration in your system:

Call CreateSupplier endpoint to create a new supplier record and provide the required parameters: SupplierName, Mobile, and Email.
After adding the supplier, you need to manage all related data. Call UploadSupplierDocument endpoint to upload the document files related to this supplier. The required documents to approve a supplier can be reviewed with the account manager.
Once the documents are uploaded, the KYC team reviews them and makes a decision. You will get a webhook with approval or rejection and the rejection reason.
Now, you can create a supplier payment using either POST Sessions or POST Payments.
You can track the balance of each supplier by calling GetSupplierDashboard endpoint.
Finally, call GetSupplierDeposits endpoint to check for the earned deposit from that supplier.

Furthermore, MyFatoorah developed additional API endpoints that help in fully integrating the Multi-Vendors feature into your platform, as described next:

Call EditSupplier endpoint if you need to update the supplier details.
Call GetSuppliers endpoint to show a list of your suppliers.
Call GetSupplierDocuments endpoint to list the uploaded documents.
Call TransferBalance endpoint to transfer a balance to or from the awaiting balance of a supplier.

Create Supplier Invoice

You can use Create Session or Create Payment endpoints to create an invoice request with no suppliers, one supplier, or many suppliers. When enabling the multi-vendors feature, you can provide suppliers' information in the request body. To do so, use the Suppliers parameter as shown in the following sample object.

  "Suppliers": [
    {
      "SupplierCode": 0,
      "ProposedDepositShare": 0, //Optional
      "InvoiceShare": 0
    }
  ]

SupplierCode Parameter:

The code is on the supplier list page after creating a supplier at your MyFatoorah account.
Also, you can use the CreateSupplier endpoint to create the suppliers, and you will get the code from the response body.
If you have already created the suppliers and need to get their codes through the API, you can use the GetSuppliers endpoint. It will retrieve all the suppliers you have in your account with all of their information.

InvoiceShare Parameter:

It is the supplier's share of the invoice, and the sum of the suppliers' InvoiceShare must be equal to the Order.Amount parameter.
For example, an invoice contains two suppliers. The first supplier products cost 30, and the second supplier products cost 70. Therefore the first supplier InvoiceShare should be set to 30, the second supplier InvoiceShare should be 70, and the Order Amount should be 100.

ProposedDepositShare Parameter:

This parameter allows setting a specific amount that the supplier will get after paying the invoice.
This parameter can be null or a value.
If the ProposedDepositShare parameter is null, the system will calculate the vendor commission based on the fixed commission value and the commission percentage that the vendor added for this supplier. For example: If the InvoiceShare equals 100, the vendor will get ((InvoiceShare X Commission Percentage) + Commission Value).
If the ProposedDepositShare is used instead of null, the supplier will get this amount, and the system will neglect the vendor fixed and percentage commission calculation.
If the ProposedDepositShare parameter is a value, make sure that the value of the ProposedDepositShare parameter will be less than or equal to the InvoiceShare parameter.
If ProposedDepositShare equals InvoiceShare parameter, the vendor will get a "zero" commission from the suppliers, and the supplier will gain the total amount of the InvoiceShare parameter after deducting the transaction fees.
If ProposedDepositShare equals to InvoiceShare parameter, and the payment service charge is on the vendor, the last supplier - at the end of the supplier list - will get the amount of the ProposedDepositShare parameter minus the cost of the payment service charge.

POST Payments with Suppliers Sample Message

{
    "PaymentMethod": "CARD",
    "Order": {
        "Amount": 20
    },
    "Suppliers": [
        {
            "SupplierCode": 1,
            "ProposedDepositShare": 10,
            "InvoiceShare": 20
        }
    ]
}

{
    "IsSuccess": true,
    "Message": "",
    "ValidationErrors": null,
    "Data": {
        "InvoiceId": "6389754",
        "PaymentId": null,
        "PaymentURL": "https://demo.MyFatoorah.com/KWT/ie/050712180638975463-d0cb4489",
        "PaymentCompleted": false,
        "TransactionDetails": null
    }
}

POST Sessions with Suppliers Sample Message

{
    "PaymentMode": "COMPLETE_PAYMENT", 
    "Order": {
        "Amount": 20
    },
        "Suppliers": [
        {
            "SupplierCode": 1,
            "ProposedDepositShare": 10,
            "InvoiceShare": 20
        }
    ]
}

{
    "IsSuccess": true,
    "Message": "Created Successfully!",
    "ValidationErrors": null,
    "Data": {
        "SessionId": "KWT-9f85547d-1a9e-4247-8511-e5818681e165",
        "SessionExpiry": "2025-12-24T19:38:07.1220714Z",
        "EncryptionKey": "Lr+AUZVza1OwbLNZ9z//6A4jsBnCEBtJqxhBdskr+KE=",
        "OperationType": "PAY",
        "Order": {
            "Amount": 20.0,
            "Currency": "KWD",
            "ExternalIdentifier": null
        },
        "Customer": {
            "Reference": null,
            "Cards": null
        }
    }
}