Create Payout Batch

The first and most important step in the External Payout workflow is creating a batch. A batch acts as a container for your deposit requests, grouping them into a single, manageable unit. By organizing requests into a batch, you can easily track, process, and review them all at once, making the payout process smoother and more efficient.

When you create a batch, you have two options:

• You can create the batch first and add deposit requests to it later which will be clarified in our Adding more Request(s) to a Batch manual.
• Or, you can create a batch, add requests to this batch, and close the batch all that in the same time/request which will be clarified in this manual.

This flexibility allows you to manage your workflow based on your business needs. Grouping your deposit requests into a batch ensures they are processed consistently and efficiently, saving time and reducing manual effort.

For a full guide on managing the entire External Payout process—including adding and closing batches—be sure to check out our External Payout APIs Workflow manual.

Let’s dive into how to create your first batch and set your payouts in motion!

---

The Endpoint and Related Postman Collection

POST	{{domain}}/payout/batch/new

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.

KSA

https://secure.paytabs.sa/payout/batch/new

UAE

https://secure.paytabs.com/payout/batch/new

Egypt

https://secure-egypt.paytabs.com/payout/batch/new

Oman

https://secure-oman.paytabs.com/payout/batch/new

Jordan

https://secure-jordan.paytabs.com/payout/batch/new

Kuwait

https://secure-kuwait.paytabs.com/payout/batch/new

Global

https://secure-global.paytabs.com/payout/batch/new

---

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:

The Minimum Required Parameters

Parameter	Data Type	Min	Max	Required
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" }

The Available Optional Parameters

Parameter	Data Type	Min	Max	Required
requests	OBJECT	-		❌
	Transfer record requests.
	{ "requests": [ . . . ] }
requests.[].merchant_reference	STRING	-		❌
	Deposit request's reference at the merchant side
	{ "requests": [ { "merchant_reference": "1001", } ] }
requests.[].amount	DECIMAL	Numeric 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	DECIMAL	100 - 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" } ] }
close_batch	BOOLEAN	at lease one request must exist to pass this parameter		❌
	When passed "true", this will close the batch and send it to review directly once it is created.
	{ "close_batch": true }

---

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.

Required Parameters Sample Payloads

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.

Sample Request Payload

{
"profile_id": 654321,
"account_id": 876543,
"order_id": "Payout-API-20220211",
}

Sample Response Payload

{
  "batch_id": 12,
  "profile_id": 48264,
  "account_id": 5154,
  "currency": "SAR",
  "total": "0",
  "count": 0,
  "order_id": "Payout-API-20220211",
  "status": "New",
  "trace": "PMNT0201.62376344.00074C2A"
}

Optional Parameters Sample Payloads

The below sample request payload will show you how you can pass the above-mentioned optional 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.

Sample Request Payload

{
"profile_id": 654321,
"account_id": 876543,
"order_id": "Payout-API-20220211",
"requests":
[
	{
		"merchant_reference":"1001",
		"amount": 100,
		"beneficiary_name": "John Snow",
		"beneficiary_country": "SA",
		"beneficiary_account_number": "SA2910000005100003144805",
		"beneficiary_bank": "NCB",
		"beneficiary_bank_branch": "",
		"beneficiary_email": "[email protected]",
		"beneficiary_mobile_number": "+971123456789",
		"beneficiary_address1": "Riyadh",
		"beneficiary_address2": "",
		"transfer_code": 100,
		"source_name": "PayTabs Technical Support Team",
		"source_address1": "address1",
		"source_address2": "address2",
		"source_address3": "address3"
	}
]
}

Sample Response Payload

{
"batch_id": 12,
"profile_id": 48264,
"account_id": 5154,
"currency": "SAR",
"total": "0",
"count": 0,
"order_id": "Payout-API-20220211",
"status": "New",
"trace": "PMNT0201.62376344.00074C2A"
}

---

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: