Guides
Log In

Multi-Vendors

Multiple Suppliers

Suggest Edits

Introduction

Base on the integration types that MyFatoorah supports now, we have added a great feature that allows you to add Multi-Vendors (multiple suppliers) under your account. So that you will be able to add them, specify the rate of each supplier, and start collecting 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 below steps to fulfill the multi-vendors integration in your system:

  1. Call CreateSupplier endpoint to create a new supplier record and provide the required parameters: SupplierName, Mobile, and Email.

  2. After adding the supplier, you need to manage all related data. Call UploadSupplierDocument endpoint to upload the document files related to this supplier. You had to upload at least six files.

  3. Then you need to call your account manager to activate that supplier into your portal account. To check the activation status, you should request the GetSupplierDashboard endpoint. It also will provide you with information about your supplier's activities.

  4. Now, you can create a supplier invoice or a new payment invoice using one of the following endpoints:

* The [SendPayment](doc:send-payment)  endpoint to create a **MyFatoorah** supplier invoice. Check the below [send payment example](#sendpayment-with-suppliers-sample-message). 
* The [ExecutePayment](doc:execute-payment) endpoint to create an invoice of a selected gateway. Check the below [execute payment example](#executepayment-with-suppliers-sample-message).
  1. 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 detail.
  • 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 SendPayment or ExecutePayment 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, 
      "InvoiceShare": 0, 
      "ProposedShare": 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 share of the invoice, and the sum of the suppliers' InvoiceShare must be equal to the InvoiceValue 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 invoice value should be 100.

ProposedShare 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 ProposedShare 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 value 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 ProposedShare parameter is a value, make sure that the value of the ProposedShare parameter will be less than or equal to the InvoiceShare parameter and less than or equal to the InvoiceValue parameter.
  • If ProposedShare equals to InvoiceShare parameter, the vendor will get a "zero" commission from the suppliers, and the supplier will gain the total amount of the InvoiceShare parameter.
  • If ProposedShare 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 ProposedShare parameter minus the cost of the payment service charge.

SendPayment with Suppliers Sample Message

{
  "CustomerName": "Type Customer Name",
  "NotificationOption": "all",
  "MobileCountryCode": "965",
  "CustomerMobile": "123456",
  "CustomerEmail": "[email protected]",
  "InvoiceValue": 2468,
  "DisplayCurrencyIso": "kwd",
  "CallBackUrl": "https://yoursite.com/success",
  "ErrorUrl": "https://yoursite.com/error",
  "Language": "en",
  "Suppliers": 
  [
      {
      "SupplierCode": 1,
      "ProposedShare": null,
      "InvoiceShare": 600
      },
      {
      "SupplierCode": 2,
      "ProposedShare": 600,
      "InvoiceShare": 600
      },
      {
      "SupplierCode": 3,
      "ProposedShare": 600,
      "InvoiceShare": 600
      },
      {
      "SupplierCode": 4,
      "ProposedShare": 668,
      "InvoiceShare": 668
      }
    ],
  "InvoiceItems": [
    {
      "ItemName": "name",
      "Quantity": 20,
      "UnitPrice": 123.4,
      "Description": "string",
      "Weight": 1.2564,
      "Width": 22.2222,
      "Height": 22.2222,
      "Depth": 22.2222
    }
  ],
  "SourceInfo": "string"
}

{
    "IsSuccess": true,
    "Message": "Invoice Created Successfully!",
    "ValidationErrors": null,
    "Data": {
        "InvoiceId": 300051,
        "InvoiceURL": "https://demo.myfatoorah.com/ie/0106230005134",
        "CustomerReference": "SupplierCode 69 - value 50",
        "UserDefinedField": null
    }
}

ExecutePayment with Suppliers Sample Message

{
  "PaymentMethodId": 1,
  "CustomerName": "test",
  "DisplayCurrencyIso": "kwd",
  "MobileCountryCode": "965",
  "CustomerMobile": "12345678",
  "CustomerEmail": "[email protected]",
  "InvoiceValue": 100,
  "CallBackUrl": "https://yoursite.com/success",
  "ErrorUrl": "https://yoursite.com/error",
  "Language": "en",
  "CustomerReference": "string",
  "CustomerCivilId": "string",
  "UserDefinedField": "string",
  "CustomerAddress": {
    "Block": "string",
    "Street": "string",
    "HouseBuildingNo": "string",
    "Address": "Address",
    "AddressInstructions": "Address"
  },
  "Suppliers": 
  [
      {
      "SupplierCode": 1,
      "ProposedShare": null,
      "InvoiceShare": 100
      }
    ],
  "InvoiceItems": [
    {
      "ItemName": "name",
      "Quantity": "1",
      "UnitPrice": 100,
      "Description": "string",
      "Weight": 0.5,
      "Width": 10,
      "Height": 15,
      "Depth": 17
    }
  ],
  "SourceInfo": "string"
}

{
    "IsSuccess": true,
    "Message": "Invoice Created Successfully!",
    "ValidationErrors": null,
    "Data": {
        "InvoiceId": 568119,
        "IsDirectPayment": false,
        "PaymentURL": "https://demo.MyFatoorah.com/En/KWT/PayInvoice/Checkout?invoiceKey=030675256811947&paymentGatewayId=20",
        "CustomerReference": "string",
        "UserDefinedField": "string"
    }
}

Updated about 1 month ago