Query Single Batch

Once a batch has been created, it's important to monitor its progress to ensure the payout process is on track. In this manual, we’ll show you how to query a single batch using our API to retrieve details such as the batch status, total amount, and any pending actions. This guide will walk you through:

• How to use the API to query a specific batch by its unique ID
• Understanding the batch's current status and related information
• What to do if the batch is incomplete or facing issues

By the end of this manual, you’ll have the knowledge needed to track your batches effectively and stay informed about the progress of your payouts.

---

The Endpoint and Related Postman Collection

POST	{{domain}}/payout/batch/query

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/query

UAE

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

Egypt

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

Oman

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

Jordan

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

Kuwait

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

Global

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

---

Request Parameters

To initiate a query batch request using this API Endpoint, there are specific parameters that need to be passed with valid information. The specification of these parameters is clarified below:

The Minimum Required Parameters

Parameter	Data Type	Min	Max	Required
batch_id	INT	Unique ID of for a batch.		✔
	{ "batch_id": 263 }
profile_id	INT	Unique profile ID associated with the batch.		✔
	{ "profile_id": 47128 }
account_id	INT	Unique ID of the merchant account associated with the batch.		✔
	{ "account_id": 17 }

---

Request & Response Payload Samples

This section is dedicated give you a sample API request payload using the above mentioned required 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

{
  "batch_id": 263,
  "profile_id": "47128",
  "account_id": "17"
}

Sample Response Payload

{
  "batch_id": 263,
  "profile_id": 47128,
  "account_id": 17,
  "currency": "SAR",
  "total": "153.99",
  "count": 1,
  "order_id": "Split (2023-10-31)",
  "status": "Completed",
  "requests":
  [
          {
              "batch_id": 263,
              "entry_id": 465,
              "merchant_reference": "Meal,Delivery Fee,Tip",
              "merchant_reference2": "cart_11123,cart_11123,cart_11123",
              "merchant_reference3": "Description of the items/services,Description of t",
              "amount": "153.99",
              "fee": "3.5",
              "total": "157.49",
              "beneficiary_account_number": "SA3305000068200027493000",
              "beneficiary_mobile_number": "+971585436859",
              "method": "Iban",
              "status": "Paid",
              "protocol_message": "The request has been queued, and should be authorized after 15 minutes.",
              "protocol_ref_1": "1703049936",
              "protocol_ref_2": "test-referral-1",
              "protocol_ref_3": "test-referral-2"
          }
  ],
  "trace": "PMNT0001.66E93142.0000000C",
  "processing_date_utc": "2023-12-20"
}