Version deployed on May 26, 2021. Back to the latest version

The fire.com API allows you to deeply integrate Business Account features into your application or back-office systems.

The API provides read access to your profile, accounts and transactions, event-driven notifications of activity on the account and payment initiation via batches. Each feature has its own HTTP endpoint and every endpoint has its own permission.

The API exposes 3 main areas of functionality: financial functions, service information and service configuration.

Financial Functions

These functions provide access to your account details, transactions, payee accounts, payment initiation etc.

Service Functions

These provide information about the fees and limits applied to your account.

Service configuration

These provide information about your service configs - applications, webhooks, API tokens, etc.

This is the documentation for version 1.0 of the API. Last update on May 26, 2021.

Base URL
https://api-preprod.fire.com/business/v1

Send a bearer token (“API Access Token” Formatted) in the Authorization http header to authenticate with the API.


fire.com Accounts are the equivalent of a bank account from bank.

List all fire.com Accounts

Returns all your fire.com Accounts. Ordered by Alias ascending. Can be paginated.

Responses
GET /accounts
curl \
 -X GET https://api-preprod.fire.com/business/v1/accounts \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Add a new account

Creates a new fire.com account.

Please note there is a charge associated with creating a new account.

Responses
  • 201

    The details of the new account

POST /accounts
curl \
 -X POST https://api-preprod.fire.com/business/v1/accounts \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d 'null'

Retrieve the details of a fire.com Account

You can retrieve the details of a fire.com Account by its ican.

Path parameters
  • ican Required / integer(int64)
Responses
  • 200

    An array of account objects.

  • 401
GET /accounts/{ican}
curl \
 -X GET https://api-preprod.fire.com/business/v1/accounts/{ican} \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Fire Open Payments is a feature of the fire.com business account that leverages Open Banking to allow your customers to pay you via bank transfer and to reconcile those payments as they are received into your fire.com GBP or EUR account.

To set up each Fire Open Payment you first need to create a payment request. This contains the details of the payment such as the amount, destination account, description as well as various other specific fields that you want to associate with the payment. The payment request is represented as a URL with a unique code which can then be incorporated into an eCommerce shopping cart as an alternative form of payment. For example, you can put “Pay by Bank” on your website along with “Pay by Card” and “Pay by PayPal”. It can also be distributed by a variety of means such as by email, SMS, WhatsApp, encoded as a QR code, NFC tag, etc.

Consumers confirm the payment details such as the amount are correct, select their bank and authorise the payment. Payments can be made from all major UK banks.

The funds are settled into your fire.com account, fully reconciled, with your specified fields provided.

There are two implementation options you can use to display payment pages with Fire Open Payments.

  1. Hosted Payment Pages: fire.com hosts the payment pages - this option allows you to re-direct your customer to the hosted fire.com payment pages displaying the payment details confirmation, bank selection, consent and response pages.
  2. Integrated Payment Pages: You host the payments page yourself - this option allows you to have control of the UI and UX for displaying the payment details confirmation, bank selection and response pages. Once the response is received, fire.com can re-direct the payer back to your website.

Hosted Payment Pages Option

Image

The payer is brought through 5 stages to complete the payment:

  1. View Payment Details page: The payer must first be clear on the amount of the payment, who they are paying and the reason for the payment.
  2. Select Bank / Account Provider page: The payer then selects their bank. Again this step is offered as part of the fire.com payment UI.
  3. Consent page: The payer must provide consent to the PISP (fire.com) prior to authorising the payment. This is a regulatory requirement, this page must be hosted by fire.com.
  4. Authenticate and Authorise Payment: The payer will be redirected to their bank’s online site or mobile banking app. After authenticating, the details of the payment will be displayed, and the payer will authorise the payment.
  5. Response page: It is a regulatory requirement that the PISP (fire.com) display the results of the payment and provide the same information that would be provided if the payer had made the payment via their banking application. fire.com must display this page, before optionally redirecting the payer back to your website.

To implement the hosted Fire Open Payments option you need to do the following:

  1. You can create a new Fire Open Payment request either within Firework Online or via the API.
  2. Create your new API application with the appropriate permissions required in Firework Online, as outlined in the “Authentication” steps. The permissions needed are:

    • “Create a Payment Request”
    • “Get Payment Details”
  3. Use the Refresh Token, Client ID and Client Key to create an access token as outlined in the “Authentication” steps.

  4. On your website, create a “Pay by Bank” button alongside your other available payment methods, such as Cards and PayPal.

  5. After the user clicks on “Pay by Bank”, you need to create a new Fire Open Payment request as outlined in the “Create a Fire Open Payment” steps. The Create a Fire Open Payment request endpoint returns a unique code for the payment request.

  6. Create a URL using the code returned in this format: https://payments.fire.com/{code} and redirect your customer to this page.

  7. fire.com will host all the pages that the customer needs to review and authorise the payment. fire.com will will return the paymentUUID of the successful or failed transaction to the returnUrl that you supplied when creating the Fire Open Payment request. fire.com can also optionally send a “webhook” to your website notifying you of the transaction’s outcome.

  8. Once fire.com responds with the paymentUUID and/or the webhook to your website, you need to call the “Get Payment Details” endpoint to get the details of the transaction. This will let you know whether the transaction was successful or not. You can set up the “Payment Request Payment Authorised” webhook to notify you once the payment is authorised or cancelled.

  9. The funds will be received into your GBP or EUR account. Funding will typically be within 6 business hours.

Once the code is returned the payment can be viewed and paid by going to the following URL: https://payments.fire.com/{code}

Create a Fire Open Payment request

Creates a new Fire Open Payment Payment request. A code is returned that can be shared to your customers as a URL by any channel you wish.
You will need to enable the PERM_BUSINESS_POST_PAYMENT_REQUEST permission to use this endpoint.

Responses
  • 200

    Payment Request created successfully

POST /paymentrequests
curl \
 -X POST https://api-preprod.fire.com/business/v1/paymentrequests \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d 'null'

Get list of ASPSPs / Banks

Returns all ASPSPs (Account Servicing Payment Service Provider) / banks. The list can be filtered by currency. You will need to enable the PERM_BUSINESS_GET_ASPSPS permission to use this endpoint.
This endpoint is only required if you intend to host the “Select ASPSP / bank” page yourself.

Query parameters
  • currency string

    The three letter code for the currency - either EUR or GBP. Use this to filter the list for banks that can be used to pay in a certain currency.

Responses
  • 200

    A list of ASPSPs the customers can use to pay a payment.

    • total integer

      The total number of ASPSPs in the list.

    • aspsps array[]
GET /aspsps
curl \
 -X GET https://api-preprod.fire.com/business/v1/aspsps \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Request a Refund for a Payment Request Payment

Process a request to refund a payment. The original payment must be in the PAID state.

Path parameters
Responses
  • 200

    Refund Request successful

  • 405

    Error Method not Allowed

POST /payments/{paymentUuid}/bankpayrefund
curl \
 -X POST https://api-preprod.fire.com/business/v1/payments/4ADFB67A-0F5B-4A9A-9D74-34437250045C/bankpayrefund \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d 'null'

Get Payment Details

Returns the details of a specific payment.

As the customer goes through the process of making the payment the status of the payment will change.

  • AWAITING_AUTHORISATION -This is the initial status of all your payments.
  • AUTHORISED - This is the status that your payment is set to after the customer has authorised the payment with their ASPSP / bank.
  • AWAITING_MULTI_AUTHORISATION - Some business accounts such as charities require dual authorisation.
  • NOT_AUTHORISED - Either your customer clicked on cancel or the payment was rejected by their ASPSP / bank.
  • PENDING - This is the status that your payment is set to after the customer has authorised the payment with their ASPSP / bank but the bank may want to carry out another check before funding the transaction.
  • PAID - Funds were received into your fire.com GBP or EUR account from your customer’s ASPSP / bank.

You will need to enable the PERM_BUSINESS_GET_PAYMENT permission to use this endpoint.

Path parameters
Responses
  • 200

    The Payment Request details object

GET /payments/{paymentUuid}
curl \
 -X GET https://api-preprod.fire.com/business/v1/payments/4ADFB67A-0F5B-4A9A-9D74-34437250045C \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Api

Manage your API Applications and Webhooks

Create a new API Application

Create a new API Application with specified permissions

Responses
  • 200

    API Application created successfully

POST /apps
curl \
 -X POST https://api-preprod.fire.com/business/v1/apps \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d 'null'

While there are many types of transactions, they are all represented by the same JSON object with a different txnType.

List transactions for an account

Retrieve a list of transactions against an account.

Path parameters
  • ican Required / integer(int64)
Responses
  • 200

    An array of transaction objects for the account with a count (total).

GET /accounts/{ican}/transactions
curl \
 -X GET https://api-preprod.fire.com/business/v1/accounts/{ican}/transactions \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Filtered list of transactions for an account

Retrieve a filtered list of transactions against an account.

  • dateRangeFrom - A millisecond epoch time specifying the date range start date.
  • dateRangeTo - A millisecond epoch time specifying the date range end date.
  • searchKeyword - Search term to filter by from the reference field (myRef).
  • transactionTypes - One or more of the transaction types above. This field can be repeated multiple times to allow for multiple transaction types.
Path parameters
  • ican Required / integer(int64)
Query parameters
Responses
  • 200

    An array of transaction objects for the account with a count (total) filtered by the specified query parameter.

GET /accounts/{ican}/transactions/filter
curl \
 -X GET https://api-preprod.fire.com/business/v1/accounts/{ican}/transactions/filter?dateRangeFrom=42.0&dateRangeTo=42.0&searchKeyword=string&transactionTypes=string \
 -H "Authorization: Bearer $ACCESS_TOKEN"

The fire.com api allows businesses to automate direct debit payment actions on their fire.com business accounts.

You can retrieve details of your direct debit payments, direct debit mandates and also take actions on both your direct debit payments and mandates.

Get all DD payments associated with a direct debit mandate

Retrieve all direct debit payments associated with a direct debit mandate.
The permision needed to access this endpoint is PERM_BUSINESS_GET_DIRECT_DEBITS

Query parameters
  • mandateUuid Required / string

    The mandate UUID to retrieve

Responses
  • 200

    Retrieve all direct debit payments associated with a direct debit mandate.

GET /directdebits
curl \
 -X GET https://api-preprod.fire.com/business/v1/directdebits?mandateUuid=1A07774B-1461-4595-BC4B-423B739712AF \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Get the deails of a direct debit

Retrieve all details of a single direct debit collection/payment, whether successful or not.
The permision needed to access this endpoint is PERM_BUSINESS_GET_DIRECT_DEBIT

Path parameters
Responses
  • 200

    Retrieve all details of a single direct debit collection/payment

GET /directdebits/{directDebitUuid}
curl \
 -X GET https://api-preprod.fire.com/business/v1/directdebits/4ADFB67A-0F5B-4A9A-9D74-34437250045C \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Reject a direct debit payment

This endpoint allows you to reject a direct debit payment where the status is still set to RECEIVED.
Permission name PERM_BUSINESS_POST_DIRECT_DEBIT_REJECT

Path parameters
Responses
  • 204

    204 no content

POST /directdebits/{directDebitUuid}/reject
curl \
 -X POST https://api-preprod.fire.com/business/v1/directdebits/4ADFB67A-0F5B-4A9A-9D74-34437250045C/reject \
 -H "Authorization: Bearer $ACCESS_TOKEN"

List all direct debit mandates

The permision needed to access this endpoint is PERM_BUSINESS_GET_MANDATES

Responses
  • 200

    List all direct debit mandates.

GET /mandates
curl \
 -X GET https://api-preprod.fire.com/business/v1/mandates \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Get direct debit mandate details

Retrieve all details for a direct debit mandate.
The permision needed to access this endpoint is PERM_BUSINESS_GET_MANDATE

Path parameters
Responses
  • 200

    Retrieve all details for a direct debit mandate.

GET /mandates/{mandateUuid}
curl \
 -X GET https://api-preprod.fire.com/business/v1/mandates/4ADFB67A-0F5B-4A9A-9D74-34437250045C \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Update a direct debit mandate alias

Update Direct Debit Mandate Alias
The permision needed to access this endpoint is PERM_BUSINESS_PUT_MANDATE

Path parameters
Responses
  • 204

    204 no content

POST /mandates/{mandateUuid}
curl \
 -X POST https://api-preprod.fire.com/business/v1/mandates/4ADFB67A-0F5B-4A9A-9D74-34437250045C \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Cancel a direct debit mandate

This endpoint allows you to cancel a direct debit mandate.
The permision needed to access this endpoint is PERM_BUSINESS_POST_MANDATE_CANCEL

Path parameters
Responses
  • 204

    204 no content

POST /mandates/{mandateUuid}/cancel
curl \
 -X POST https://api-preprod.fire.com/business/v1/mandates/4ADFB67A-0F5B-4A9A-9D74-34437250045C/cancel \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Activate a direct debit mandate

This endpoint can only be used to activate a direct debit mandate when it is in the status REJECT_REQUESTED (even if the account has direct debits disabled). This action will also enable the account for direct debits if it was previously set to be disabled.
The permision needed to access this endpoint is PERM_BUSINESS_POST_MANDATE_ACTIVATE

Path parameters
Responses
  • 204

    204 no content

POST /mandates/{mandateUuid}/activate
curl \
 -X POST https://api-preprod.fire.com/business/v1/mandates/4ADFB67A-0F5B-4A9A-9D74-34437250045C/activate \
 -H "Authorization: Bearer $ACCESS_TOKEN"

The fire.com API allows businesses to automate payments between their accounts or to third parties across the UK and Europe.

For added security, the API can only set up the payments in batches. These batches must be approved by an authorised user via the firework mobile app.

The process is as follows:

1.Create a new batch

2.Add payments to the batch

3.Submit the batch for approval

Once the batch is submitted, the authorised users will receive notifications to their firework mobile apps. They can review the contents of the batch and then approve or reject it. If approved, the batch is then processed. You can avail of enhanced security by using Dual Authorisation to verify payments if you wish. Dual Authorisation can be enabled by you when setting up your API application in firework online.

Batch Life Cycle Events

A batch webhook can be specified to receive details of all the payments as they are processed. This webhook receives notifications for every event in the batch lifecycle.

The following events are triggered during a batch:

batch.opened: Contains the details of the batch opened. Checks that the callback URL exists - unless a HTTP 200 response is returned, the callback URL will not be configured.

batch.item-added: Details of the item added to the batch

batch.item-removed: Details of the item removed from the batch

batch.cancelled: Notifies that the batch was cancelled.

batch.submitted: Notifes that the batch was submitted

batch.approved: Notifies that the batch was approved.

batch.rejected: Notifies that the batch was rejected.

batch.failed: Notifies that the batch failed - includes the details of the failure (insufficient funds etc)

batch.completed: Notifies that the batch completed successfully. Includes a summary.

Push notifications are sent to the firework mobile app for many of these events too - these can be configured from within the app.

List batches

Returns the list of batch with the specified types and statuses.

Query parameters
  • batchStatus string

    Values are SUBMITTED, REMOVED, SUCCEEDED, and FAILED.

  • batchTypes string

    Values are INTERNAL_TRANSFER, BANK_TRANSFER, and NEW_PAYEE.

  • orderBy string

    Values are DATE.

  • order string

    Values are DESC and ASC.

Responses
  • 200

    List all batches.

GET /batches
curl \
 -X GET https://api-preprod.fire.com/business/v1/batches \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Submit a batch for approval

Submits the Batch (for approval in the case of a BANK_TRANSFER). If this is an INTERNAL_TRANSFER batch, the transfers are immediately queued for processing. If this is a BANK_TRANSFER batch, this will trigger requests for approval to the firework mobile apps of authorised users. Once those users approve the batch, it is queued for processing.

You can only submit a batch while it is in the OPEN state.

Responses
  • 204

    No body is returned - a HTTP 204 No Content response signifies the call was successful.

PUT /batches
curl \
 -X PUT https://api-preprod.fire.com/business/v1/batches \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Create a new bath of payments

This is the first step in creating a batch payment.

Responses
  • 200

    Batch created successfully

POST /batches
curl \
 -X POST https://api-preprod.fire.com/business/v1/batches \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d 'null'

List items in a Batch

Returns a paginated list of items in the specified batch.

Path parameters
Query parameters
Responses
  • 200

    A fire.com list object of Batch Items (Internal transfers or Bank transfers).

GET /batches/{batchUuid}/internaltransfers
curl \
 -X GET https://api-preprod.fire.com/business/v1/batches/4ADFB67A-0F5B-4A9A-9D74-34437250045C/internaltransfers \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Add payment for an internal transfers

Simply specify the source account, destination account, amount and a reference.

Path parameters
Responses
  • 200

    Batch payment added successfully. Note* Please use batchUuid when submitting a batch, not batchItemUuid.

POST /batches/{batchUuid}/internaltransfers
curl \
 -X POST https://api-preprod.fire.com/business/v1/batches/4ADFB67A-0F5B-4A9A-9D74-34437250045C/internaltransfers \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d 'null'

List items in a Batch

Returns a paginated list of items in the specified batch.

Path parameters
Query parameters
Responses
  • 200

    A fire.com list object of Batch Items (Internal transfers or Bank transfers).

GET /batches/{batchUuid}/banktransfers
curl \
 -X GET https://api-preprod.fire.com/business/v1/batches/4ADFB67A-0F5B-4A9A-9D74-34437250045C/banktransfers \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Add payment for an bank transfers

There are two ways to process bank transfers - by Payee ID (Mode 1) or by Payee Account Details (Mode 2).

Mode 1: Use the payee IDs of existing approved payees set up against your account. These batches can be approved in the normal manner.

Mode 2: Use the account details of the payee. In the event that these details correspond to an existing approved payee, the batch can be approved as normal. If the account details are new, a batch of New Payees will automatically be created. This batch will need to be approved before the Payment batch can be approved. These payees will then exist as approved payees for future batches.

Path parameters
Responses
  • 200

    Batch payment added successfully. Note* Please use batchUuid when submitting a batch, not batchItemUuid.

POST /batches/{batchUuid}/banktransfers
curl \
 -X POST https://api-preprod.fire.com/business/v1/batches/4ADFB67A-0F5B-4A9A-9D74-34437250045C/banktransfers \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d 'null'

Remove a Payment from the Batch (Internal Transfer)

Removes a Payment from the Batch (Internal Transfer). You can only remove payments before the batch is submitted for approval (while it is in the OPEN state).

Path parameters
Responses
  • 200

    Batch payment deleted successfully.

DELETE /batches/{batchUuid}/internaltransfers/{itemUuid}
curl \
 -X DELETE https://api-preprod.fire.com/business/v1/batches/4ADFB67A-0F5B-4A9A-9D74-34437250045C/internaltransfers/4ADFB67A-0F5B-4A9A-9D74-34437250045C \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Remove a Payment from the Batch (Bank Transfers)

Removes a Payment from the Batch (Bank Transfers). You can only remove payments before the batch is submitted for approval (while it is in the OPEN state).

Path parameters
Responses
  • 200

    Batch payment deleted successfully.

DELETE /batches/{batchUuid}/banktransfers/{itemUuid}
curl \
 -X DELETE https://api-preprod.fire.com/business/v1/batches/4ADFB67A-0F5B-4A9A-9D74-34437250045C/banktransfers/{itemUuid} \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Get details of a single Batch

Returns the details of the batch specified in the API endpoint - {batchUuid}.

Path parameters
Responses
  • 200

    Returns the details of the batch specified in the API endpoint - {batchUuid}.

GET /batches/{batchUuid}
curl \
 -X GET https://api-preprod.fire.com/business/v1/batches/4ADFB67A-0F5B-4A9A-9D74-34437250045C \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Cancel a batch

Cancels the Batch. You can only cancel a batch before it is submitted for approval (while it is in the OPEN state).

Path parameters
Responses
  • 200

    Batch payment deleted successfully.

DELETE /batches/{batchUuid}
curl \
 -X DELETE https://api-preprod.fire.com/business/v1/batches/4ADFB67A-0F5B-4A9A-9D74-34437250045C \
 -H "Authorization: Bearer $ACCESS_TOKEN"

List Approvers for a Batch

Returns a list of approvers for this batch.

Path parameters
Responses
  • 200

    A list of approvers for this batch.

GET /batches/{batchUuid}/approvals
curl \
 -X GET https://api-preprod.fire.com/business/v1/batches/4ADFB67A-0F5B-4A9A-9D74-34437250045C/approvals \
 -H "Authorization: Bearer $ACCESS_TOKEN"

View List of Cards.

Returns a list of cards related to your fire.com account.

Responses
GET /cards
curl \
 -X GET https://api-preprod.fire.com/business/v1/cards \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Create a new debit card.

You can create multiple debit cards which can be linked to your fire.com accounts.

Responses
  • 200

    Card created successfully

POST /cards
curl \
 -X POST https://api-preprod.fire.com/business/v1/cards \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d 'null'

Returns list of all users on your fire.com account

You can retrieve the details of all fire.com users on your acount.

Responses
  • 200 array[]

    List of all Users.

GET /users
curl \
 -X GET https://api-preprod.fire.com/business/v1/users \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Returns details of a specific fire.com user.

You can retrieve the details of a specific fire.com user

Path parameters
Responses
  • 200

    Unique information about a User.

GET /user/{userId}
curl \
 -X GET https://api-preprod.fire.com/business/v1/user/14059 \
 -H "Authorization: Bearer $ACCESS_TOKEN"

List all Payee Bank Accounts

Returns all your payee bank accounts.

Ordered by date added descending.

Can be paginated.

Responses
  • 200

    An array of Payee Bank Accounts

GET /payees
curl \
 -X GET https://api-preprod.fire.com/business/v1/payees \
 -H "Authorization: Bearer $ACCESS_TOKEN"