v1

latestOpenAPI 3.1.02026-07-136388308.2 KB

Open Banking

Create a payment request

This endpoint creates a new Open Banking Payment request. A code is returned that can be shared to your customers as a URL by any channel you wish. See our Guide to Fire Open Payments for more details. You will need to enable PERM_BUSINESS_POST_PAYMENT_REQUEST to use this endpoint.

post/v1/paymentrequests

Request body

currency'EUR' | 'GBP' required

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

type'OTHER' required

The type of Fire Open Payment that was created

icanTointeger required

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

amountinteger

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

myRefstring required

An internal description of the request.

descriptionstring required

A public facing description of the request. This will be shown to the user when they tap or scan the request. Fire will truncate to 18 characters to ensure it is accepted by all banks. It is safest to use only numbers, letters, spaces and a fullstop (.) Special characters are not accepted by most banks and errors will only occur after the customer has approved the payment.

maxNumberPaymentsinteger

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

expirystring date-time

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

returnUrlstring

The merchant return URL where the customer will be re-directed to with the result of the transaction. The returnUrl variable should handle two scenarios. If the user cancels the payment before reaching their banking app, URLs are identified with a /return?status=cancelled. If the user proceeds to their banking app, URLs are identified with /paymentUUID={paymentUUID}

collectFieldsstring

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.

mandatoryFieldsstring

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.

additionalFieldsstring

These fields will be displayed 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.

Example request

{
  "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": "CustNum-303863544",
    "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

Payment Request created successfully

codestring

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

type'OTHER'

The type of Fire Open Payment that was created.

Example response

{
  "code": "1234abcd"
}