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:

ParameterData TypeMinMaxRequired
profile_id
INTAccept only valid profile number✔
The merchant Profile ID you can get from your PayTabs dashboard. For more information please check ourHow to get your account information from PT2 Dashboard?tutorial article.
To know more about this parameter pleaseclick here.
{
    "profile_id": 987654
}
tran_type
STRING

Valid string from this enum list:

sale auth refund register void 		✔
the identification of the type of the transaction. To know more about these types please check ourWhat is the "tran_type" (transaction type)?solution article.
To know more about this parameter pleaseclick here.
{
    "tran_type": "sale"
}
tran_class
STRING

Valid string from this list

ecom recurringmoto		✔
the identification of the category/class this transaction will follow, such as eCommerce, Recurring, etc. To know more about these types please check ourWhat is the "tran_class" (transaction class)?solution article.
To know more about this parameter pleaseclick here.
{
     "tran_class": "ecom"
}
cart_id
STRING
1
64
✔
Indicates the cart/order id at the merchant end to easily relate the transaction to.
To know more about this parameter pleaseclick here.
{
     "cart_id": "CART#10001"
}
cart_description
STRING
1
128
✔
Indicates the cart/order description at the merchant end to easily relate the transaction to.
To know more about this parameter pleaseclick here.
{
     "cart_description": "Description of the items/services"
}
cart_currency
STRINGValid string from the following list:
SAR AED BHDEGP EUR GBP HKD IDR INR IQD JOD JPY KWD MAD OMR PKR QAR USD
Accepts both upper- and lower-case characters		✔
Indicates the transaction currency, which the customer will be charged with.
To know more about this parameter pleaseclick here.
{
     "cart_currency": "SAR"
}
cart_amount
DECIMAL
0.01
9999999999.99
✔
Indicates 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 pleaseclick here.
{
     "cart_amount": 500
}
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" : "beneficiary1@email.com"
    }
}
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": "demo@paytabs.com",
              "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.