Skip to main content

Step 2: Initiating a Split Payout Request

The Split Payout feature empowers merchants to allocate funds from a single transaction to multiple beneficiaries. This is ideal for businesses operating in marketplaces, commission-based services, or platforms managing multiple parties. In this guide, we will walk you through the key steps to successfully initiate split payouts using PayTabs APIs.

info

For a better understanding of the requirements and the whole split payout cycle, we highly recommend you to check our Workflow, Prerequisites & Configurations manuals

POST{{domain}}/payment/request
Be Aware Of

Please note that not using the proper endpoint URL {domain} will lead to authentication issues within your responses. To find the your proper domain you can read ourWhat is my (Region)/(endpoint URL)?tutorial article.

https://secure.paytabs.sa/payment/request

Request Parameters​

To initiate a payment request using this integration type, there are minimum required parameters that need to be passed with valid information. The specification of these required parameters is clarified below:

Parameter
profile_id
DescriptionThe merchant Profile ID you can get from your PayTabs dashboard. For more information please check our How to get your account information from PT2 Dashboard? solution article. To know more about this parameter please click here.
Data TypeINT
Required✔
Validation RulesAccept only valid profile number.
Sample
{
    "profile_id": 987654
}
Parameter
tran_type
DescriptionThe identification of the type of the transaction. To know more about these types please check our What is the "tran_type" (transaction type)? solution article.
To know more about this parameter please click here.
Data TypeSTRING
Required✔
Validation Rules

Valid string from this enum list:

sale auth void release capture refund register
Sample
{
    "tran_type": "sale"
}
Parameter
tran_class
DescriptionThe identification of the category/class this transaction will follow, such as eCommerce, Recurring, etc. To know more about these types please check our What is the "tran_class" (transaction class)? solution article.
To know more about this parameter please click here.
Data TypeSTRING
Required✔
Validation Rules

Valid string from this list

ecom recurring moto
Sample
{
     "tran_class": "ecom"
}
Parameter
cart_id
DescriptionIndicates the cart/order id at the merchant end, to easily relate the PayTabs transaction to.
To know more about this parameter please click here.
Data TypeSTRING
Required✔
Min1
Max64
Sample
{
     "cart_id": "CART#10001"
}
Parameter
cart_description
DescriptionIndicates the cart/order description at the merchant end, to easily relate the PayTabs transaction to.
To know more about this parameter please click here.
Data TypeSTRING
Required✔
Min1
Max128
Sample
{
     "cart_id": "CART#10001"
}
Parameter
cart_currency
DescriptionIndicates the transaction currency, which the customer will be charged with.
To know more about this parameter please click here.
Data TypeSTRING
Required✔
Min1
Max128
Validation RulesValid string from the following list: SAR AED BHD EGP EUR GBP HKD IDR INR IQD JOD JPY KWD MAD OMR PKR QAR USD
Accepts both upper/lower case characters
Sample
{
     "cart_currency": "SAR"
}
Parameter
cart_amount
DescriptionIndicates the amount of the transaction the customer is about to be charged. Both min and max values are subjected to the merchant transaction limits.
To know more about this parameter please click here.
Data TypeDECIMAL
Required✔
Min0.01
Max9999999999.99
Sample
{
     "cart_amount": 500.99
}
split_payout
OBJECT-
The Split Object which contains, the stakeholders of current transaction. If it is defined at least two entities should be provided.
{
    "split_payout": 
    [
        .
        .
        .
    ]
}
split_payout.entity_id
INT
-
✔
Unique Entity Id, defined by the merchant
{
    "split_payout": 
    [
        {
            "entity_id": 1001,
        }
    ]
}
split_payout.entity_name
STRING
-
✔
Entity name
{
    "split_payout": 
    [
        {
            "entity_name": "Agency",
        }
    ]
}
split_payout.item_description
STRING
-
✔
A brief description for the item.
{
    "split_payout": 
    [
        {
            "item_description": "Delivery Fee",
        }
    ]
}
split_payout.item_total
STRING
-
✔
The amount that should be paid for related entity.
{
    "split_payout": 
    [
        {
            "item_total": "10.00",
        }
    ]
}
split_payout.msc_flag
STRINGone of the following values:
F = Full MSC is applied to this item
P = Proportional MSC is applied to this item
Z = Zero MSC
R = Remainder of MSC
✔
  • If one item has ‘F’ as the flag, then all other items must have ‘Z’.
  • The item set to ‘F’ will take the entire MSC for the total transaction amount.
  • If an item has ‘P’ as the flag, then the MSC charged to that item will be a proportion of the total MSC based on what proportion of the total transaction this item represents.
  • If using ‘P’ as one of the flags, then one item must have ‘R’ as its flag, for that item to take the remainder of any MSC that has not been allocated elsewhere.
{
    "split_payout": 
    [
        {
            "msc_flag": "Z",
        }
    ]
}
split_payout.beneficiary
OBJECT✔
Beneficiary details.
{
    "split_payout": 
    [
        {
            "beneficiary": {
                .
                .
            }
        }
    ]
}
split_payout.beneficiary.name
DECIMAL
-
✔
Beneficiary Name as defined in the bank.
{
    "beneficiary": {
        "name" : "Tywin Lannister"
    }
}
split_payout.beneficiary.account_number
INT
-
✔
Beneficiary account (IBAN, VIBAN) .
{
    "beneficiary": {
        "account_number" : "SAXX0X0000XXX000XXXXX000"
    }
}
split_payout.beneficiary.country
STRINGOnly valid country code is accepted.✔
Beneficiary Bank’s country.
{
    "beneficiary": {
        "country" : "SA"
    }    
}
split_payout.beneficiary.bank
STRING
-
✔
The name of Beneficiary bank.
{
    "beneficiary": {
        "bank" : "Iron Bank of Braavos"
    }
}
split_payout.beneficiary.bank_branch
STRING
-
✔
The bank branch.
{
    "beneficiary": {
        "bank_branch" : "Riyadh"
    }
}
split_payout.beneficiary.mobile_number
STRING
-
✔
Beneficiary Phone number.
{
    "beneficiary": {
        "mobile_number" : "+96612345678"
    }
}
split_payout.beneficiary.email
STRING
-
✔
Beneficiary email.
{
    "beneficiary": {
        "email" : "[email protected]"
    }
}
split_payout.beneficiary.address_1
STRING
-
✔
Beneficiary address.
{
    "beneficiary": {
        "address_1" : "Oroba Road, AlRahmania, 12334"
    }   
}
split_payout.beneficiary.address_2
DECIMAL
-
✔
Beneficiary additional address.
{
        "beneficiary": {
    "address_2" : "Building 6, Office 2"
}
}

Request & Response Payload Samples​

This section is dedicated give you a sample API request payload using both the above mentioned required and optional parameters, along with showing you the response payload received upon using each request payload.

The below sample request payload will show you how you can pass the above-mentioned required parameter/s, which are needed to be passed with valid values to perform a request. Along with the response payload received after using this request payload.

{
  "profile_id": **Your profile ID**,
  "tran_type": "sale",
  "tran_class": "ecom",
  "cart_id": "cart_11123",
  "cart_currency": "SAR",
  "cart_amount": 158.56,
  "cart_description": "Description of the items/services",
  "split_payout":
  [
      {
          "entity_id": 1000,
          "entity_name": "Restaurant",
          "item_description": "Meal",
          "item_total": "133.56",
          "msc_flag": "p",
          "beneficiary":
          {
              "name": "Customer Name",
              "account_number": "SAXX0X0000XXX000XXXXX000",
              "country": "SA",
              "bank": "bank name",
              "bank_branch": "",
              "email": "[email protected]",
              "mobile_number": "+966XXXXXXXXX",
              "address_1": "Riyadh",
              "address_2": ""
          }
      },
  ],
  "callback": "none",
  "return": "none"
}

The Payment Flow Experience​

Reaching this point, you are now able to initiate a Split Payout request and as you now, the process involves several key steps that ensure a smooth payment and tracking experience for both you and customers. Here’s how it works:

  1. Initiating the Request:

    Once you initiate a split payout request, you will receive a response that includes a redirect URL. This URL is crucial for guiding your customer through the payment process.


    "redirect_url": "https://secure.paytabs.com/payment/page/599452E5B6B********************B4817688",

  1. Redirecting the Customer:

    You should redirect your customer to this URL as you normally would in a payment transaction. This step allows the customer to complete their payment securely and efficiently. PayTabs then will handle the transaction and ensure that the funds are collected as specified in your split payout request.


  1. Tracking in the Merchant Dashboard:

    After the payment is completed, the transaction will be displayed in your Merchant Dashboard. You can view the details of the split payout in the transaction view. The dashboard will provide a dedicated Split Payout section, showing a comprehensive breakdown of how the funds have been distributed among the designated beneficiaries.


    Sample Split Payout in transaction view

This process ensures that you have full visibility and control over your split payouts, from initiating the transaction to tracking its completion in the dashboard.

We are glad to be always in help. We aim to serve you better each time. As such, please spare a minute to share feedback about your recent experience with PayTabs Developers , on Trustpilot, or Google Reviews.