Fire Financial Services Business API

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

Authentication

Access to the API is by Bearer Tokens. The process is somewhat similar to OAuth2.0, but with some changes to improve security.

  1. You must first log into the firework online application and create a new Application in the Profile > API page. (You will need your PIN digits and 2-Factor Authentication device).
  2. Give your application a Name and select the scope/permissions you need the application to have (more on Scopes below).
  3. You will be provided with three pieces of information - the App Refresh Token, Client ID and Client Key. You need to take note of the Client Key when it is displayed - it will not be shown again.

You now use these pieces of data to retrieve a short-term Access Token which you can use to access the API. The Access Token expires within a relatively short time, so even if it is compromised, the attacker will not have long to use it. The Client Key is the most important piece of information to keep secret. This should only ever be stored on a backend server, and never in a front end client or mobile app.

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).

Once you have the access token, pass it as a header for every call, like so:
Authorization: Bearer $ACCESS_TOKEN
Whenever it expires, create a new nonce and get a new access token again.

Authenticate with the API.

TODO - Authenticate with the API.

Body
  • clientId string

    The Client ID for this API Application

  • refreshToken string

    The Refresh Token for this API Application

  • nonce integer(int64)

    A random non-repeating number used as a salt for the clientSecret below. The simplest nonce is a unix time.

  • grantType string

    Always AccessToken. (This will change to refresh_token in a future release.)

    Values are AccessToken.

  • clientSecret string

    The SHA256 hash of the nonce above and the app’s Client Key. The Client Key will only be shown to you when you create the app, so don’t forget to save it somewhere safe.

Responses
  • • 200 object

    Successfully authenticated

    • businessId integer(int64)

      The business ID for the business.

    • apiApplicationId integer(int64)

      The ID of the application you are using.

    • expiry string(date-time)

      The expiry date and time for this token (ISO-8601).

    • permissions array[string]

      The permissions assigned to the Access Token as an array of strings. This provides information on what API access it is allowed. See the section on Scope below.

    • accessToken string

      The App Bearer Access Token you can use in further API calls.

Definition
POST https://api-preprod.fire.com/business/v1/apps/accesstokens
cURL example
curl \ -X POST https://api-preprod.fire.com/business/v1/apps/accesstokens \ -H "Content-Type: application/json" \ -d '{"clientId":"4ADFB67A-0F5B-4A9A-9D74-34437250045C","refreshToken":"4ADFB67A-0F5B-4A9A-9D74-34437250045C","nonce":728345638475,"grantType":"AccessToken","clientSecret":"4ADFB67A-0F5B-4A9A-9D74-34437250045C"}'
Request payload example
{ "clientId": "4ADFB67A-0F5B-4A9A-9D74-34437250045C", "refreshToken": "4ADFB67A-0F5B-4A9A-9D74-34437250045C", "nonce": 728345638475, "grantType": "AccessToken", "clientSecret": "4ADFB67A-0F5B-4A9A-9D74-34437250045C" }
Response example (200)
{ "businessId": 248, "apiApplicationId": 433, "expiry": "2020-10-22T07:48:56.460Z", "permissions": [ "PERM_BUSINESSES_GET_ACCOUNTS", "PERM_BUSINESSES_GET_ACCOUNT_TRANSACTIONS" ], "accessToken": "4ADFB67A-0F5B-4A9A-9D74-34437250045C" }

Accounts

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
  • • 200 object

    An array of account objects.

    • accounts array[object]
      • ican integer(int64)

        identifier for the fire.com account (assigned by fire.com)

      • name string

        the name the user gives to the account to help them identify it.

      • colour string Deprecated

        Internal Use

      • currency object
        • code string

          The three letter code for the currency - either EUR or GBP.

          Values are EUR and GBP.

        • description string

          The name of the currency

      • balance integer(int64)

        the balance of the account (in minor currency units - pence, cent etc. 434050 == 4,340.50 GBP for a GBP account).

      • status string

        Live accounts can be used as normal. Migrated accounts were used before Brexit and are read-only.

        Values are LIVE and MIGRATED.

      • cbic string

        the BIC of the account (provided if currency is EUR).

      • ciban string

        the IBAN of the account (provided if currency is EUR).

      • cnsc string

        the Sort Code of the account.

      • ccan string

        the Account Number of the account.

      • defaultAccount boolean

        true if this is the default account for this currency. This will be the account that general fees are taken from (as opposed to per-transaction fees).

      • directDebitsAllowed boolean

        Whether or not direct debits can be set up on this account.

  • • 401

    Access Token is Invalid or missing

Definition
GET https://api-preprod.fire.com/business/v1/accounts
cURL example
curl \ -X GET https://api-preprod.fire.com/business/v1/accounts
Response example (200)
{ "accounts": [ { "ican": 42, "name": "Main Account", "colour": "ORANGE", "currency": { "code": "EUR", "description": "Euro" }, "balance": 23950, "status": "LIVE", "cbic": "CPAYIE2D", "ciban": "IE54CPAY99119911111111", "cnsc": "232221", "ccan": "11111111", "defaultAccount": true, "directDebitsAllowed": true } ] }
Response example (401)
No content

Add a new account

Creates a new fire.com account.

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

Body
  • accountName string

    Name to give the new account

  • currency string

    The currency of the new account

    Values are EUR and GBP.

  • acceptFeesAndCharges boolean

    a field to indicate you accept the fee for a new account

Responses
  • • 201 object

    The details of the new account

    • ican integer(int64)

      identifier for the fire.com account (assigned by fire.com)

    • name string

      the name the user gives to the account to help them identify it.

    • colour string Deprecated

      Internal Use

    • currency object
      • code string

        The three letter code for the currency - either EUR or GBP.

        Values are EUR and GBP.

      • description string

        The name of the currency

    • balance integer(int64)

      the balance of the account (in minor currency units - pence, cent etc. 434050 == 4,340.50 GBP for a GBP account).

    • status string

      Live accounts can be used as normal. Migrated accounts were used before Brexit and are read-only.

      Values are LIVE and MIGRATED.

    • cbic string

      the BIC of the account (provided if currency is EUR).

    • ciban string

      the IBAN of the account (provided if currency is EUR).

    • cnsc string

      the Sort Code of the account.

    • ccan string

      the Account Number of the account.

    • defaultAccount boolean

      true if this is the default account for this currency. This will be the account that general fees are taken from (as opposed to per-transaction fees).

    • directDebitsAllowed boolean

      Whether or not direct debits can be set up on this account.

Definition
POST https://api-preprod.fire.com/business/v1/accounts
cURL example
curl \ -X POST https://api-preprod.fire.com/business/v1/accounts \ -H "Content-Type: application/json" \ -d '{"accountName":"Operating Account","currency":"EUR","acceptFeesAndCharges":true}'
Request payload example
{ "accountName": "Operating Account", "currency": "EUR", "acceptFeesAndCharges": true }
Response example (201)
{ "ican": 42, "name": "Main Account", "colour": "ORANGE", "currency": { "code": "EUR", "description": "Euro" }, "balance": 23950, "status": "LIVE", "cbic": "CPAYIE2D", "ciban": "IE54CPAY99119911111111", "cnsc": "232221", "ccan": "11111111", "defaultAccount": true, "directDebitsAllowed": true }

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 object

    An array of account objects.

    • ican integer(int64)

      identifier for the fire.com account (assigned by fire.com)

    • name string

      the name the user gives to the account to help them identify it.

    • colour string Deprecated

      Internal Use

    • currency object
      • code string

        The three letter code for the currency - either EUR or GBP.

        Values are EUR and GBP.

      • description string

        The name of the currency

    • balance integer(int64)

      the balance of the account (in minor currency units - pence, cent etc. 434050 == 4,340.50 GBP for a GBP account).

    • status string

      Live accounts can be used as normal. Migrated accounts were used before Brexit and are read-only.

      Values are LIVE and MIGRATED.

    • cbic string

      the BIC of the account (provided if currency is EUR).

    • ciban string

      the IBAN of the account (provided if currency is EUR).

    • cnsc string

      the Sort Code of the account.

    • ccan string

      the Account Number of the account.

    • defaultAccount boolean

      true if this is the default account for this currency. This will be the account that general fees are taken from (as opposed to per-transaction fees).

    • directDebitsAllowed boolean

      Whether or not direct debits can be set up on this account.

  • • 401

    Access Token is Invalid or missing

Definition
GET https://api-preprod.fire.com/business/v1/accounts/{ican}
cURL example
curl \ -X GET https://api-preprod.fire.com/business/v1/accounts/{ican}
Response example (200)
{ "ican": 42, "name": "Main Account", "colour": "ORANGE", "currency": { "code": "EUR", "description": "Euro" }, "balance": 23950, "status": "LIVE", "cbic": "CPAYIE2D", "ciban": "IE54CPAY99119911111111", "cnsc": "232221", "ccan": "11111111", "defaultAccount": true, "directDebitsAllowed": true }
Response example (401)
No content

Open banking

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.

Body
  • currency Required / string

    Either EUR or GBP, and must correspond to the currency of the account the funds are being lodged into in the icanTo.

    Values are EUR and GBP.

  • type Required / string

    The type of Fire Open Payment that was created

    Values are OTHER.

  • icanTo Required / integer(int64)

    The ican of the account to collect the funds into. Must be one of your fire.com Accounts.

  • amount integer(int64)

    The requested amount to pay. Note the last two digits represent pennies/cents, (e.g., £1.00 = 100).

  • myRef Required / string

    An internal description of the request.

  • description Required / string

    A public facing description of the request. This will be shown to the user when they tap or scan the request.

  • maxNumberPayments integer

    The max number of people who can pay this request. Must be set to 1 for the ECOMMERCE_GOODS and ECOMMERCE_SERVICES types.

  • expiry string(date-time)

    This is the expiry of the payment request. After this time, the payment cannot be paid.

  • returnUrl string

    The merchant return URL where the customer will be re-directed to with the result of the transaction.

  • orderDetails object
    • merchantNumber string

      Your Merchant Number (if applicable).

    • orderId string

      Use this field to store the order id for the transaction. The Order Id cannot be set unless the maxNumberPayments is 1.

    • productId string

      Use this field to store a product id for the transaction (for example).

    • customerNumber string

      Use this field to store a customer number for the transaction (for example).

    • variableReference string

      Use this field to store any other reference for the transaction (for example, a phone number).

    • comment1 string

      This is your own comment for the transaction.

    • comment2 string

      This is your own comment for the transaction.

    • merchantCustomerIdentification string

      This is a reference you use to uniquely identify each of your customers.

    • deliveryAddressLine1 string

      The first line of the delivery address.

    • deliveryAddressLine2 string

      The second line of the delivery address.

    • deliveryCity string

      Delivery address city

    • deliveryPostCode string

      Delivery address post code

    • deliveryCountry string

      2-digit code for the country

  • collectFields string

    For the hosted option, the payer will be asked to fill in these fields but they will not be mandatory. You can choose to collect any of the payer's ADDRESS, REFERENCE and/or COMMENT1. If you choose to collect these fields from the payer, you cannot set 'delivery’, 'variableReference’ or 'comment1’ fields respectively.

  • mandatoryFields string

    For the hosted option, these fields will be madatory for the payer to fill in on the hosted payment page. You can choose to collect any the payer's ADDRESS, REFERENCE and/or COMMENT1. If you choose to collect these fields from the payer, you cannot set 'delivery’, 'variableReference’ or 'comment1’ fields respectively.

  • additionalFields string

    These fields will be dispalyed to the payer when using the hosted option. You can choose to display any of ORDER_ID, PRODUCT_ID, CUSTOMER_ID, CUSTOMER_NUMBER and COMMENT2 to the payer.

Responses
  • • 200 object

    Payment Request created successfully

    • code string

      The code for this request. Create a URL in this format: https://payments.fire.com/{code} and share to your customers.

    • type string

      The type of Fire Open Payment that was created.

      Values are OTHER.

Definition
POST https://api-preprod.fire.com/business/v1/paymentrequests
cURL example
curl \ -X POST https://api-preprod.fire.com/business/v1/paymentrequests \ -H "Content-Type: application/json" \ -d '{"currency":"EUR","type":"OTHER","icanTo":42,"amount":1000,"myRef":"Fees","description":"Gym Fees Oct 2020","maxNumberPayments":1,"expiry":"2020-10-22T07:48:56.460Z","returnUrl":"https://example.com/callback","orderDetails":{"merchantNumber":1234567,"orderId":"6c28a47d-4502-4111","productId":"ZFDAA-1221","customerNumber":"123645","variableReference":"John Doe","comment1":"Additional comments about the transaction","comment2":"Additional comments about the transaction","merchantCustomerIdenti...}'
Request payload example
{ "currency": "EUR", "type": "OTHER", "icanTo": 42, "amount": 1000, "myRef": "Fees", "description": "Gym Fees Oct 2020", "maxNumberPayments": 1, "expiry": "2020-10-22T07:48:56.460Z", "returnUrl": "https://example.com/callback", "orderDetails": { "merchantNumber": 1234567, "orderId": "6c28a47d-4502-4111", "productId": "ZFDAA-1221", "customerNumber": "123645", "variableReference": "John Doe", "comment1": "Additional comments about the transaction", "comment2": "Additional comments about the transaction", "merchantCustomerIdentification": "08303863544", "deliveryAddressLine1": "12 The Street", "deliveryAddressLine2": "The Way", "deliveryCity": "London", "deliveryPostCode": "EC15155", "deliveryCountry": "GB" }, "collectFields": "ADDRESS|REFERENCE|COMMENT1", "mandatoryFields": "ADDRESS|REFERENCE|COMMENT1", "additionalFields": "ORDER_ID|PRODUCT_ID|CUSTOMER_ID|CUSTOMER_NUMBER|COMMENT2" }
Response example (200)
{ "code": "1234abcd", "type": "OTHER" }

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 object

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

    • total integer

      The total number of ASPSPs in the list.

    • aspsps array[object]
      • aspspUuid string

        The UUID associated with the ASPSP / bank.

      • alias string

        The name of the ASPSP / bank.

      • logoUrl string

        A link to the ASPSP / bank's logo in SVG format.

      • country object
        • code string

          The 2-letter code for the country - e.g. IE, GP...

        • description string

          The name of the country

      • currency object
        • code string

          The three letter code for the currency - either EUR or GBP.

          Values are EUR and GBP.

        • description string

          The name of the currency

      • dateCreated string(date-time)

        The date the ASPSP / bank was created.

      • lastUpdated string(date-time)

        The date the ASPSP / bank was last updated.

Definition
GET https://api-preprod.fire.com/business/v1/aspsps
cURL example
curl \ -X GET https://api-preprod.fire.com/business/v1/aspsps
Response example (200)
{ "total": 10, "aspsps": [ { "aspspUuid": "4ADFB67A-0F5B-4A9A-9D74-34437250045C", "alias": "Demo Bank", "logoUrl": "https://assets.fire.com/pisp/demo.svg", "country": { "code": "GB", "description": "United Kingdom" }, "currency": { "code": "EUR", "description": "Euro" }, "dateCreated": "2019-08-22T07:48:56.460Z", "lastUpdated": "2019-08-22T07:48:56.460Z" } ] }

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
  • paymentUuid Required / string
Body
  • currency string

    Must correspond to the currency of the original payment

    Values are EUR and GBP.

  • amount integer(int64)

    The amount to refund. Must be within a certain percentage of the original payment.

  • myRef string

    An internal description of the refund request.

  • description string

    A public facing description of the refund request.

  • orderDetails object
    • merchantNumber string

      Your Merchant Number (if applicable).

  • reason string

    A reason for the refund.

Responses
  • • 200 object

    Refund Request successful

    • status string

      Status of the refund request.

      Values are REQUEST_ACCEPTED, REQUEST_REJECTED, REJECTED, and RECEIVED.

    • refundRequestUuid string

      The unique id for the refund request

    • paymentUuid string

      The unique id for the original payment.

  • • 405 object

    Error Method not Allowed

    • errors array[object]
      • code integer(int64)

        Error Code

      • message string

        The error message

Definition
POST https://api-preprod.fire.com/business/v1/payments/{paymentUuid}/bankpayrefund
cURL example
curl \ -X POST https://api-preprod.fire.com/business/v1/payments/4ADFB67A-0F5B-4A9A-9D74-34437250045C/bankpayrefund \ -H "Content-Type: application/json" \ -d '{"currency":"EUR","amount":1000,"myRef":"Fees Refunded","description":"Gym Fees Refunded Oct 2020","orderDetails":{"merchantNumber":1234567},"reason":"Gym Closed for repairs."}'
Request payload example
{ "currency": "EUR", "amount": 1000, "myRef": "Fees Refunded", "description": "Gym Fees Refunded Oct 2020", "orderDetails": { "merchantNumber": 1234567 }, "reason": "Gym Closed for repairs." }
Response example (200)
{ "status": "REQUEST_ACCEPTED", "refundRequestUuid": "4ADFB67A-0F5B-4A9A-9D74-34437250045C", "paymentUuid": "4ADFB67A-0F5B-4A9A-9D74-34437250045C" }
Response example (405)
{ "errors": [ { "code": 50051, "message": "Sorry, we are unable to proceed with your request." } ] }

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
  • paymentUuid Required / string
Responses
  • • 200 object

    The Payment Request details object

    • paymentRequestCode string

      The code that was returned when you created the payment request.

    • paymentUuid string

      A unique id for the transaction.

    • transactionType string

      The type of payment request payment

      Values are REFUND_REQUEST and PAYMENT.

    • status string

      The status of the transaction

      Values are AWAITING_AUTHORISATION, AUTHORISED, AWAITING_MULTI_AUTHORISATION, NOT_AUTHORISED, PAID, REJECTED, ACCEPTED, and RECEIVED.

    • currency object
      • code string

        The three letter code for the currency - either EUR or GBP.

        Values are EUR and GBP.

      • description string

        The name of the currency

    • type string

      The type of Fire Open Payment that was created

      Values are OTHER.

    • icanTo integer(int64)

      The ican of the account to collect the funds into. Must be one of your fire.com Accounts.

    • amount integer(int64)

      The requested amount to pay. Note the last two digits represent pennies/cents, (e.g., £1.00 = 100).

    • myRef string

      An internal description of the request.

    • description string

      A public facing description of the request. This will be shown to the user when they tap or scan the request.

    • maxNumberPayments integer

      The max number of people who can pay this request. Must be set to 1 for the ECOMMERCE_GOODS and ECOMMERCE_SERVICES types.

    • expiry string(date-time)

      This is the expiry of the payment request. After this time, the payment cannot be paid.

    • returnUrl string

      The merchant return URL where the customer will be re-directed to with the result of the transaction.

    • orderDetails object
      • merchantNumber string

        Your Merchant Number (if applicable).

      • orderId string

        Use this field to store the order id for the transaction. The Order Id cannot be set unless the maxNumberPayments is 1.

      • productId string

        Use this field to store a product id for the transaction (for example).

      • customerNumber string

        Use this field to store a customer number for the transaction (for example).

      • variableReference string

        Use this field to store any other reference for the transaction (for example, a phone number).

      • comment1 string

        This is your own comment for the transaction.

      • comment2 string

        This is your own comment for the transaction.

      • merchantCustomerIdentification string

        This is a reference you use to uniquely identify each of your customers.

      • deliveryAddressLine1 string

        The first line of the delivery address.

      • deliveryAddressLine2 string

        The second line of the delivery address.

      • deliveryCity string

        Delivery address city

      • deliveryPostCode string

        Delivery address post code

      • deliveryCountry string

        2-digit code for the country

    • collectFields string

      For the hosted option, the payer will be asked to fill in these fields but they will not be mandatory. You can choose to collect any of the payer's ADDRESS, REFERENCE and/or COMMENT1. If you choose to collect these fields from the payer, you cannot set 'delivery’, 'variableReference’ or 'comment1’ fields respectively.

    • mandatoryFields string

      For the hosted option, these fields will be madatory for the payer to fill in on the hosted payment page. You can choose to collect any the payer's ADDRESS, REFERENCE and/or COMMENT1. If you choose to collect these fields from the payer, you cannot set 'delivery’, 'variableReference’ or 'comment1’ fields respectively.

    • additionalFields string

      These fields will be dispalyed to the payer when using the hosted option. You can choose to display any of ORDER_ID, PRODUCT_ID, CUSTOMER_ID, CUSTOMER_NUMBER and COMMENT2 to the payer.

Definition
GET https://api-preprod.fire.com/business/v1/payments/{paymentUuid}
cURL example
curl \ -X GET https://api-preprod.fire.com/business/v1/payments/4ADFB67A-0F5B-4A9A-9D74-34437250045C
Response example (200)
{ "paymentRequestCode": "1234abcd", "paymentUuid": "4ADFB67A-0F5B-4A9A-9D74-34437250045C", "transactionType": "REFUND_REQUEST", "status": "AWAITING_AUTHORISATION", "currency": { "code": "EUR", "description": "Euro" }, "type": "OTHER", "icanTo": 42, "amount": 1000, "myRef": "Fees", "description": "Gym Fees Oct 2020", "maxNumberPayments": 1, "expiry": "2020-10-22T07:48:56.460Z", "returnUrl": "https://example.com/callback", "orderDetails": { "merchantNumber": 1234567, "orderId": "6c28a47d-4502-4111", "productId": "ZFDAA-1221", "customerNumber": "123645", "variableReference": "John Doe", "comment1": "Additional comments about the transaction", "comment2": "Additional comments about the transaction", "merchantCustomerIdentification": "08303863544", "deliveryAddressLine1": "12 The Street", "deliveryAddressLine2": "The Way", "deliveryCity": "London", "deliveryPostCode": "EC15155", "deliveryCountry": "GB" }, "collectFields": "ADDRESS|REFERENCE|COMMENT1", "mandatoryFields": "ADDRESS|REFERENCE|COMMENT1", "additionalFields": "ORDER_ID|PRODUCT_ID|CUSTOMER_ID|CUSTOMER_NUMBER|COMMENT2" }

Api

Manage your API Applications and Webhooks

Create a new API Application

Create a new API Application with specified permissions

Body
  • ican integer(int64)

    The ICAN of one of your Fire accounts. Restrict this API Application to a certan account.

  • enabled boolean

    Whether or not this API Application can be used

  • expiry string(date-time)

    The date that this API Application can no longer be used.

  • applicationName string

    A name for the API Application to help you identify it

  • numberOfPaymentApprovalsRequired integer

    Number of approvals required to process a payment in a batch

  • numberOfPayeeApprovalsRequired integer

    Number of approvals required to create a payee in a batch

  • permissions array[string]

    The list of permissions required

Responses
  • • 200 object

    API Application created successfully

    • applicationId integer(int64)

      The ID of the API Application

    • ican integer(int64)

      The ICAN of one of your Fire accounts. Restrict this API Application to a certan account.

    • enabled boolean

      Whether or not this API Application can be used

    • expiry string(date-time)

      The date that this API Application can no longer be used.

    • numberOfPaymentApprovalsRequired integer

      Number of approvals required to process a payment in a batch

    • numberOfPayeeApprovalsRequired integer

      Number of approvals required to create a payee in a batch

    • clientId string

      The Client ID of the new API Application

    • clientKey string

      The Client Key of the new API Application

    • refreshToken string

      The Refresh Token of the new API Application

Definition
POST https://api-preprod.fire.com/business/v1/apps
cURL example
curl \ -X POST https://api-preprod.fire.com/business/v1/apps \ -H "Content-Type: application/json" \ -d '{"ican":42,"enabled":true,"expiry":"2019-08-22T07:48:56.460Z","applicationName":"Batch Processing API","numberOfPaymentApprovalsRequired":1,"numberOfPayeeApprovalsRequired":1,"permissions":["PERM_BUSINESS_POST_PAYMENT_REQUEST","PERM_BUSINESS_GET_ASPSPS"]}'
Request payload example
{ "ican": 42, "enabled": true, "expiry": "2019-08-22T07:48:56.460Z", "applicationName": "Batch Processing API", "numberOfPaymentApprovalsRequired": 1, "numberOfPayeeApprovalsRequired": 1, "permissions": [ "PERM_BUSINESS_POST_PAYMENT_REQUEST", "PERM_BUSINESS_GET_ASPSPS" ] }
Response example (200)
{ "applicationId": 45345, "ican": 42, "enabled": true, "expiry": "2019-08-22T07:48:56.460Z", "numberOfPaymentApprovalsRequired": 1, "numberOfPayeeApprovalsRequired": 1, "clientId": "4ADFB67A-0F5B-4A9A-9D74-34437250045C", "clientKey": "4ADFB67A-0F5B-4A9A-9D74-34437250045C", "refreshToken": "4ADFB67A-0F5B-4A9A-9D74-34437250045C" }

Transactions

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 object

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

    • txnId integer(int64)

      The id of this side of the transaction (each transaction has two sides - a to and a from). This is used to get the details of the transaction.

    • refId integer(int64)

      The id of the transaction.

    • ican integer(int64)

      identifier for the fire.com account (assigned by fire.com) This field is only used in the condensed version.

    • currency object
      • code string

        The three letter code for the currency - either EUR or GBP.

        Values are EUR and GBP.

      • description string

        The name of the currency

    • amountBeforeCharges integer(int64)

      Amount of the transaction before the fees and taxes were applied.

    • feeAmount integer(int64)

      The amount of the fee, if any.

    • taxAmount integer(int64)

      The amount of the tax, if any (e.g. Stamp duty for ATM transactions)

    • amountAfterCharges integer(int64)

      Net amount lodged or taken from the account after fees and charges were applied.

    • balance integer(int64)

      the balance of the account (in minor currency units - pence, cent etc. 434050 == 4,340.50 GBP for a GBP account).

    • myRef string

      The comment/reference on the transaction

    • paymentRequestPublicCode string

      The code that was returned when you created the payment request.

    • date string(date-time)

      Date of the transaction

    • card object
      • cardId number(int64)
      • provider string
      • alias string
      • maskedPan string
      • embossCardName string
      • embossBusinessName string
      • expiryDate string(date-time)
    • type string

      Retrieve a filtered list of transactions against an account.

      • LODGEMENT - Bank Transfer received
      • PIS_LODGEMENT - Fire Open Payments Lodgement received
      • MANUAL_TRANSFER - Manual Transfer to
      • WITHDRAWAL - Bank Transfer sent
      • REVERSAL - Credit Reversal
      • INTERNAL_TRANSFER_TO - Internal Transfer sent (between two of my accounts of the same currency)
      • INTERNAL_TRANSFER_FROM - Internal Transfer received (between two of my accounts of the same currency)
      • WITHDRAWAL_RETURNED - Bank Transfer sent returned
      • LODGEMENT_REVERSED - Bank Transfer received returned
      • FX_INTERNAL_TRANSFER_FROM - FX Internal Transfer received (between two of my accounts of different currency)
      • FX_INTERNAL_TRANSFER_TO - FX Internal Transfer sent (between two of my accounts of different currency)
      • CARD_POS_CONTACT_DEBIT - Card used in store; read by magnetic stripe or pin
      • CARD_POS_CONTACT_CREDIT - Card used in store; read by magnetic stripe or pin
      • CARD_POS_CONTACTLESS_DEBIT - Card used in store; read by NFC
      • CARD_POS_CONTACTLESS_CREDIT - Card used in store; read by NFC
      • CARD_ECOMMERCE_DEBIT - Card used on the internet
      • CARD_ECOMMERCE_CREDIT - Card used on the internet
      • CARD_ATM_DEBIT - Card used in an ATM
      • CARD_ATM_CREDIT - Card used in an ATM
      • CARD_INTERNATIONAL_POS_CONTACT_DEBIT - Card used in store in non-processing currency; read by magnetic stripe or pin
      • CARD_INTERNATIONAL_POS_CONTACT_CREDIT - Card used in store in non-processing currency; read by magnetic stripe or pin
      • CARD_INTERNATIONAL_POS_CONTACTLESS_DEBIT - Card used in store in non-processing currency; read by NFC
      • CARD_INTERNATIONAL_POS_CONTACTLESS_CREDIT - Card used in store in non-processing currency; read by NFC
      • CARD_INTERNATIONAL_ECOMMERCE_DEBIT - Card used on the internet in non-processing currency
      • CARD_INTERNATIONAL_ECOMMERCE_CREDIT - Card used on the internet in non-processing currency
      • CARD_INTERNATIONAL_ATM_DEBIT - Card used in an ATM in non-processing currency
      • CARD_INTERNATIONAL_ATM_CREDIT - Card used in an ATM in non-processing currency
      • CARD_POS_CONTACT_DEBIT_REVERSAL - Card used in store; read by magnetic stripe or pin - reversed
      • CARD_POS_CONTACT_CREDIT_REVERSAL - Card used in store; read by magnetic stripe or pin - reversed
      • CARD_POS_CONTACTLESS_DEBIT_REVERSAL - Card used in store; read by NFC - reversed
      • CARD_POS_CONTACTLESS_CREDIT_REVERSAL - Card used in store; read by NFC - reversed
      • CARD_ECOMMERCE_DEBIT_REVERSAL - Card used on the internet - reversed
      • CARD_ECOMMERCE_CREDIT_REVERSAL - Card used on the internet - reversed
      • CARD_ATM_DEBIT_REVERSAL - Card used in an ATM - reversed
      • CARD_ATM_CREDIT_REVERSAL - Card used in an ATM - reversed
      • CARD_INTERNATIONAL_POS_CONTACT_DEBIT_REVERSAL - Card used in store in non-processing currency; read by magnetic stripe or pin - reversed
      • CARD_INTERNATIONAL_POS_CONTACT_CREDIT_REVERSAL - Card used in store in non-processing currency; read by magnetic stripe or pin - reversed
      • CARD_INTERNATIONAL_POS_CONTACTLESS_DEBIT_REVERSAL - Card used in store in non-processing currency; read by NFC - reversed
      • CARD_INTERNATIONAL_POS_CONTACTLESS_CREDIT_REVERSAL - One or more of the transaction types above. This field can be repeated multiple times to allow for multiple transaction types.
      • CARD_INTERNATIONAL_ECOMMERCE_DEBIT_REVERSAL - Card used in store in non-processing currency; read by NFC - reversed
      • CARD_INTERNATIONAL_ECOMMERCE_CREDIT_REVERSAL - Card used in store in non-processing currency; read by NFC - reversed
      • CARD_INTERNATIONAL_ATM_DEBIT_REVERSAL - Card used on the internet in non-processing currency - reversed
      • CARD_INTERNATIONAL_ATM_CREDIT_REVERSAL - Card used on the internet in non-processing currency - reversed
    • dateAcknowledged string(date-time)
    • fxTradeDetails object
      • buyCurrency string

        currency which is being bought

      • sellCurrency string

        currency which is being sold

      • fixedSide string

        type of trade

      • buyAmount integer(int64)

        amount of buyCurrency being bought

      • sellAmount integer(int64)

        amount of sellCurrency being sold

      • rate4d integer(int64)

        exchange rate

    • relatedParty
Definition
GET https://api-preprod.fire.com/business/v1/accounts/{ican}/transactions
cURL example
curl \ -X GET https://api-preprod.fire.com/business/v1/accounts/{ican}/transactions
Response example (200)
{ "txnId": 30157, "refId": 26774, "ican": 1951, "currency": { "code": "EUR", "description": "Euro" }, "amountBeforeCharges": 5000, "feeAmount": 0, "taxAmount": 0, "amountAfterCharges": 5000, "balance": 8500, "myRef": "Transfer to main account", "paymentRequestPublicCode": "1abcdefg", "date": "2021-04-13 11:06:32 UTC", "card": { "cardId": 42.0, "provider": "string", "alias": "string", "maskedPan": "string", "embossCardName": "string", "embossBusinessName": "string", "expiryDate": "2021-05-04T09:42:00+00:00" }, "type": "WITHDRAWAL", "dateAcknowledged": "2021-04-13 11:06:32 UTC", "fxTradeDetails": { "buyCurrency": "GBP", "sellCurrency": "EUR", "fixedSide": "SELL", "buyAmount": 359, "sellAmount": 500, "rate4d": 7180 }, "relatedParty": "string" }

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
  • dateRangeFrom Required / number(int64)
  • dateRangeTo Required / number(int64)
  • searchKeyword Required / string
  • transactionTypes Required / array[]
Responses
  • • 200 object

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

    • txnId integer(int64)

      The id of this side of the transaction (each transaction has two sides - a to and a from). This is used to get the details of the transaction.

    • refId integer(int64)

      The id of the transaction.

    • ican integer(int64)

      identifier for the fire.com account (assigned by fire.com) This field is only used in the condensed version.

    • currency object
      • code string

        The three letter code for the currency - either EUR or GBP.

        Values are EUR and GBP.

      • description string

        The name of the currency

    • amountBeforeCharges integer(int64)

      Amount of the transaction before the fees and taxes were applied.

    • feeAmount integer(int64)

      The amount of the fee, if any.

    • taxAmount integer(int64)

      The amount of the tax, if any (e.g. Stamp duty for ATM transactions)

    • amountAfterCharges integer(int64)

      Net amount lodged or taken from the account after fees and charges were applied.

    • balance integer(int64)

      the balance of the account (in minor currency units - pence, cent etc. 434050 == 4,340.50 GBP for a GBP account).

    • myRef string

      The comment/reference on the transaction

    • paymentRequestPublicCode string

      The code that was returned when you created the payment request.

    • date string(date-time)

      Date of the transaction

    • card object
      • cardId number(int64)
      • provider string
      • alias string
      • maskedPan string
      • embossCardName string
      • embossBusinessName string
      • expiryDate string(date-time)
    • type string

      Retrieve a filtered list of transactions against an account.

      • LODGEMENT - Bank Transfer received
      • PIS_LODGEMENT - Fire Open Payments Lodgement received
      • MANUAL_TRANSFER - Manual Transfer to
      • WITHDRAWAL - Bank Transfer sent
      • REVERSAL - Credit Reversal
      • INTERNAL_TRANSFER_TO - Internal Transfer sent (between two of my accounts of the same currency)
      • INTERNAL_TRANSFER_FROM - Internal Transfer received (between two of my accounts of the same currency)
      • WITHDRAWAL_RETURNED - Bank Transfer sent returned
      • LODGEMENT_REVERSED - Bank Transfer received returned
      • FX_INTERNAL_TRANSFER_FROM - FX Internal Transfer received (between two of my accounts of different currency)
      • FX_INTERNAL_TRANSFER_TO - FX Internal Transfer sent (between two of my accounts of different currency)
      • CARD_POS_CONTACT_DEBIT - Card used in store; read by magnetic stripe or pin
      • CARD_POS_CONTACT_CREDIT - Card used in store; read by magnetic stripe or pin
      • CARD_POS_CONTACTLESS_DEBIT - Card used in store; read by NFC
      • CARD_POS_CONTACTLESS_CREDIT - Card used in store; read by NFC
      • CARD_ECOMMERCE_DEBIT - Card used on the internet
      • CARD_ECOMMERCE_CREDIT - Card used on the internet
      • CARD_ATM_DEBIT - Card used in an ATM
      • CARD_ATM_CREDIT - Card used in an ATM
      • CARD_INTERNATIONAL_POS_CONTACT_DEBIT - Card used in store in non-processing currency; read by magnetic stripe or pin
      • CARD_INTERNATIONAL_POS_CONTACT_CREDIT - Card used in store in non-processing currency; read by magnetic stripe or pin
      • CARD_INTERNATIONAL_POS_CONTACTLESS_DEBIT - Card used in store in non-processing currency; read by NFC
      • CARD_INTERNATIONAL_POS_CONTACTLESS_CREDIT - Card used in store in non-processing currency; read by NFC
      • CARD_INTERNATIONAL_ECOMMERCE_DEBIT - Card used on the internet in non-processing currency
      • CARD_INTERNATIONAL_ECOMMERCE_CREDIT - Card used on the internet in non-processing currency
      • CARD_INTERNATIONAL_ATM_DEBIT - Card used in an ATM in non-processing currency
      • CARD_INTERNATIONAL_ATM_CREDIT - Card used in an ATM in non-processing currency
      • CARD_POS_CONTACT_DEBIT_REVERSAL - Card used in store; read by magnetic stripe or pin - reversed
      • CARD_POS_CONTACT_CREDIT_REVERSAL - Card used in store; read by magnetic stripe or pin - reversed
      • CARD_POS_CONTACTLESS_DEBIT_REVERSAL - Card used in store; read by NFC - reversed
      • CARD_POS_CONTACTLESS_CREDIT_REVERSAL - Card used in store; read by NFC - reversed
      • CARD_ECOMMERCE_DEBIT_REVERSAL - Card used on the internet - reversed
      • CARD_ECOMMERCE_CREDIT_REVERSAL - Card used on the internet - reversed
      • CARD_ATM_DEBIT_REVERSAL - Card used in an ATM - reversed
      • CARD_ATM_CREDIT_REVERSAL - Card used in an ATM - reversed
      • CARD_INTERNATIONAL_POS_CONTACT_DEBIT_REVERSAL - Card used in store in non-processing currency; read by magnetic stripe or pin - reversed
      • CARD_INTERNATIONAL_POS_CONTACT_CREDIT_REVERSAL - Card used in store in non-processing currency; read by magnetic stripe or pin - reversed
      • CARD_INTERNATIONAL_POS_CONTACTLESS_DEBIT_REVERSAL - Card used in store in non-processing currency; read by NFC - reversed
      • CARD_INTERNATIONAL_POS_CONTACTLESS_CREDIT_REVERSAL - One or more of the transaction types above. This field can be repeated multiple times to allow for multiple transaction types.
      • CARD_INTERNATIONAL_ECOMMERCE_DEBIT_REVERSAL - Card used in store in non-processing currency; read by NFC - reversed
      • CARD_INTERNATIONAL_ECOMMERCE_CREDIT_REVERSAL - Card used in store in non-processing currency; read by NFC - reversed
      • CARD_INTERNATIONAL_ATM_DEBIT_REVERSAL - Card used on the internet in non-processing currency - reversed
      • CARD_INTERNATIONAL_ATM_CREDIT_REVERSAL - Card used on the internet in non-processing currency - reversed
    • dateAcknowledged string(date-time)
    • fxTradeDetails object
      • buyCurrency string

        currency which is being bought

      • sellCurrency string

        currency which is being sold

      • fixedSide string

        type of trade

      • buyAmount integer(int64)

        amount of buyCurrency being bought

      • sellAmount integer(int64)

        amount of sellCurrency being sold

      • rate4d integer(int64)

        exchange rate

    • relatedParty
Definition
GET https://api-preprod.fire.com/business/v1/accounts/{ican}/transactions/filter
cURL example
curl \ -X GET https://api-preprod.fire.com/business/v1/accounts/{ican}/transactions/filter?dateRangeFrom=42.0&dateRangeTo=42.0&searchKeyword=string&transactionTypes=string
Response example (200)
{ "txnId": 30157, "refId": 26774, "ican": 1951, "currency": { "code": "EUR", "description": "Euro" }, "amountBeforeCharges": 5000, "feeAmount": 0, "taxAmount": 0, "amountAfterCharges": 5000, "balance": 8500, "myRef": "Transfer to main account", "paymentRequestPublicCode": "1abcdefg", "date": "2021-04-13 11:06:32 UTC", "card": { "cardId": 42.0, "provider": "string", "alias": "string", "maskedPan": "string", "embossCardName": "string", "embossBusinessName": "string", "expiryDate": "2021-05-04T09:42:00+00:00" }, "type": "WITHDRAWAL", "dateAcknowledged": "2021-04-13 11:06:32 UTC", "fxTradeDetails": { "buyCurrency": "GBP", "sellCurrency": "EUR", "fixedSide": "SELL", "buyAmount": 359, "sellAmount": 500, "rate4d": 7180 }, "relatedParty": "string" }

Direct debits

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 object

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

    • total integer(int64)

      Number of direct debits found

    • directdebits array[object]
      • directDebitUuid string

        The UUID for the direct debit payment

      • currency object
        • code string

          The three letter code for the currency - either EUR or GBP.

          Values are EUR and GBP.

        • description string

          The name of the currency

      • status string

        The statuses of the direct debit payments associated with the mandate.

        • 'RECIEVED' - Direct Debit has been recieved
        • 'REJECT_REQUESTED' - The direct debit has a rejected request associated with it
        • 'REJECT_READY_FOR_PROCESSING'
        • 'REJECT_RECORD_IN_PROGRESS'
        • 'REJECT_RECORDED'
        • 'REJECT_FILE_CREATED'
        • 'REJECT_FILE_SENT'
        • 'COLLECTED' - Direct debit collected
        • 'REFUND_REQUESTED' - Refund requested on direct debit
        • 'REFUND_RECORD_IN_PROGRESS' - Refund in progress on direct debit
        • 'REFUND_RECORDED'
        • 'REFUND_FILE_CREATED'
        • 'REFUND_FILE_SENT'

        Values are RECIEVED, REJECT_REQUESTED, REJECT_READY_FOR_PROCESSING, REJECT_RECORD_IN_PROGRESS, REJECT_RECORDED, REJECT_FILE_CREATED, REJECT_FILE_SENT, COLLECTED, REFUND_REQUESTED, REFUND_RECORD_IN_PROGRESS, REFUND_RECORDED, REFUND_FILE_CREATED, and REFUND_FILE_SENT.

      • type string

        The type of the direct debit.

        Values are FIRST_COLLECTION, ONGOING_COLLECTION, REPRESENTED_COLLECTION, and FINAL_COLLECTION.

      • mandateUUid string

        The UUID for the mandate

      • originatorReference string

        Set by party who sets up the direct debit.

      • originatorName string

        The creator of the party who sets up the direct debit.

      • originatorAlias string

        The Alias of the party who sets up the direct debit.

      • directDebitReference string

        The direct debit reference.

      • targetIcan integer(int64)

        The ican of your fire account that the money was taken from

      • targetPayeeId integer(int64)

        The payee that was created when the DD was processed

      • isDDIC boolean

        DDIC is a Direct Debit Indemnity Claim (i.e.a refund). If if the DD is requested to be refunded it is marked isDDIC true.

      • amount integer(int64)

        Value of the payment

      • schemeRejectReason string

        Reason why rejected

      • schemeRejectReasonCode string

        The reject code returned by the bank indicating an issue with the direct debit. Each ARRUD code represents a rejection reason.

        Values are 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, and B.

      • lastUpdated string(date-time)

        Date the direct debit was last updated. Milliseconds since the epoch (1970).

      • dateCreated string(date-time)

        Date the direct debit was created. Milliseconds since the epoch (1970).

Definition
GET https://api-preprod.fire.com/business/v1/directdebits
cURL example
curl \ -X GET https://api-preprod.fire.com/business/v1/directdebits?mandateUuid=1A07774B-1461-4595-BC4B-423B739712AF
Response example (200)
{ "total": 1, "directdebits": [ { "directDebitUuid": "42de0705-e3f1-44fa-8c41-79973eb80eb2", "currency": { "code": "EUR", "description": "Euro" }, "status": "RECIEVED", "type": "FIRST_COLLECTION", "mandateUUid": "f171b143-e3eb-47de-85a6-1c1f1108c701", "originatorReference": "VODA-123456", "originatorName": "Vodafone PLC", "originatorAlias": "Three", "directDebitReference": "VODA-ABC453-1", "targetIcan": 42, "targetPayeeId": 12, "isDDIC": true, "amount": 100, "schemeRejectReason": "eg. Instruction cancelled by payer", "schemeRejectReasonCode": "for BACS (ARUDD) 0|1|2|3|5|6|7|8|9|A|B", "lastUpdated": "2016-12-15T22:56:05.937Z", "dateCreated": "2016-12-15T22:56:05.937Z" } ] }

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
  • directDebitUuid Required / string
Responses
  • • 200 object

    Retrieve all details of a single direct debit collection/payment

    • directDebitUuid string

      The UUID for the direct debit payment

    • currency object
      • code string

        The three letter code for the currency - either EUR or GBP.

        Values are EUR and GBP.

      • description string

        The name of the currency

    • status string

      The statuses of the direct debit payments associated with the mandate.

      • 'RECIEVED' - Direct Debit has been recieved
      • 'REJECT_REQUESTED' - The direct debit has a rejected request associated with it
      • 'REJECT_READY_FOR_PROCESSING'
      • 'REJECT_RECORD_IN_PROGRESS'
      • 'REJECT_RECORDED'
      • 'REJECT_FILE_CREATED'
      • 'REJECT_FILE_SENT'
      • 'COLLECTED' - Direct debit collected
      • 'REFUND_REQUESTED' - Refund requested on direct debit
      • 'REFUND_RECORD_IN_PROGRESS' - Refund in progress on direct debit
      • 'REFUND_RECORDED'
      • 'REFUND_FILE_CREATED'
      • 'REFUND_FILE_SENT'

      Values are RECIEVED, REJECT_REQUESTED, REJECT_READY_FOR_PROCESSING, REJECT_RECORD_IN_PROGRESS, REJECT_RECORDED, REJECT_FILE_CREATED, REJECT_FILE_SENT, COLLECTED, REFUND_REQUESTED, REFUND_RECORD_IN_PROGRESS, REFUND_RECORDED, REFUND_FILE_CREATED, and REFUND_FILE_SENT.

    • type string

      The type of the direct debit.

      Values are FIRST_COLLECTION, ONGOING_COLLECTION, REPRESENTED_COLLECTION, and FINAL_COLLECTION.

    • mandateUUid string

      The UUID for the mandate

    • originatorReference string

      Set by party who sets up the direct debit.

    • originatorName string

      The creator of the party who sets up the direct debit.

    • originatorAlias string

      The Alias of the party who sets up the direct debit.

    • directDebitReference string

      The direct debit reference.

    • targetIcan integer(int64)

      The ican of your fire account that the money was taken from

    • targetPayeeId integer(int64)

      The payee that was created when the DD was processed

    • isDDIC boolean

      DDIC is a Direct Debit Indemnity Claim (i.e.a refund). If if the DD is requested to be refunded it is marked isDDIC true.

    • amount integer(int64)

      Value of the payment

    • schemeRejectReason string

      Reason why rejected

    • schemeRejectReasonCode string

      The reject code returned by the bank indicating an issue with the direct debit. Each ARRUD code represents a rejection reason.

      Values are 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, and B.

    • lastUpdated string(date-time)

      Date the direct debit was last updated. Milliseconds since the epoch (1970).

    • dateCreated string(date-time)

      Date the direct debit was created. Milliseconds since the epoch (1970).

Definition
GET https://api-preprod.fire.com/business/v1/directdebits/{directDebitUuid}
cURL example
curl \ -X GET https://api-preprod.fire.com/business/v1/directdebits/4ADFB67A-0F5B-4A9A-9D74-34437250045C
Response example (200)
{ "directDebitUuid": "42de0705-e3f1-44fa-8c41-79973eb80eb2", "currency": { "code": "EUR", "description": "Euro" }, "status": "RECIEVED", "type": "FIRST_COLLECTION", "mandateUUid": "f171b143-e3eb-47de-85a6-1c1f1108c701", "originatorReference": "VODA-123456", "originatorName": "Vodafone PLC", "originatorAlias": "Three", "directDebitReference": "VODA-ABC453-1", "targetIcan": 42, "targetPayeeId": 12, "isDDIC": true, "amount": 100, "schemeRejectReason": "eg. Instruction cancelled by payer", "schemeRejectReasonCode": "for BACS (ARUDD) 0|1|2|3|5|6|7|8|9|A|B", "lastUpdated": "2016-12-15T22:56:05.937Z", "dateCreated": "2016-12-15T22:56:05.937Z" }

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
  • directDebitUuid Required / string
Responses
  • • 204

    204 no content

Definition
POST https://api-preprod.fire.com/business/v1/directdebits/{directDebitUuid}/reject
cURL example
curl \ -X POST https://api-preprod.fire.com/business/v1/directdebits/4ADFB67A-0F5B-4A9A-9D74-34437250045C/reject
Response example (204)
No content

List all direct debit mandates

The permision needed to access this endpoint is PERM_BUSINESS_GET_MANDATES

Responses
  • • 200 object

    List all direct debit mandates.

    • total integer(int64)

      Number of direct debits found

    • mandates array[object]
      • mandateUuid string

        The UUID for the mandate

      • currency object
        • code string

          The three letter code for the currency - either EUR or GBP.

          Values are EUR and GBP.

        • description string

          The name of the currency

      • status string

        The status of the mandate.

        • 'CREATED'
        • 'LIVE'
        • 'REJECT_REQUESTED'
        • 'REJECT_RECORD_IN_PROGRESS'
        • 'REJECT_RECORDED'
        • 'REJECT_FILE_CREATED'
        • 'REJECT_FILE_SENT'
        • 'CANCEL_REQUESTED'
        • 'CANCEL_RECORD_IN_PROGRESS'
        • 'CANCEL_RECORDED'
        • 'CANCEL_FILE_CREATED'
        • 'CANCEL_FILE_SENT'
        • 'COMPLETE'
        • 'DORMANT'

        Values are CREATED, LIVE, REJECT_REQUESTED, REJECT_RECORD_IN_PROGRESS, REJECT_RECORDED, REJECT_FILE_CREATED, REJECT_FILE_SENT, CANCEL_REQUESTED, CANCEL_RECORD_IN_PROGRESS, CANCEL_RECORDED, CANCEL_FILE_CREATED, CANCEL_FILE_SENT, COMPLETE, and DORMANT.

      • originatorReference string

        Set by party who sets up the direct debit.

      • originatorName string

        The creator of the party who sets up the direct debit.

      • originatorAlias string

        The name of the alias

      • originatorLogoUrlSmall string

        Logo url from party who sets up the direct debit.

      • originatorLogoUrlLarge string

        Logo url from party who sets up the direct debit.

      • mandateReference string

        the reference of the mandate

      • alias string

        The name of the alias

      • targetIcan integer(int64)

        Identifier for the fire.com account (assigned by fire.com)

      • numberOfDirectDebitCollected integer(int64)

        The number of direct debits collected

      • valueOfDirectDebitCollected integer(int64)

        The value of direct debits collected

      • latestDirectDebitAmount integer(int64)

        The value of largest direct debit collected

      • latestDirectDebitDate string(date-time)

        The date of latest direct debit collected

      • fireRejectionReason string

        Rejection reason if transaction is rejected

        Values are ACCOUNT_DOES_NOT_ACCEPT_DIRECT_DEBITS, DDIC, ACCOUNT_NOT_FOUND, ACCOUNT_NOT_LIVE, CUSTOMER_NOT_FOUND, BUSINESS_NOT_LIVE, BUSINESS_NOT_FULL, PERSONAL_USER_NOT_LIVE, PERSONAL_USER_NOT_FULL, MANDATE_ALREADY_EXISTS, MANDATE_WITH_DIFERENT_ACCOUNT, NULL_MANDATE_REFERENCE, INVALID_ACCOUNT_CURRENCY, INVALID_MANDATE_REFERENCE, REQUESTED_BY_CUSTOMER_VIA_SUPPORT, CUSTOMER_ACCOUNT_CLOSED, CUSTOMER_DECEASED, ACCOUNT_TRANSFERRED, MANDATE_NOT_FOUND, ACCOUNT_TRANSFERRED_TO_DIFFERENT_ACCOUNT, INVALID_ACCOUNT_TYPE, MANDATE_EXPIRED, MANDATE_CANCELLED, and REQUESTED_BY_CUSTOMER.

      • schemeCancelReason string

        Reason for cancelation

      • schemeCancelReasonCode string

        The cancelation code returned by the bank indicating an issue with the direct debit. Each ARRUD code represents a rejection reason.

      • lastUpdated string(date-time)

        Date the direct debit was last updated. Milliseconds since the epoch (1970).

      • dateCreated string(date-time)

        Date the direct debit was created. Milliseconds since the epoch (1970).

      • dateCompleted string(date-time)

        Date the direct debit was completed. Milliseconds since the epoch (1970).

      • dateCancelled string(date-time)

        Date the direct debit was canceled. Milliseconds since the epoch (1970).

Definition
GET https://api-preprod.fire.com/business/v1/mandates
cURL example
curl \ -X GET https://api-preprod.fire.com/business/v1/mandates
Response example (200)
{ "total": 1, "mandates": [ { "mandateUuid": "28d627c3-1889-44c8-ae59-6f6b20239260", "currency": { "code": "EUR", "description": "Euro" }, "status": "RECIEVED", "originatorReference": "VODA-123456", "originatorName": "Vodafone PLC", "originatorAlias": "Vodaphone PLC", "originatorLogoUrlSmall": "originatorLogoSmall", "originatorLogoUrlLarge": "originatorLogoLarge", "mandateReference": "CRZ-102190123", "alias": "Vodaphone", "targetIcan": 1, "numberOfDirectDebitCollected": 2, "valueOfDirectDebitCollected": 2, "latestDirectDebitAmount": 2, "latestDirectDebitDate": "2016-12-15T22:56:05.937Z", "fireRejectionReason": "ACCOUNT_DOES_NOT_ACCEPT_DIRECT_DEBITS", "schemeCancelReason": "e.g. Instruction cancelled by payer", "schemeCancelReasonCode": "For BACS (ADDACS) - 0|1|2|3|B|C|D|E|R", "lastUpdated": "2016-12-15T22:56:05.937Z", "dateCreated": "2016-12-15T22:56:05.937Z", "dateCompleted": "2016-12-15T22:56:05.937Z", "dateCancelled": "2016-12-15T22:56:05.937Z" } ] }

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
  • mandateUuid Required / string
Responses
  • • 200 object

    Retrieve all details for a direct debit mandate.

    • mandateUuid string

      The UUID for the mandate

    • currency object
      • code string

        The three letter code for the currency - either EUR or GBP.

        Values are EUR and GBP.

      • description string

        The name of the currency

    • status string

      The status of the mandate.

      • 'CREATED'
      • 'LIVE'
      • 'REJECT_REQUESTED'
      • 'REJECT_RECORD_IN_PROGRESS'
      • 'REJECT_RECORDED'
      • 'REJECT_FILE_CREATED'
      • 'REJECT_FILE_SENT'
      • 'CANCEL_REQUESTED'
      • 'CANCEL_RECORD_IN_PROGRESS'
      • 'CANCEL_RECORDED'
      • 'CANCEL_FILE_CREATED'
      • 'CANCEL_FILE_SENT'
      • 'COMPLETE'
      • 'DORMANT'

      Values are CREATED, LIVE, REJECT_REQUESTED, REJECT_RECORD_IN_PROGRESS, REJECT_RECORDED, REJECT_FILE_CREATED, REJECT_FILE_SENT, CANCEL_REQUESTED, CANCEL_RECORD_IN_PROGRESS, CANCEL_RECORDED, CANCEL_FILE_CREATED, CANCEL_FILE_SENT, COMPLETE, and DORMANT.

    • originatorReference string

      Set by party who sets up the direct debit.

    • originatorName string

      The creator of the party who sets up the direct debit.

    • originatorAlias string

      The name of the alias

    • originatorLogoUrlSmall string

      Logo url from party who sets up the direct debit.

    • originatorLogoUrlLarge string

      Logo url from party who sets up the direct debit.

    • mandateReference string

      the reference of the mandate

    • alias string

      The name of the alias

    • targetIcan integer(int64)

      Identifier for the fire.com account (assigned by fire.com)

    • numberOfDirectDebitCollected integer(int64)

      The number of direct debits collected

    • valueOfDirectDebitCollected integer(int64)

      The value of direct debits collected

    • latestDirectDebitAmount integer(int64)

      The value of largest direct debit collected

    • latestDirectDebitDate string(date-time)

      The date of latest direct debit collected

    • fireRejectionReason string

      Rejection reason if transaction is rejected

      Values are ACCOUNT_DOES_NOT_ACCEPT_DIRECT_DEBITS, DDIC, ACCOUNT_NOT_FOUND, ACCOUNT_NOT_LIVE, CUSTOMER_NOT_FOUND, BUSINESS_NOT_LIVE, BUSINESS_NOT_FULL, PERSONAL_USER_NOT_LIVE, PERSONAL_USER_NOT_FULL, MANDATE_ALREADY_EXISTS, MANDATE_WITH_DIFERENT_ACCOUNT, NULL_MANDATE_REFERENCE, INVALID_ACCOUNT_CURRENCY, INVALID_MANDATE_REFERENCE, REQUESTED_BY_CUSTOMER_VIA_SUPPORT, CUSTOMER_ACCOUNT_CLOSED, CUSTOMER_DECEASED, ACCOUNT_TRANSFERRED, MANDATE_NOT_FOUND, ACCOUNT_TRANSFERRED_TO_DIFFERENT_ACCOUNT, INVALID_ACCOUNT_TYPE, MANDATE_EXPIRED, MANDATE_CANCELLED, and REQUESTED_BY_CUSTOMER.

    • schemeCancelReason string

      Reason for cancelation

    • schemeCancelReasonCode string

      The cancelation code returned by the bank indicating an issue with the direct debit. Each ARRUD code represents a rejection reason.

    • lastUpdated string(date-time)

      Date the direct debit was last updated. Milliseconds since the epoch (1970).

    • dateCreated string(date-time)

      Date the direct debit was created. Milliseconds since the epoch (1970).

    • dateCompleted string(date-time)

      Date the direct debit was completed. Milliseconds since the epoch (1970).

    • dateCancelled string(date-time)

      Date the direct debit was canceled. Milliseconds since the epoch (1970).

Definition
GET https://api-preprod.fire.com/business/v1/mandates/{mandateUuid}
cURL example
curl \ -X GET https://api-preprod.fire.com/business/v1/mandates/4ADFB67A-0F5B-4A9A-9D74-34437250045C
Response example (200)
{ "mandateUuid": "28d627c3-1889-44c8-ae59-6f6b20239260", "currency": { "code": "EUR", "description": "Euro" }, "status": "RECIEVED", "originatorReference": "VODA-123456", "originatorName": "Vodafone PLC", "originatorAlias": "Vodaphone PLC", "originatorLogoUrlSmall": "originatorLogoSmall", "originatorLogoUrlLarge": "originatorLogoLarge", "mandateReference": "CRZ-102190123", "alias": "Vodaphone", "targetIcan": 1, "numberOfDirectDebitCollected": 2, "valueOfDirectDebitCollected": 2, "latestDirectDebitAmount": 2, "latestDirectDebitDate": "2016-12-15T22:56:05.937Z", "fireRejectionReason": "ACCOUNT_DOES_NOT_ACCEPT_DIRECT_DEBITS", "schemeCancelReason": "e.g. Instruction cancelled by payer", "schemeCancelReasonCode": "For BACS (ADDACS) - 0|1|2|3|B|C|D|E|R", "lastUpdated": "2016-12-15T22:56:05.937Z", "dateCreated": "2016-12-15T22:56:05.937Z", "dateCompleted": "2016-12-15T22:56:05.937Z", "dateCancelled": "2016-12-15T22:56:05.937Z" }

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
  • mandateUuid Required / string
Responses
  • • 204

    204 no content

Definition
POST https://api-preprod.fire.com/business/v1/mandates/{mandateUuid}
cURL example
curl \ -X POST https://api-preprod.fire.com/business/v1/mandates/4ADFB67A-0F5B-4A9A-9D74-34437250045C
Response example (204)
No content

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
  • mandateUuid Required / string
Responses
  • • 204

    204 no content

Definition
POST https://api-preprod.fire.com/business/v1/mandates/{mandateUuid}/cancel
cURL example
curl \ -X POST https://api-preprod.fire.com/business/v1/mandates/4ADFB67A-0F5B-4A9A-9D74-34437250045C/cancel
Response example (204)
No content

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
  • mandateUuid Required / string
Responses
  • • 204

    204 no content

Definition
POST https://api-preprod.fire.com/business/v1/mandates/{mandateUuid}/activate
cURL example
curl \ -X POST https://api-preprod.fire.com/business/v1/mandates/4ADFB67A-0F5B-4A9A-9D74-34437250045C/activate
Response example (204)
No content

Payment batches

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 object

    List all batches.

    • total integer(int64)

      total number of batches returned

    • items array[object]
      • batchItemUuid string

        A UUID for this item.

      • status string

        status of the batch if internal trasnfer

        Values are SUBMITTED, REMOVED, SUCCEEDED, and FAILED.

      • result object

        The outcome of the attempted transaction.

        • code integer(int64)
        • message string
      • dateCreated string(date-time)

        The datestamp the batch was created - ISO format - e.g. 2018-04-04T00:53:21.910Z

      • lastUpdated string(date-time)

        The datestamp of the last action on this batch - ISO format - e.g. 2018-04-04T10:48:53.540Z

      • feeAmount integer(int64)

        The fee charged by fire.com for the payment. In pence or cent.

      • taxAmount integer(int64)

        Any taxes/duty collected by fire.com for this payments (e.g. stamp duty etc). In pence or cent.

      • amountAfterCharges integer(int64)

        The amount of the transfer after fees and taxes. in pence or cent.

      • icanFrom integer(int64)

        The Fire account ID of the source account.

      • icanTo integer(int64)

        The Fire account ID for the fire.com account the funds are sent to.

      • amount integer(int64)

        The amount of funds to send. In cent or pence

      • ref string

        The reference on the transaction.

      • refId integer(int64)

        The ID of the resulting payment in your account. Can be used to retrieve the transaction using the https://api.fire.com/business/v1/accounts/{accountId}/transactions/{refId} endpoint.

Definition
GET https://api-preprod.fire.com/business/v1/batches
cURL example
curl \ -X GET https://api-preprod.fire.com/business/v1/batches
Response example (200)
{ "total": 1, "items": [ { "batchItemUuid": "F2AF3F2B-4406-4199-B249-B354F2CC6019", "status": "SUCCEEDED", "result": { "code": 500001, "message": "SUCCESS" }, "dateCreated": "2021-04-04T10:48:53.540Z", "lastUpdated": "2021-04-04T10:48:53.540Z", "feeAmount": 0, "taxAmount": 0, "amountAfterCharges": 10000, "icanFrom": 2150, "icanTo": 1002, "amount": 10000, "ref": "Testing a transfer via batch", "refId": 123782 } ] }

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.

Definition
PUT https://api-preprod.fire.com/business/v1/batches
cURL example
curl \ -X PUT https://api-preprod.fire.com/business/v1/batches
Response example (204)
No content

Create a new bath of payments

This is the first step in creating a batch payment.

Body
  • type string

    The type of the batch - can be one of the listed 3

    Values are BANK_TRANSFER and INTERNAL_TRANSFER.

  • currency string

    GBP or EUR

  • batchName string

    An optional name you give to the batch at creation time.

  • jobNumber string

    An optional job number you can give to the batch to help link it to your own system.

  • callBackUrl string

    An optional POST URL that all events for this batch will be sent to.

Responses
  • • 200 object

    Batch created successfully

    • batchUuid string

      A UUID for this item.

Definition
POST https://api-preprod.fire.com/business/v1/batches
cURL example
curl \ -X POST https://api-preprod.fire.com/business/v1/batches \ -H "Content-Type: application/json" \ -d '{"type":"BANK_TRANSFER","currency":"EUR","batchName":"January 2018 Payroll","jobNumber":"2022-01-PR","callBackUrl":"https://my.webserver.com/cb/payroll"}'
Request payload example
{ "type": "BANK_TRANSFER", "currency": "EUR", "batchName": "January 2018 Payroll", "jobNumber": "2022-01-PR", "callBackUrl": "https://my.webserver.com/cb/payroll" }
Response example (200)
{ "batchUuid": "F2AF3F2B-4406-4199-B249-B354F2CC6019" }

List items in a Batch

Returns a paginated list of items in the specified batch.

Path parameters
  • batchUuid Required / string
Query parameters
  • offset integer(int64)
  • limit integer(int64)
Responses
  • • 200 object

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

    • total integer(int64)

      total number of batches returned

    • items array[object]
      • batchItemUuid string

        A UUID for this item.

      • status string

        status of the batch if internal trasnfer

        Values are SUBMITTED, REMOVED, SUCCEEDED, and FAILED.

      • result object

        The outcome of the attempted transaction.

        • code integer(int64)
        • message string
      • dateCreated string(date-time)

        The datestamp the batch was created - ISO format - e.g. 2018-04-04T00:53:21.910Z

      • lastUpdated string(date-time)

        The datestamp of the last action on this batch - ISO format - e.g. 2018-04-04T10:48:53.540Z

      • feeAmount integer(int64)

        The fee charged by fire.com for the payment. In pence or cent.

      • taxAmount integer(int64)

        Any taxes/duty collected by fire.com for this payments (e.g. stamp duty etc). In pence or cent.

      • amountAfterCharges integer(int64)

        The amount of the transfer after fees and taxes. in pence or cent.

      • icanFrom integer(int64)

        The Fire account ID of the source account.

      • icanTo integer(int64)

        The Fire account ID for the fire.com account the funds are sent to.

      • amount integer(int64)

        The amount of funds to send. In cent or pence

      • ref string

        The reference on the transaction.

      • refId integer(int64)

        The ID of the resulting payment in your account. Can be used to retrieve the transaction using the https://api.fire.com/business/v1/accounts/{accountId}/transactions/{refId} endpoint.

Definition
GET https://api-preprod.fire.com/business/v1/batches/{batchUuid}/internaltransfers
cURL example
curl \ -X GET https://api-preprod.fire.com/business/v1/batches/4ADFB67A-0F5B-4A9A-9D74-34437250045C/internaltransfers
Response example (200)
{ "total": 1, "items": [ { "batchItemUuid": "F2AF3F2B-4406-4199-B249-B354F2CC6019", "status": "SUCCEEDED", "result": { "code": 500001, "message": "SUCCESS" }, "dateCreated": "2021-04-04T10:48:53.540Z", "lastUpdated": "2021-04-04T10:48:53.540Z", "feeAmount": 0, "taxAmount": 0, "amountAfterCharges": 10000, "icanFrom": 2150, "icanTo": 1002, "amount": 10000, "ref": "Testing a transfer via batch", "refId": 123782 } ] }

Add payment for an internal transfers

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

Path parameters
  • batchUuid Required / string
Body
  • icanFrom integer(int64)

    The account ID for the fire.com account the funds are taken from

  • icanTo integer(int64)

    The account ID for the fire.com account the funds are directed to

  • amount integer(int64)

    amount of funds to be transfered

  • ref string

    The reference on the transaction

Responses
  • • 200 object

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

    • batchItemUuid string

      A Batch Item UUID for this item. Note* Do not confuse this for BatchUuid when submitting a batch.

Definition
POST https://api-preprod.fire.com/business/v1/batches/{batchUuid}/internaltransfers
cURL example
curl \ -X POST https://api-preprod.fire.com/business/v1/batches/4ADFB67A-0F5B-4A9A-9D74-34437250045C/internaltransfers \ -H "Content-Type: application/json" \ -d '{"icanFrom":2001,"icanTo":3221,"amount":10000,"ref":"Moving funds to Operating Account"}'
Request payload example
{ "icanFrom": 2001, "icanTo": 3221, "amount": 10000, "ref": "Moving funds to Operating Account" }
Response example (200)
{ "batchItemUuid": "fba4a76a-ce51-4fc1-b562-98ec01299e4d" }

List items in a Batch

Returns a paginated list of items in the specified batch.

Path parameters
  • batchUuid Required / string
Query parameters
  • offset integer(int64)
  • limit integer(int64)
Responses
  • • 200 object

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

    • total integer(int64)

      total number of batches returned

    • items array[object]
      • batchItemUuid string

        A UUID for this item.

      • status string

        status of the batch if internal trasnfer

        Values are SUBMITTED, REMOVED, SUCCEEDED, and FAILED.

      • result object

        The outcome of the attempted transaction.

        • code integer(int64)
        • message string
      • dateCreated string(date-time)

        The datestamp the batch was created - ISO format - e.g. 2018-04-04T00:53:21.910Z

      • lastUpdated string(date-time)

        The datestamp of the last action on this batch - ISO format - e.g. 2018-04-04T10:48:53.540Z

      • feeAmount integer(int64)

        The fee charged by fire.com for the payment. In pence or cent.

      • taxAmount integer(int64)

        Any taxes/duty collected by fire.com for this payments (e.g. stamp duty etc). In pence or cent.

      • amountAfterCharges integer(int64)

        The amount of the transfer after fees and taxes. in pence or cent.

      • icanFrom integer(int64)

        The Fire account ID of the source account.

      • icanTo integer(int64)

        The Fire account ID for the fire.com account the funds are sent to.

      • amount integer(int64)

        The amount of funds to send. In cent or pence

      • ref string

        The reference on the transaction.

      • refId integer(int64)

        The ID of the resulting payment in your account. Can be used to retrieve the transaction using the https://api.fire.com/business/v1/accounts/{accountId}/transactions/{refId} endpoint.

Definition
GET https://api-preprod.fire.com/business/v1/batches/{batchUuid}/banktransfers
cURL example
curl \ -X GET https://api-preprod.fire.com/business/v1/batches/4ADFB67A-0F5B-4A9A-9D74-34437250045C/banktransfers
Response example (200)
{ "total": 1, "items": [ { "batchItemUuid": "F2AF3F2B-4406-4199-B249-B354F2CC6019", "status": "SUCCEEDED", "result": { "code": 500001, "message": "SUCCESS" }, "dateCreated": "2021-04-04T10:48:53.540Z", "lastUpdated": "2021-04-04T10:48:53.540Z", "feeAmount": 0, "taxAmount": 0, "amountAfterCharges": 10000, "icanFrom": 2150, "icanTo": 1002, "amount": 10000, "ref": "Testing a transfer via batch", "refId": 123782 } ] }

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
  • batchUuid Required / string
Responses
  • • 200 object

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

    • batchItemUuid string

      A Batch Item UUID for this item. Note* Do not confuse this for BatchUuid when submitting a batch.

Definition
POST https://api-preprod.fire.com/business/v1/batches/{batchUuid}/banktransfers
cURL example
curl \ -X POST https://api-preprod.fire.com/business/v1/batches/4ADFB67A-0F5B-4A9A-9D74-34437250045C/banktransfers \ -H "Content-Type: application/json"
Response example (200)
{ "batchItemUuid": "fba4a76a-ce51-4fc1-b562-98ec01299e4d" }

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
  • batchUuid Required / string
  • itemUuid Required / string
Responses
  • • 200

    Batch payment deleted successfully.

Definition
DELETE https://api-preprod.fire.com/business/v1/batches/{batchUuid}/internaltransfers/{itemUuid}
cURL example
curl \ -X DELETE https://api-preprod.fire.com/business/v1/batches/4ADFB67A-0F5B-4A9A-9D74-34437250045C/internaltransfers/4ADFB67A-0F5B-4A9A-9D74-34437250045C
Response example (200)
No content

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
  • batchUuid Required / string
  • itemUuid Required / string
Responses
  • • 200

    Batch payment deleted successfully.

Definition
DELETE https://api-preprod.fire.com/business/v1/batches/{batchUuid}/banktransfers/{itemUuid}
cURL example
curl \ -X DELETE https://api-preprod.fire.com/business/v1/batches/4ADFB67A-0F5B-4A9A-9D74-34437250045C/banktransfers/{itemUuid}
Response example (200)
No content

Get details of a single Batch

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

Path parameters
  • batchUuid Required / string
Responses
  • • 200 object

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

    • batchItemUuid string

      A UUID for this item.

    • status string

      status of the batch if internal trasnfer

      Values are SUBMITTED, REMOVED, SUCCEEDED, and FAILED.

    • result object

      The outcome of the attempted transaction.

      • code integer(int64)
      • message string
    • dateCreated string(date-time)

      The datestamp the batch was created - ISO format - e.g. 2018-04-04T00:53:21.910Z

    • lastUpdated string(date-time)

      The datestamp of the last action on this batch - ISO format - e.g. 2018-04-04T10:48:53.540Z

    • feeAmount integer(int64)

      The fee charged by fire.com for the payment. In pence or cent.

    • taxAmount integer(int64)

      Any taxes/duty collected by fire.com for this payments (e.g. stamp duty etc). In pence or cent.

    • amountAfterCharges integer(int64)

      The amount of the transfer after fees and taxes. in pence or cent.

    • icanFrom integer(int64)

      The Fire account ID of the source account.

    • icanTo integer(int64)

      The Fire account ID for the fire.com account the funds are sent to.

    • amount integer(int64)

      The amount of funds to send. In cent or pence

    • ref string

      The reference on the transaction.

    • refId integer(int64)

      The ID of the resulting payment in your account. Can be used to retrieve the transaction using the https://api.fire.com/business/v1/accounts/{accountId}/transactions/{refId} endpoint.

Definition
GET https://api-preprod.fire.com/business/v1/batches/{batchUuid}
cURL example
curl \ -X GET https://api-preprod.fire.com/business/v1/batches/4ADFB67A-0F5B-4A9A-9D74-34437250045C
Response example (200)
{ "batchItemUuid": "F2AF3F2B-4406-4199-B249-B354F2CC6019", "status": "SUCCEEDED", "result": { "code": 500001, "message": "SUCCESS" }, "dateCreated": "2021-04-04T10:48:53.540Z", "lastUpdated": "2021-04-04T10:48:53.540Z", "feeAmount": 0, "taxAmount": 0, "amountAfterCharges": 10000, "icanFrom": 2150, "icanTo": 1002, "amount": 10000, "ref": "Testing a transfer via batch", "refId": 123782 }

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
  • batchUuid Required / string
Responses
  • • 200

    Batch payment deleted successfully.

Definition
DELETE https://api-preprod.fire.com/business/v1/batches/{batchUuid}
cURL example
curl \ -X DELETE https://api-preprod.fire.com/business/v1/batches/4ADFB67A-0F5B-4A9A-9D74-34437250045C
Response example (200)
No content

List Approvers for a Batch

Returns a list of approvers for this batch.

Path parameters
  • batchUuid Required / string
Responses
  • • 200 object

    A list of approvers for this batch.

    • approvals array[object]
      • userId integer(int64)

        User id assigned by fire.com

      • emailAddress string

        User email address

      • firstName string
      • lastName string
      • mobileNumber string
      • status string
      • lastUpdated string(date-time)

        The datestamp of the last action on this batch - ISO format - e.g. 2018-04-04T10:48:53.540Z

Definition
GET https://api-preprod.fire.com/business/v1/batches/{batchUuid}/approvals
cURL example
curl \ -X GET https://api-preprod.fire.com/business/v1/batches/4ADFB67A-0F5B-4A9A-9D74-34437250045C/approvals
Response example (200)
{ "approvals": [ { "userId": 3138, "emailAddress": "jane.doe@example.com", "firstName": "Jane", "lastName": "Doe", "mobileNumber": 353871234567, "status": "PENDING_APPROVAL", "lastUpdated": "2021-04-04T10:48:53.540Z" } ] }

Cards

View List of Cards.

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

Responses
  • • 200 object

    Successful response

    • cards array[object]
      • blocked boolean

        Whether the card is blocked or not

      • cardId integer(int64)

        card id assigned by fire.com

      • dateCreated string(date-time)

        The date-time the card was created

      • emailAddress string

        card user email address

      • expiryDate string(date-time)

        card expiry date

      • firstName string

        card user first name

      • lastName string

        card user last name

      • eurIcan integer(int64)

        identifier for the eur fire.com account (assigned by fire.com)

      • gbpIcan integer(int64)

        identifier for the gbp fire.com account (assigned by fire.com)

      • maskedPan string

        card number (masked)

      • provider string

        card provider

        Values are MASTERCARD.

      • status string

        card status

        Values are LIVE, CREATED_ACTIVE, CREATED_INACTIVE, and DEACTIVATED.

      • statusReason string

        reason for card status

        Values are LOST_CARD, STOLEN_CARD, and CARD_DESTROYED.

      • userId integer(int64)

        card user id assigned by fire.com

  • • 401

    Access Token is Invalid or missing

  • • 403

    Access Token is Invalid or missing

Definition
GET https://api-preprod.fire.com/business/v1/cards
cURL example
curl \ -X GET https://api-preprod.fire.com/business/v1/cards
Response example (200)
{ "cards": [ { "blocked": true, "cardId": 51, "dateCreated": "2017-01-19T16:38:15.803Z", "emailAddress": "user@example.com", "expiryDate": "2019-01-31T00:00:00.000Z", "firstName": "John", "lastName": "Doe", "eurIcan": 2150, "gbpIcan": 2152, "maskedPan": "537455******1111", "provider": "MASTERCARD", "status": "LIVE", "statusReason": "LOST_CARD", "userId": 3138 } ] }
Response example (401)
No content
Response example (403)
No content

Create a new debit card.

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

Body
  • userId number(int64)
  • cardPin string
  • eurIcan integer(int64)
  • gbpIcan integer(int64)
  • addressType string

    Values are HOME and BUSINESS.

  • acceptFeesAndCharges boolean
Responses
  • • 200 object

    Card created successfully

    • cardId integer(int64)
    • maskedPan string
    • expiryDate string(date-time)
    • status string

      Values are CREATED_ACTIVE and CREATED_INACTIVE.

Definition
POST https://api-preprod.fire.com/business/v1/cards
cURL example
curl \ -X POST https://api-preprod.fire.com/business/v1/cards \ -H "Content-Type: application/json" \ -d '{"userId":3245,"cardPin":5345,"eurIcan":2150,"gbpIcan":2152,"addressType":"BUSINESS","acceptFeesAndCharges":true}'
Request payload example
{ "userId": 3245, "cardPin": 5345, "eurIcan": 2150, "gbpIcan": 2152, "addressType": "BUSINESS", "acceptFeesAndCharges": true }
Response example (200)
{ "cardId": 51, "maskedPan": "537455******1111", "expiryDate": "2019-01-31T00:00:00.000Z", "status": "CREATED_ACTIVE" }

Users

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[object]

    List of all Users.

    • Id integer(int64)

      The User ID for this User

    • emailAddress string

      email address for user

    • firstName string

      User first name

    • lastName string

      User second name

    • mobileNumber integer(int64)

      User mobile number

    • role string

      User role

      Values are ADMIN, FULL_USER, READ_ONLY, and CARD_ONLY.

    • status string

      Status of user

      Values are LIVE, CLOSED, FROZEN, INVITE_SENT, and SMS_CODE_SENT.

    • lastlogin string

      Timestamp on when user last logged in.

    • userCvl string

      Users Cvl type ID (shows up when status is LIVE)

    • mobileApplicationDetails object
      • businessUserId integer(int64)

        Business user ID

      • mobileApplicationId integer(int64)

        Mobile application id for user.

      • clientID string

        Client ID of user.

      • status string

        Status of user

        Values are LIVE, CLOSED, LOCKED, and SMS_SENT.

      • deviceName string

        type of device.

        Values are iPhone, Android, and Other.

      • OS string

        Operating system of device.

        Values are Android, IOS, and OTHER.

      • deviceOSVersion string

        OS version for device.

Definition
GET https://api-preprod.fire.com/business/v1/users
cURL example
curl \ -X GET https://api-preprod.fire.com/business/v1/users
Response example (200)
[ { "Id": "14059", "emailAddress": "user@example.com", "firstName": "Colm", "lastName": "User", "mobileNumber": "+35371234567", "role": "ADMIN", "status": "LIVE", "lastlogin": "2012-01-20T11:21:35.000Z", "userCvl": "FULL", "mobileApplicationDetails": { "businessUserId": "14059", "mobileApplicationId": "18967", "clientID": "EBB10F29-A653-4DBA-9C8C-BA79F72F78B0", "status": "LIVE", "deviceName": "iPhone", "OS": "Android", "deviceOSVersion": "14.4" } } ]

Returns details of a specific fire.com user.

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

Path parameters
  • userId Required / number
Responses
  • • 200 object

    Unique information about a User.

    • Id integer(int64)

      The User ID for this User

    • emailAddress string

      email address for user

    • firstName string

      User first name

    • lastName string

      User second name

    • mobileNumber integer(int64)

      User mobile number

    • role string

      User role

      Values are ADMIN, FULL_USER, READ_ONLY, and CARD_ONLY.

    • status string

      Status of user

      Values are LIVE, CLOSED, FROZEN, INVITE_SENT, and SMS_CODE_SENT.

    • lastlogin string

      Timestamp on when user last logged in.

    • userCvl string

      Users Cvl type ID (shows up when status is LIVE)

    • mobileApplicationDetails object
      • businessUserId integer(int64)

        Business user ID

      • mobileApplicationId integer(int64)

        Mobile application id for user.

      • clientID string

        Client ID of user.

      • status string

        Status of user

        Values are LIVE, CLOSED, LOCKED, and SMS_SENT.

      • deviceName string

        type of device.

        Values are iPhone, Android, and Other.

      • OS string

        Operating system of device.

        Values are Android, IOS, and OTHER.

      • deviceOSVersion string

        OS version for device.

Definition
GET https://api-preprod.fire.com/business/v1/user/{userId}
cURL example
curl \ -X GET https://api-preprod.fire.com/business/v1/user/14059
Response example (200)
{ "Id": "14059", "emailAddress": "user@example.com", "firstName": "Colm", "lastName": "User", "mobileNumber": "+35371234567", "role": "ADMIN", "status": "LIVE", "lastlogin": "2012-01-20T11:21:35.000Z", "userCvl": "FULL", "mobileApplicationDetails": { "businessUserId": "14059", "mobileApplicationId": "18967", "clientID": "EBB10F29-A653-4DBA-9C8C-BA79F72F78B0", "status": "LIVE", "deviceName": "iPhone", "OS": "Android", "deviceOSVersion": "14.4" } }

Payee bank accounts

List all Payee Bank Accounts

Returns all your payee bank accounts.

Ordered by date added descending.

Can be paginated.

Responses
  • • 200 object

    An array of Payee Bank Accounts

    • id integer(int64)

      Identifier for the fire.com payee bank account (assigned by fire.com).

    • currency object
      • code string

        The three letter code for the currency - either EUR or GBP.

        Values are EUR and GBP.

      • description string

        The name of the currency

    • status string

      The status of the payee. Only payees in LIVE status can be selected as a destination account for an outgoing payment.

      • 'CREATED' - The payee has been set-up via Bank Transfer Received, Direct Debit, or Open Banking. This payee must be converted to LIVE status to select as a destination account for an outgoing payment.
      • 'LIVE' - The payee can be selected as a destination account for an outgoing payment.
      • 'CLOSED'
      • 'ARCHIVED' - The payee has been deleted and must be added again to be selected as a destination account for an outgoing payment.

      Values are CREATED, LIVE, CLOSED, and ARCHIVED.

    • accountName string

      The alias attributed to the payee, usually set by the user when creating the payee.

    • accountHolderName string

      The name on the payee bank account.

    • bic string

      The BIC of the account if currency is EUR.

    • iban string

      The IBAN of the account if currency is EUR.

    • nsc string

      The Sort Code of the account if currency is GBP.

    • accountNumber string

      The Account Number of the account if currency is GBP.

    • createdBy string

      The creation source of the payee.

      Values are CUSTOMER, LODGEMENT, DIRECT DEBIT, OPEN BANKING, FIRE OPEN PAYMENT, and FIRE DIRECT.

    • dateCreated string(date-time)

      The date the payee was created. Milliseconds since the epoch (1970).

Definition
GET https://api-preprod.fire.com/business/v1/payees
cURL example
curl \ -X GET https://api-preprod.fire.com/business/v1/payees
Response example (200)
{ "id": 742, "currency": { "code": "EUR", "description": "Euro" }, "status": "LIVE", "accountName": "Joe", "accountHolderName": "Joe Bloggs", "bic": "BOFIIE2DXXX", "iban": "IE86BOFI90535211111111", "nsc": "string", "accountNumber": "string", "createdBy": "CUSTOMER", "dateCreated": "2019-08-22T07:48:56.460Z" }