Create a Fire Open Payment request

v1.0.0

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.

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

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

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.
Select Bank / Account Provider page: The payer then selects their bank. Again this step is offered as part of the fire.com payment UI.
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.
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.
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:

You can create a new Fire Open Payment request either within Firework Online or via the API.
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”
Use the Refresh Token, Client ID and Client Key to create an access token as outlined in the “Authentication” steps.
On your website, create a “Pay by Bank” button alongside your other available payment methods, such as Cards and PayPal.
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.
Create a URL using the code returned in this format: https://payments.fire.com/{code} and redirect your customer to this page.
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.
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.
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}

This request creates a new Fire Open Payment Payment. 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.

Input

{
  "type": "object",
  "required": [
    "currency",
    "description",
    "icanTo",
    "myRef",
    "type"
  ],
  "properties": {
    "additionalFields": {
      "type": "string",
      "description": "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."
    },
    "amount": {
      "type": "integer",
      "format": "int64",
      "description": "The requested amount to pay. Note the last two digits represent pennies/cents, (e.g., £1.00 = 100)."
    },
    "collectFields": {
      "type": "string",
      "description": "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."
    },
    "currency": {
      "type": "string",
      "description": "Either `EUR` or `GBP`, and must correspond to the currency of the account the funds are being lodged into in the `icanTo`.",
      "enum": [
        "EUR",
        "GBP"
      ]
    },
    "description": {
      "type": "string",
      "description": "A public facing description of the request. This will be shown to the user when they tap or scan the request."
    },
    "expiry": {
      "type": "string",
      "format": "date-time",
      "description": "This is the expiry of the payment request. After this time, the payment cannot be paid."
    },
    "icanTo": {
      "type": "integer",
      "format": "int64",
      "description": "The ican of the account to collect the funds into. Must be one of your fire.com Accounts."
    },
    "mandatoryFields": {
      "type": "string",
      "description": "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."
    },
    "maxNumberPayments": {
      "type": "integer",
      "description": "The max number of people who can pay this request. Must be set to 1 for the ECOMMERCE_GOODS and ECOMMERCE_SERVICES types."
    },
    "myRef": {
      "type": "string",
      "description": "An internal description of the request."
    },
    "orderDetails": {
      "type": "object",
      "properties": {
        "comment1": {
          "type": "string",
          "description": "This is your own comment for the transaction."
        },
        "comment2": {
          "type": "string",
          "description": "This is your own comment for the transaction."
        },
        "customerNumber": {
          "type": "string",
          "description": "Use this field to store a customer number for the transaction (for example)."
        },
        "deliveryAddressLine1": {
          "type": "string",
          "description": "The first line of the delivery address."
        },
        "deliveryAddressLine2": {
          "type": "string",
          "description": "The second line of the delivery address."
        },
        "deliveryCity": {
          "type": "string",
          "description": "Delivery address city"
        },
        "deliveryCountry": {
          "type": "string",
          "description": "2-digit code for the country"
        },
        "deliveryPostCode": {
          "type": "string",
          "description": "Delivery address post code"
        },
        "merchantCustomerIdentification": {
          "type": "string",
          "description": "This is a reference you use to uniquely identify each of your customers."
        },
        "merchantNumber": {
          "type": "string",
          "description": "Your Merchant Number (if applicable)."
        },
        "orderId": {
          "type": "string",
          "description": "Use this field to store the order id for the transaction. The Order Id cannot be set unless the `maxNumberPayments` is 1."
        },
        "productId": {
          "type": "string",
          "description": "Use this field to store a product id for the transaction (for example)."
        },
        "variableReference": {
          "type": "string",
          "description": "Use this field to store any other reference for the transaction (for example, a phone number)."
        }
      }
    },
    "returnUrl": {
      "type": "string",
      "description": "The merchant return URL where the customer will be re-directed to with the result of the transaction."
    },
    "type": {
      "type": "string",
      "description": "The type of Fire Open Payment that was created",
      "enum": [
        "OTHER"
      ]
    }
  }
}

Output

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "The code for this request. Create a URL in this format: `https://payments.fire.com/{code}` and share to your customers.\n"
    },
    "type": {
      "type": "string",
      "description": "The type of Fire Open Payment that was created.",
      "enum": [
        "OTHER"
      ]
    }
  }
}