Query Batch With Merchant Reference

For businesses managing multiple payout batches, staying organized is crucial. In this manual, we’ll explain how to query batches by merchant reference, allowing you to retrieve batches that are tied to specific transactions or accounts through the below points:

• How to use your merchant reference to query and retrieve batches via API
• Tracking batches associated with a particular project or account
• How to use this data for easier reconciliation and reporting

By querying batches using merchant reference, you can streamline your tracking process and maintain better control over your payouts.

---

The Endpoint and Related Postman Collection

POST	{{domain}}/payout/batch/request/search

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/request/search

UAE

https://secure.paytabs.com/payout/batch/request/search

Egypt

https://secure-egypt.paytabs.com/payout/batch/request/search

Oman

https://secure-oman.paytabs.com/payout/batch/request/search

Jordan

https://secure-jordan.paytabs.com/payout/batch/request/search

Kuwait

https://secure-kuwait.paytabs.com/payout/batch/request/search

Global

https://secure-global.paytabs.com/payout/batch/request/search

---

Request Parameters

To initiate a query batch request searching for specific merchant reference 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
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 }
merchant_reference	STRING	Merchant reference for the transaction.		✔
	{ "merchant_reference": 960 }

---

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

{
  "profile_id": "47128",
  "account_id": "17",
  "merchant_reference":"Delivery Fee"
}

Sample Response Payload

{
  [
      {
          "batch_id": 441,
          "entry_id": 961,
          "merchant_reference": "Delivery Fee",
          "merchant_reference2": "",
          "merchant_reference3": "",
          "amount": "97.25",
          "fee": "3.5",
          "total": "100.75",
          "beneficiary_account_number": "BH29BMAG1299123456BH00",
          "method": "Iban",
          "status": "Rejected",
          "protocol_message": ""
      },
      {
          "batch_id": 441,
          "entry_id": 963,
          "merchant_reference": "Delivery Fee",
          "merchant_reference2": "",
          "merchant_reference3": "",
          "amount": "97",
          "fee": "4.5",
          "total": "100",
          "beneficiary_account_number": "BH29XXXG1299123456BH00",
          "method": "Iban",
          "status": "Pending",
          "protocol_message": ""
      }
  ]
}