Skip to main content
Documentation Powered by Redocly

Payments (1.1.0)

Download OpenAPI specification:Download

Payments API requests specification

Single Payments

Single payments API requests for managing payments

Create draft payment

Create a draft payment, which you can later process by its id.

header Parameters
terminal-secret
required
string <uuid>
Example: 3858f642-e92f-431c-9d38-46d15efb7fba
terminal-id
required
string
Example: 62b48adf6ba2cd6a040b1eec
Request Body schema: application/json
One of
reference
required
string (reference) [ 1 .. 12 ] characters /^[a-z0-9-]+$/i
amount
required
string (amount) ^[0-9]*.[0-9]{2}$

Amount of money of the payment

bankAccount
string (bankAccountId)

ID of the bank account to which the payment will be made. If not specified, the payment will be made to the company's default bank account

customerName
string (customerName)

Customer name

dueDate
string (dueDate)

Date when payment should be completed. If not completed by this date, the payment status will be changed to 'overdue'

customerEmail
string <email> (customerEmail)

Customer email

customerEmailCC
Array of strings <email> (customerEmailCC)

CC

paymentMethod
any
Enum: "fena_ob" "fena_ob_qr"
description
string (paymentDescription) <= 1000 characters

Payment description

Array of objects (PaymentNoteBody) [ items ]

Responses

Request samples

Content type
application/json
Example
{
  • "reference": "ref-123",
  • "amount": "0.50",
  • "bankAccount": "62b48c5b6ba2cd6a040b20a8",
  • "customerName": "John Doe",
  • "dueDate": "2024-01-24T00:00:00Z",
  • "customerEmail": "example@gmail.com",
  • "customerEmailCC": [
    ],
  • "paymentMethod": "fena_ob",
  • "description": "string",
  • "notes": [
    ]
}

Response samples

Content type
application/json; charset=utf-8
{
  • "created": true,
  • "result": {
    }
}

Create and process payment.

Create payment with link. Payment with payment method Fena Open Banking and Fena Open Banking QR will be marked as sent and payment link will be generated. Payment with payment method Cash and Other will be marked as paid.

header Parameters
terminal-secret
required
string <uuid>
Example: 3858f642-e92f-431c-9d38-46d15efb7fba
terminal-id
required
string
Example: 62b48adf6ba2cd6a040b1eec
Request Body schema: application/json
One of
reference
required
string (reference) [ 1 .. 12 ] characters /^[a-z0-9-]+$/i
amount
required
string (amount) ^[0-9]*.[0-9]{2}$

Amount of money of the payment

bankAccount
string (bankAccountId)

ID of the bank account to which the payment will be made. If not specified, the payment will be made to the company's default bank account

customerName
string (customerName)

Customer name

dueDate
string (dueDate)

Date when payment should be completed. If not completed by this date, the payment status will be changed to 'overdue'

customerEmail
string <email> (customerEmail)

Customer email

customerEmailCC
Array of strings <email> (customerEmailCC)

CC

paymentMethod
any
Enum: "fena_ob" "fena_ob_qr"
description
string (paymentDescription) <= 1000 characters

Payment description

Array of objects (PaymentNoteBody) [ items ]

Responses

Request samples

Content type
application/json
Example
{
  • "reference": "ref-123",
  • "amount": "0.50",
  • "bankAccount": "62b48c5b6ba2cd6a040b20a8",
  • "customerName": "John Doe",
  • "dueDate": "2024-01-24T00:00:00Z",
  • "customerEmail": "example@gmail.com",
  • "customerEmailCC": [
    ],
  • "paymentMethod": "fena_ob",
  • "description": "string",
  • "notes": [
    ]
}

Response samples

Content type
application/json; charset=utf-8
{
  • "created": true,
  • "result": {
    }
}

Get payment by ID

Get payment details by its ID

path Parameters
id
required
string
Example: 62b48c5b6ba2cd6a040b20a8

Mongoose Object ID of the target entity

header Parameters
terminal-secret
required
string <uuid>
Example: 3858f642-e92f-431c-9d38-46d15efb7fba
terminal-id
required
string
Example: 62b48adf6ba2cd6a040b1eec

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": {
    }
}

List payments

Get list of all payments

query Parameters
page
integer
Default: 1
Example: page=4

Current page number

limit
integer
Default: 25
Example: limit=10

Number of items per page

string or string or string or string or string or string or string or string or string or string or string (PaymentStatus)
Example: status=paid

Payment status

amountFrom
string (amount) ^[0-9]*.[0-9]{2}$
Example: amountFrom=0.50

Filter payments by amount from

amountTo
string (amount) ^[0-9]*.[0-9]{2}$
Example: amountTo=0.50

Filter payments by amount to

from
string (createdAt)
Example: from=2022-12-24T00:00:00Z

Filter payments by created date from

from
string (createdAt)
Example: from=2022-12-24T00:00:00Z

Filter payments by created date to

paymentMethod
string (PaymentMethod)
Enum: "fena_ob" "cash" "other" "fena_ob_qr"

Filter payments by payment method

header Parameters
terminal-secret
required
string <uuid>
Example: 3858f642-e92f-431c-9d38-46d15efb7fba
terminal-id
required
string
Example: 62b48adf6ba2cd6a040b1eec

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": {
    }
}

Edit payment data

Edit payment data

path Parameters
id
required
string
Example: 62b48c5b6ba2cd6a040b20a8

Mongoose Object ID of the target entity

header Parameters
terminal-secret
required
string <uuid>
Example: 3858f642-e92f-431c-9d38-46d15efb7fba
terminal-id
required
string
Example: 62b48adf6ba2cd6a040b1eec
Request Body schema: application/json
One of
reference
required
string (reference) [ 1 .. 12 ] characters /^[a-z0-9-]+$/i
amount
required
string (amount) ^[0-9]*.[0-9]{2}$

Amount of money of the payment

customerName
string (customerName)

Customer name

dueDate
string (dueDate)

Date when payment should be completed. If not completed by this date, the payment status will be changed to 'overdue'

customerEmail
string <email> (customerEmail)

Customer email

customerEmailCC
Array of strings <email> (customerEmailCC)

CC

description
string (paymentDescription) <= 1000 characters

Payment description

Responses

Request samples

Content type
application/json
Example
{
  • "reference": "ref-123",
  • "amount": "0.50",
  • "customerName": "John Doe",
  • "dueDate": "2024-01-24T00:00:00Z",
  • "customerEmail": "example@gmail.com",
  • "customerEmailCC": [
    ],
  • "description": "string"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "saved": true,
  • "result": {
    }
}

Process draft payment

Process draft payment by its ID. If payment method is 'Fena Open Banking' or 'Fena Open Banking QR', payment status will be changed to 'send' and payment link will be generated. If payment method is 'Cash' or 'Other', payment status will be changed to 'paid'

path Parameters
id
required
string
Example: 62b48c5b6ba2cd6a040b20a8

Mongoose Object ID of the target entity

header Parameters
terminal-secret
required
string <uuid>
Example: 3858f642-e92f-431c-9d38-46d15efb7fba
terminal-id
required
string
Example: 62b48adf6ba2cd6a040b1eec

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "saved": true,
  • "result": {
    }
}

Delete payment

Delete payment by its ID. Paid payments can't be deleted.

path Parameters
id
required
string
Example: 62b48c5b6ba2cd6a040b20a8

Mongoose Object ID of the target entity

header Parameters
terminal-secret
required
string <uuid>
Example: 3858f642-e92f-431c-9d38-46d15efb7fba
terminal-id
required
string
Example: 62b48adf6ba2cd6a040b1eec

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "deleted": true
}

Refund payment

Refund paid payment by its ID. Payment status will be changed to 'refund_started' and refund link will be generated

path Parameters
id
required
string
Example: 62b48c5b6ba2cd6a040b20a8

Mongoose Object ID of the target entity

header Parameters
terminal-secret
required
string <uuid>
Example: 3858f642-e92f-431c-9d38-46d15efb7fba
terminal-id
required
string
Example: 62b48adf6ba2cd6a040b1eec
Request Body schema: application/json
amount
string

Override refund amount

object

Responses

Request samples

Content type
application/json
{
  • "amount": "string",
  • "payeeAccountInfo": {
    }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "saved": true,
  • "result": {
    }
}

Get public payment data

Get

path Parameters
id
required
string
Example: 62b48c5b6ba2cd6a040b20a8

Mongoose Object ID of the target entity

Responses

Response samples

Content type
application/json; charset=utf-8
{}

Payment notes

Payments notes API. Used for creating, editing and deleting payment notes.

Create note for payment

Create note for payment

path Parameters
id
required
string
Example: 62b48c5b6ba2cd6a040b20a8

Mongoose Object ID of the target entity

companyId
required
string
Example: 62b48adf6ba2cd6a040b1eec

Mongoose Object ID of the target managed company

header Parameters
terminal-secret
required
string <uuid>
Example: 3858f642-e92f-431c-9d38-46d15efb7fba
terminal-id
required
string
Example: 62b48adf6ba2cd6a040b1eec
Request Body schema: application/json
text
string [ 1 .. 1000 ] characters

Note text

visibility
string
Enum: "public" "private"

Note visibility. Public notes are visible to the customer in emails. Private notes are visible only to the user in the Fena Portal.

Responses

Request samples

Content type
application/json
{
  • "text": "This is a test payment",
  • "visibility": "public"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "saved": true,
  • "result": {
    }
}

Delete note for payment

Delete note for payment

path Parameters
id
required
string
Example: 62b48c5b6ba2cd6a040b20a8

Mongoose Object ID of the target entity

companyId
required
string
Example: 62b48adf6ba2cd6a040b1eec

Mongoose Object ID of the target managed company

noteId
required
string
Example: 62b48c5b6ba2cd6a040b20a8

Mongoose Object ID of the note to be deleted

header Parameters
terminal-secret
required
string <uuid>
Example: 3858f642-e92f-431c-9d38-46d15efb7fba
terminal-id
required
string
Example: 62b48adf6ba2cd6a040b1eec

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "saved": true,
  • "result": {
    }
}

Edit note for payment

Edit note for payment

path Parameters
id
required
string
Example: 62b48c5b6ba2cd6a040b20a8

Mongoose Object ID of the target entity

companyId
required
string
Example: 62b48adf6ba2cd6a040b1eec

Mongoose Object ID of the target managed company

noteId
required
string
Example: 62b48c5b6ba2cd6a040b20a8

Mongoose Object ID of the note to be edited

header Parameters
terminal-secret
required
string <uuid>
Example: 3858f642-e92f-431c-9d38-46d15efb7fba
terminal-id
required
string
Example: 62b48adf6ba2cd6a040b1eec
Request Body schema: application/json
text
string [ 1 .. 1000 ] characters

Note text

visibility
string
Enum: "public" "private"

Note visibility. Public notes are visible to the customer in emails. Private notes are visible only to the user in the Fena Portal.

Responses

Request samples

Content type
application/json
{
  • "text": "This is a test payment",
  • "visibility": "public"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "saved": true,
  • "result": {
    }
}

Payments flow

Payments flow API. Used for payments initiated by customers.

Initiate payment

Initiate payment by its hashed ID. The response will contain the auth URL which will lead to the payment provider's page where the customer can complete the payment.

Request Body schema: application/json
id
string

Hashed ID from the payment link (the one after or p?=)

provider
string
Enum: "ob-natwest" "ob-lloyds-personal" "ob-rbs" "ob-tsb" "ob-halifax-personal" "ob-mettle" "ob-bos-personal" "ob-hsbc-personal" "ob-barclays-business" "ob-danske-private" "ob-danske-business" "ob-revolut" "ob-starling" "ob-bos-business" "ob-first-direct" "ob-nationwide" "ob-monzo" "ob-lloyds-business" "ob-santander" "ob-virgin-money" "ob-hsbc-business" "ob-barclays-personal" "ob-barclays-corporate" "ob-tide" "ob-ulster" "ob-sandbox-coutts" "ob-chase" "ob-aibni-retail" "ob-aibni-corporate" "ob-aibgb-retail" "ob-aibgb-corporate" "ob-boi-uk-b365" "ob-boi-uk-bol" "ob-zempler"

Provider customer is paying with

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "provider": "ob-natwest"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "sucess": true,
  • "data": {
    }
}

Providers

Payment providers API. Used for getting list of payment providers.

Get list of payment providers

List of payment Fena OB providers supported by Fena

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": [
    ]
}

Webhooks

Webhooks are used to notify your application about events that happen in FenaPay. For example, when a payment is completed, a webhook will be sent to your application with the payment data. You can use webhooks to automate your business processes and integrate FenaPay with your CRM, ERP, or other systems.

Payment status update Webhook

Webhook notification about payment status update

Request Body schema: application/json

Webhook payload

One of
eventScope
string
Value: "single-payments"

The scope of the webhook

eventName
string
Value: "status-update"

payment status update

id
string (paymentId)

ID of the payment

reference
string (reference) [ 1 .. 12 ] characters /^[a-z0-9-]+$/i
amount
string (amount) ^[0-9]*.[0-9]{2}$

Amount of money of the payment

object (BankAccountData)
customerName
string (customerName)

Customer name

dueDate
string (dueDate)

Date when payment should be completed. If not completed by this date, the payment status will be changed to 'overdue'

customerEmail
string <email> (customerEmail)

Customer email

customerEmailCC
Array of strings <email> (customerEmailCC)

CC

paymentMethod
string (PaymentMethod)
Enum: "fena_ob" "cash" "other" "fena_ob_qr"
createdAt
string (createdAt)

Date when entity was created

currency
string (currency)
string or string or string or string or string or string or string or string or string or string or string (PaymentStatus)

Payment status

completedAt
string (completedAt)

Date when payment was completed

refundLink
string
refundQrCodeData
string
object (refundPayeeAccount)

Information about the account from which the payment was made. Note that not all of the providers expose this information

description
string (paymentDescription) <= 1000 characters

Payment description

Array of objects (PaymentNote) [ items ]
dataApiCheckStatus
string (dataApiCheckStatus)
Enum: "pending_payment" "missed_payment" "payment_made" "partial_payment" "unable_to_check" "permanent_connection_loss" "waiting_for_first_check"

Data API check status is an additional check for payments, and indicates whether a matching transaction has been found in the transactions list of the user's/company's bank account. This flag provides an update if the transactions list and the last payment status do not match e.g. pending status but completed transaction identified in the transaction list. To use this field the payment must be created with an account which has an existing consentId, meaning that this account was connected automatically, using Data APIs. The status check is done at the start of every hour (9:00, 10:00, etc.). Only available for payments made with Fena Open Banking with bank account connected via app (Data APIs).

lastDataApiCheckAt
string (lastDataApiCheckAt)

Date when the payment had its most recent Data API status check

Responses

Request samples

Content type
application/json
{
  • "eventScope": "single-payments",
  • "eventName": "status-update",
  • "id": "62b48c5b6ba2cd6a040b20a8",
  • "reference": "ref-123",
  • "amount": "0.50",
  • "bankAccount": {
    },
  • "customerName": "John Doe",
  • "dueDate": "2024-01-24T00:00:00Z",
  • "customerEmail": "example@gmail.com",
  • "customerEmailCC": [
    ],
  • "paymentMethod": "fena_ob",
  • "createdAt": "2022-12-24T00:00:00Z",
  • "currency": "GBP",
  • "status": "paid",
  • "link": "https://epos-pay.fena.co/payments/?p=8nj78XgqOGs5NmG6G8qy",
  • "qrCodeData": "https://epos-pay.fena.co/payments/?p=8nj78XgqOGs5NmG6G8qy",
  • "description": "string",
  • "notes": [
    ]
}

Data API status check Webhook

Webhook notification about data API status check. The status check value will be in the dataApiCheckStatus field. Please note that Data API status check is only available for payments with OB payment method with bank account connected via app (Data API).

Request Body schema: application/json

Webhook payload

One of
eventScope
string
Value: "single-payments"

The scope of the webhook

eventName
string
Value: "data-api-check"

payment status update

id
string (paymentId)

ID of the payment

reference
string (reference) [ 1 .. 12 ] characters /^[a-z0-9-]+$/i
amount
string (amount) ^[0-9]*.[0-9]{2}$

Amount of money of the payment

object (BankAccountData)
customerName
string (customerName)

Customer name

dueDate
string (dueDate)

Date when payment should be completed. If not completed by this date, the payment status will be changed to 'overdue'

customerEmail
string <email> (customerEmail)

Customer email

customerEmailCC
Array of strings <email> (customerEmailCC)

CC

paymentMethod
string (PaymentMethod)
Enum: "fena_ob" "cash" "other" "fena_ob_qr"
createdAt
string (createdAt)

Date when entity was created

currency
string (currency)
string or string or string or string or string or string or string or string or string or string or string (PaymentStatus)

Payment status

completedAt
string (completedAt)

Date when payment was completed

refundLink
string
refundQrCodeData
string
object (refundPayeeAccount)

Information about the account from which the payment was made. Note that not all of the providers expose this information

description
string (paymentDescription) <= 1000 characters

Payment description

Array of objects (PaymentNote) [ items ]
dataApiCheckStatus
string (dataApiCheckStatus)
Enum: "pending_payment" "missed_payment" "payment_made" "partial_payment" "unable_to_check" "permanent_connection_loss" "waiting_for_first_check"

Data API check status is an additional check for payments, and indicates whether a matching transaction has been found in the transactions list of the user's/company's bank account. This flag provides an update if the transactions list and the last payment status do not match e.g. pending status but completed transaction identified in the transaction list. To use this field the payment must be created with an account which has an existing consentId, meaning that this account was connected automatically, using Data APIs. The status check is done at the start of every hour (9:00, 10:00, etc.). Only available for payments made with Fena Open Banking with bank account connected via app (Data APIs).

lastDataApiCheckAt
string (lastDataApiCheckAt)

Date when the payment had its most recent Data API status check

Responses

Request samples

Content type
application/json
{
  • "eventScope": "single-payments",
  • "eventName": "data-api-check",
  • "id": "62b48c5b6ba2cd6a040b20a8",
  • "reference": "ref-123",
  • "amount": "0.50",
  • "bankAccount": {
    },
  • "customerName": "John Doe",
  • "dueDate": "2024-01-24T00:00:00Z",
  • "customerEmail": "example@gmail.com",
  • "customerEmailCC": [
    ],
  • "paymentMethod": "fena_ob",
  • "createdAt": "2022-12-24T00:00:00Z",
  • "currency": "GBP",
  • "status": "paid",
  • "completedAt": "2022-12-24T00:00:00Z",
  • "refundLink": "string",
  • "refundQrCodeData": "string",
  • "refundPayeeAccount": {
    },
  • "description": "string",
  • "notes": [
    ],
  • "dataApiCheckStatus": "pending_payment",
  • "lastDataApiCheckAt": "2022-12-24T00:00:00Z"
}