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 https://business.fire.com.
-
Select the “Settings“ Menu.
-
Select the “API” tab.
-
Click “Add New Application“
Give you API Application a name, and select the required permissions.
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.
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).
Authentication
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 IDcreated above. -
Refresh Token – The app’s
Refresh Tokencreated 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 https://api.fire.com/business/v1/apps/accesstokens 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:
-
Create a new batch
-
Add payments to the batch
-
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 Batch
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:
-
INTERNAL_TRANSFER– All the payments are funds movements between your own Fire accounts. -
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 https://api.fire.com/business/v1/batches 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. SayJanuary 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
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 https://api.fire.com/business/v1/batches/{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
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 https://api.fire.com/business/v1/batches/{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 webhook.site) to showcase what a webhook call may look like:
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 https://jwt.io for testing purposes. Your system can now receive live updates when Batches are made, approved or submitted.
