Skip to main content
Documentation Powered by Redocly

Payments (1.0)

Download OpenAPI specification:Download

Payments API requests specification

Payments

Single payments API

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
scope
string
Value: "single-payment"

The scope of the webhook

event_name
string
Value: "payment_status_update"

event_name

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

Responses

Request samples

Content type
application/json
{
  • "scope": "single-payment",
  • "event_name": "payment_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"
}

Payments requests

Create draft payment

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

path Parameters
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
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
string
Enum: "fena_ob" "fena_ob_qr"
description
string (paymentDescription) <= 1000 characters

Payment description

integration
string (MerchantIntegration)

Id of integration to use for payment. Payment webhooks will be sent to this integration webhook URL and customer will be redirected to this integration URL after payment is completed.

Responses

Request samples

Content type
application/json
{
  • "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",
  • "integration": "62b48c5b6ba2cd6a040b20a8"
}

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.

path Parameters
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
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
string
Enum: "fena_ob" "fena_ob_qr"
description
string (paymentDescription) <= 1000 characters

Payment description

integration
string (MerchantIntegration)

Id of integration to use for payment. Payment webhooks will be sent to this integration webhook URL and customer will be redirected to this integration URL after payment is completed.

Responses

Request samples

Content type
application/json
{
  • "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",
  • "integration": "62b48c5b6ba2cd6a040b20a8"
}

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

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

Responses

Response samples

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

List payments

Get list of all payments

path Parameters
companyId
required
string
Example: 62b48adf6ba2cd6a040b1eec

Mongoose Object ID of the target managed company

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

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
One of
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
{
  • "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

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

Responses

Response samples

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

Cancel payment

Cancel 'draft' or 'sent' payment by its ID. Payment status will be changed to 'cancelled' and payment link will no longer be valid.

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

Responses

Response samples

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

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

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

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

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
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": {
    }
}

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-revolut" "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-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"

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": {
    }
}