Skip to main content

Closing a Batch: Finalizing Your External Payouts

After creating a batch and adding the necessary payout requests, the next step in the external payout workflow is to close the batch. Closing a batch ensures that the requests are finalized and processed for distribution to the designated beneficiaries. This is particularly relevant for external payouts, where funds are sent to outside beneficiaries, often via IBANs.

In this manual, we’ll guide you through the steps to close a batch and finalize your external payouts. Each request within a batch contains its own beneficiary details, ensuring accurate transfers to the intended recipients.

For more information on how to create a batch and add deposit requests, please refer to our External Payout APIs Workflow manual.

By the end of this manual, you’ll understand how to close a batch effectively and ensure that your payout requests are processed without any issues.

you should know

You should know that you can close the batch while creating it from the beginging by providing all the needed requests and the "close_batch" parameter within the create batch payload.

Limitations​

There are some Limitations that may stop closing batch, check the following:

  • Balance:
    You should make sure that the deposit account that you choose in the batch, have enough balance to cover the batch amount (all requests amount), or you will face an error.
  • Count:
    Count parameter that mentioned in the request payload, is mandatory and if the batch contains 5 requests and you pass 4 in the count parameter, you will face validation error, so make sure to pass the right count of request in the batch.
  • Total:
    Total parameter that mentioned in the request payload, is mandatory and if the total amount of the batch is 10 SAR and you pass 9, you will face validation error. make sure to pass the total amount of the batch right (total requests amount).
POST{{domain}}/payout/batch/close
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/close

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:

ParameterData TypeMinMaxRequired
batch_id
INTUnique ID of for a batch.✔
{
        "batch_id": 263
    }
profile_id
INTUnique profile ID associated with the batch.✔
{
        "profile_id": 47128
    }
account_id
INTUnique ID of the merchant account associated with the batch.✔
{
    "account_id": 17
    }
count
INTNumber of requests in the batch ( entry )✔
{
        "count": 2
    }
total
INTTotal payout amount for the batch✔
{
    "total": 120
    }

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.

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": 437,
  "profile_id": "47128",
  "account_id": "17",
  "count": 1,
  "total": 1
}

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:

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.