Skip to main content

Adding more Request(s) to a Batch

Understanding Adding Request(s) to Batch​

After creating the batch, you may need to add deposit requests to ensure that funds are transferred to the intended recipients. Each deposit request is designed to transfer a specific amount of money to a designated beneficiary.

At this stage, you will need to fill in the beneficiary details, which include the beneficiary’s name, account number, and any other relevant information required for the transfer. This process ensures that each beneficiary receives the correct amount in a timely manner. Additionally, it is important to review all the details carefully to avoid any errors that could delay the transfer or result in funds being sent to the wrong account.

POST{{domain}}/payout/batch/request/add
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/payout/batch/request/add

Request Parameters​

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

ParameterData TypeMinMaxRequired
batch_id
INT-✔
The Batch ID as received from Creating Batch API.
{
        "batch_id": 987654,
    }
profile_id
INT-✔
PayTabs Merchant Profile ID.
{
        "profile_id": 654321,
    }
account_id
INT
-
✔
PayTabs Merchant Deposit Account ID.
{
    "account_id": 876543,
}
order_id
STRING
-
✔
Merchant's Batch Reference
{
    "order_id": "Payout-API-20220211"
}
requests
OBJECT
-
✗
Transfer record requests.
{
        "requests": 
        [
            .
            .
            .
        ]
    }
requests.[].merchant_reference
STRING
-
✗
Merchant specific data.
{
    "requests": 
    [
        {
            "merchant_reference": "1001",
        }
    ]
}
requests.[].amount
DECIMALNumeric with support for decimals✔
Transfer Amount
{
    "requests": 
    [
        {
            "amount": 1,
        }
    ]
}
requests.[].beneficiary_name
STRING
-
✔
Beneficiary Name as defined in the bank.
{
    "requests": 
    [
        {
            "beneficiary_name": "John Snow"
        }
    ]
}
requests.[].beneficiary_country
STRING
ISO 3166-1 Alpha-2 Codes
✔
Beneficiary Country Code.
{
    "requests": 
    [
        {
            "beneficiary_country": "SA"
        }
    ]
}
requests.[].beneficiary_account_number
INT Alphanumeric - Length as mentioned in https://www.iban.com/structure✔
Beneficiary account (IBAN, VIBAN).
{
    "requests": 
    [
        {
            "beneficiary_account_number": "SAXX0X0000XXX000XXXXX000"
        }
    ]
}
requests.[].beneficiary_bank
STRING
-
✔
Beneficiary Bank.
{
    "requests": 
    [
        {
            "beneficiary_bank": "Iron Bank of Braavos"
        }
    ]
}
requests.[].beneficiary_bank_branch
STRING
-
✔
Beneficiary Bank Branch.
{
    "requests": 
    [
        {
            "beneficiary_bank_branch": "Riyadh"
        }
    ]
}
requests.[].beneficiary_email
STRING
-
✔
Beneficiary Email address.
{
    "requests": 
    [
        {
            "beneficiary_email": "[email protected]"
        }
    ]
}
requests.[].beneficiary_mobile_number
STRING
-
✔
Beneficiary Mobile Number in E164 format.
{
    "requests": 
    [
        {
            "beneficiary_mobile_number": "+96612345678"
        }
    ]
}
requests.[].beneficiary_address1
STRING
-
✔
Beneficiary Address Line 1.
{
    "requests": 
    [
        {
            "beneficiary_address1": 
                "Riyadh, Building 6, Office 2"
        }
    ]
}
requests.[].beneficiary_address2
STRING
-
✔
Beneficiary Address Line 2.
{
    "requests": 
    [
        {
            "beneficiary_address2": 
                "Oroba Road, AlRahmania, 12334"
        }
    ]
}
requests.[].transfer_code
DECIMAL100 - Salary
101 - Pension
102 - General Cash Management
103 - Donation
✔
Transfer Code.
{
    "requests": 
    [
        {
            "transfer_code": 100
        }
    ]
}
requests.[].source_name
DECIMAL
1
30
✔
Payout ordering party name.
{
    "requests": 
    [
        {
            "source_name": "PayTabs Technical Support Team"
        }
    ]
}
requests.[].source_address1
DECIMAL
1
30
✔
Payout ordering party address 1.
{
    "requests": 
    [
        {
            "source_address1": 
                "Concord Tower - office 2712 27 Floor"
        }
    ]
}
requests.[].source_address2
DECIMAL
1
30
✔
Payout ordering party address 2.
{
    "requests": 
    [
        {
            "source_address2": 
                "Al Sufouh - Dubai Media City"
        }
    ]
}
requests.[].source_address3
DECIMAL
1
30
✔
Payout ordering party address 3.
{
    "requests": 
    [
        {
            "source_address3": 
                "Dubai - United Arab Emirates"
        }
    ]
}

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.

{
  "batch_id": 987654,
  "profile_id": 654321,
  "account_id": 876543,
  "order_id": "Payout-API-100101",
  "requests": [
      {
          "merchant_reference":"1234",
          "amount": 101,
          "beneficiary_name": "Rami Hegazi",
          "beneficiary_country": "SE",
          "beneficiary_account_number": "SE3550000000054910000003",
          "beneficiary_bank": "ESSESESS",
          "beneficiary_bank_branch": "",
          "beneficiary_email": "[email protected]",
          "beneficiary_mobile_number": "+971585436859",
          "beneficiary_address1": "Riyadh",
          "beneficiary_address2": "",
          "transfer_code": "100",
          "source_name": "PayTabs Technical Support Team",
          "source_address1": "address1",
          "source_address2": "address2",
          "source_address3": "address3"
      },
      {
          "merchant_reference":"8906",
          "amount": 155,
          "beneficiary_name": "Rami Hegazi",
          "beneficiary_country": "SE",
          "beneficiary_account_number": "SE3550000000054910000003",
          "beneficiary_bank": "ESSESESS",
          "beneficiary_bank_branch": "",
          "beneficiary_email": "[email protected]",
          "beneficiary_mobile_number": "+971585436859",
          "beneficiary_address1": "Riyadh",
          "beneficiary_address2": "",
          "transfer_code": 101,
          "source_name": "PayTabs Technical Support Team",
          "source_address1": "address1",
          "source_address2": "address2",
          "source_address3": "address3"
      }
  ]
}

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.