---
title: "Create a payment request"
method: POST
path: "/v1/paymentrequests"
tags: ["Open Banking"]
---

# Create a payment request

`POST /v1/paymentrequests`

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](/docs/fire-open-payments) for more details. You will need to enable PERM_BUSINESS_POST_PAYMENT_REQUEST to use this endpoint.

## Request body

- NewPaymentRequest
  - `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
  - `icanTo` integer, required — The ican of the account to collect the funds into. Must be one of your fire.com Accounts.
  - `amount` integer — The requested amount to pay. Note the last two digits represent pennies/cents, (e.g., £1.00 = 100).
  - `myRef` string, required — An internal description of the request.
  - `description` string, 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.
  - `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. 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}
  - `orderDetails` OrderDetails
    - `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 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.

## Response `201`

Payment Request created successfully

- PaymentRequestResponse
  - `code` string — 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.

## Other responses

- `400` — An error has occured. Any 403 errors usually mean your access token is invalid or missing. For other errors, check the validity of your input, and if you are permitted to access this endpoint.
- `401` — An error has occured. Any 403 errors usually mean your access token is invalid or missing. For other errors, check the validity of your input, and if you are permitted to access this endpoint.
- `403` — An error has occured. Any 403 errors usually mean your access token is invalid or missing. For other errors, check the validity of your input, and if you are permitted to access this endpoint.

---

[API](https://skmtc.net/firefinancialservices/apis/fire-financial-services-business-api.md) · [All operations](https://skmtc.net/firefinancialservices/apis/fire-financial-services-business-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/firefinancialservices/fire-financial-services-business-api/versions/1d19896d095c/schema)