Batch API Tutorial

November 17, 2021

Automating your payout process with batches

In a previous blog post we described the payouts pain point some businesses experience today, how Fire can help automate this process and examples of automated payout processes some Fire customers have implemented today. In this blog post we’ll walk you through the steps needed to set up an automated payouts process in your organisation using payment batches via the Fire API.

Application Set-Up

Firstly, you will need to set up set up a Fire Application to access the Fire API. To do this:

  • Login at

  • Select the “Settings“ Menu.

  • Select the “API” tab.

  • Click “Add New Application“

a8371dc7 43d2 457e 8df2 29fff8f0708c

Give you API Application a name, and select the required permissions.

bdfded78 a604 4b3e 90e4 207962aa88b7
For this Tutorial we will be showcasing the Batch functionality so select the Batch permissions below:
2d7e6840 d029 4468 822e 1342fb458c2a

You then can configure how many approvers are need prior to processing a batch. There are 2 types of approvals:

  • Approvals for adding a new payee for a batch – in line with legislation, you are required to approve new payees on your account using Strong Customer Authentication (SCA). The first time you make a payment to a payee, Fire will send notifications to Full Users so they can approve. This will be a single notification containing the details of all the new payees in the batch. Once a payee has been approved on your account, it is not necessary to approve payments going forward (although you can can opt to approve all payments – see below).

  • Approvals for batches of bank transfers – you can set this to 0 to automatically process batch payments to previously approved payees. This is useful for setting up unattended automated batch payments.

You can also have multiple approvers if you want for either type to enhance security. All full users will get a push notification to approve to their linked mobile devices to approve the batch.

1b3f622e 4d6f 44de bc08 6dfc246fc243

Once you’ve finished above, click “Create“, and take note of your Client ID, Client Key and Refresh Token – the Client Key will not be displayed again.

Note  If you ever accidentally reveal the Client Key (or accidentally commit it to Github for instance) it is vital that you log into firework online and delete/recreate the App Tokens as soon as possible. Anyone who has these three pieces of data can access the API to view your data and set up payments from your account (depending on the scope of the tokens).


You now use these pieces of data to retrieve a short-term Access Token which you can use to access the API. This will be set as the Bearer Token in the ‘Authorization’ header for all API calls. For security reasons, the Access Token expires within a relatively short timeframe – there is a 15 minute window to use it.

In order to create an Access Token, you require:

  • Client ID – The app’s Client ID created above.

  • Refresh Token – The app’s Refresh Token created above.

  • Nonce – A random non-repeating number (that is incremented from the previously used value) used as a salt for the clientSecret below. The simplest nonce is a unix time.
  • Client Secret – A Client Secret is the a SHA256 sum of the nonce concatenated with the Client Key: sha256(<NONCE><CLIENT_KEY>)

To retrieve the Access Token, send a POST request to containing the following JSON body:

You will receive an Access Token and details of the allowed permissions in response:

Once you have the access token, pass it as a header for every API call, like so:

Authorization: Bearer $ACCESS_TOKEN

Whenever it expires, create a new nonce and get a new access token again.

Processing a Batch

The process is as follows:

  1. Create a new batch

  2. Add payments to the batch

  3. Submit the batch for approval

Download a Postman Collection which contains all of the main batch calls you can use to follow along with this tutorial.
In Postman, you can import this collection by copying this URL and pasting it in the import section.

1. Create a new Batch921c6b2d bd5f 408f b17c 9ed10d156e46

The first step in making a making a batch payment is creating the batch itself. The batch object can be thought of as a container which you can add multiple payments to which are to be made at the same time. The batch object specifies the name, currency and type of the batch.

There are 2 batch types you can create:

  1. INTERNAL_TRANSFER – All the payments are funds movements between your own Fire accounts.

  2. BANK_TRANSFER – All the payments relate to fund movements outside of your own Fire accounts (e.g to a Payee)

For this tutorial, we will be making a BANK_TRANSFER batch. Send a POST request to with the following JSON:

  • callBackUrl:An optional POST URL that all events for this batch will be sent to – see the section on webhooks below.
  • batchName: An optional name you give to the batch at creation time. Say January 2018 Payroll.
  • jobNumber:An optional job number you can give to the batch to help link it to your own system.

You will receive the batch UUID in response:

2. Add a bank transfer to a Batch

09da3555 6fa5 408d 9919 c10a2fabdb85

Now that we have a batch UUID, the next step is to add some bank transfers to the batch. This is done by passing the account details, amount and references to the API. If the account details relate to an existing payee, the batch will be processed as normal. If this is your first time making a bank transfer to these account details, you will get a push notification to your phone to approve the new payees in the batch once you submit the batch in the next step. Once these new payees have been approved you won’t need to approve them again in future batches.

POST the bank transfer details as a JSON object to{batchUuid}/banktransfers

You will receive a bank transfer item UUID in response. You can use this UUID to query the status of the payment, or to remove the payment from the batch.

3. Submit the batch for approval

0034a947 16c1 478b 9b28 76e218373353#media blob url=true&id=f65cc528 f342 4231 a9df 89d3bbfb8159&collection=contentId 3288662028&contextId=3288662028&mimeType=image%2Fpng&name=step%203 20211020 083753
0034a947 16c1 478b 9b28 76e218373353

Once you have added all the bank transfers you wish to make, it is now time to submit the batch to make the payments. Send a PUT request to{BatchUUID}. This will result in a 204 NO CONTENT response.

Depending on how you configured the API keys above, this may trigger a request for approval to all full users of the account. They can login to the Firework mobile app to view the details of the requests and approve/reject. Once approved, all the bank transfers in the batch are sent out to the payees and the batch process is complete.

Callback/Webhook real-time notifications:

If a callbackURL was specified in the Create Batch API call, you will be notified in real time when payments are submitted, approved and complete. This is a popular feature Fire offers and will allow your systems to make real time updates accordingly.

Below is an image (using to showcase what a webhook call may look like:Webhook Received Img

Each webhook call will contain a JWT payload (as seen in the Raw Content section) in the body. You can decode this JWT payload token to JSON in your own code, or by going to for testing purposes. Your system can now receive live updates when Batches are made, approved or submitted.


Jake Profile

Jake McCarthy is a Product Analyst at Fire with experience across partner payment solutions, transaction monitoring and payment processing.

Ready to get started?

© 2015 – 2023 Fire Financial Services Limited trading as and Fire.
Fire Financial Services Limited (Fire-EU) is regulated by the Central Bank of Ireland, Reference No: C58301. Registered address: Dogpatch Labs, The CHQ Building, Custom House Quay, Dublin 1, D01 Y6H7, Ireland. Incorporated in Dublin, Ireland, Registration No: 464819.
Fire Financial Services Limited (Fire-UK) is authorised as an Electronic Money Institution by the Financial Conduct Authority, Reference No: 900983. Registered Address: The Rise, 41 Luke Street, London, United Kingdom, EC2A 4DP. Incorporated in England and Wales, Registration No: 11549793.