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
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 |
description | string (paymentDescription) <= 1000 characters Payment description |
Responses
Request samples
- Payload
{- "scope": "single-payment",
- "event_name": "payment_status_update",
- "id": "62b48c5b6ba2cd6a040b20a8",
- "reference": "ref-123",
- "amount": "0.50",
- "bankAccount": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "sortCode": "123456",
- "accountNumber": "12345678",
- "name": "Default account",
- "provider": "other",
- "isDefault": true,
- "status": "verified",
- "connectionType": "manual",
- "createdAt": "2022-12-24T00:00:00Z",
- "bankStatementAttachmentURL": "string",
- "bankConsentExpired": "day-30"
}, - "customerName": "John Doe",
- "dueDate": "2024-01-24T00:00:00Z",
- "customerEmail": "example@gmail.com",
- "customerEmailCC": [
- "example@gmail.com"
], - "paymentMethod": "fena_ob",
- "createdAt": "2022-12-24T00:00:00Z",
- "currency": "GBP",
- "status": "paid",
- "description": "string"
}
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
- Payload
{- "reference": "ref-123",
- "amount": "0.50",
- "bankAccount": "62b48c5b6ba2cd6a040b20a8",
- "customerName": "John Doe",
- "dueDate": "2024-01-24T00:00:00Z",
- "customerEmail": "example@gmail.com",
- "customerEmailCC": [
- "example@gmail.com"
], - "paymentMethod": "fena_ob",
- "description": "string",
- "integration": "62b48c5b6ba2cd6a040b20a8"
}
Response samples
- 200
- 401
- 403
- 404
- 500
{- "created": true,
- "result": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "reference": "ref-123",
- "amount": "0.50",
- "bankAccount": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "sortCode": "123456",
- "accountNumber": "12345678",
- "name": "Default account",
- "provider": "other",
- "isDefault": true,
- "status": "verified",
- "connectionType": "manual",
- "createdAt": "2022-12-24T00:00:00Z",
- "bankStatementAttachmentURL": "string",
- "bankConsentExpired": "day-30"
}, - "customerName": "John Doe",
- "dueDate": "2024-01-24T00:00:00Z",
- "customerEmail": "example@gmail.com",
- "customerEmailCC": [
- "example@gmail.com"
], - "paymentMethod": "fena_ob",
- "createdAt": "2022-12-24T00:00:00Z",
- "currency": "GBP",
- "status": "paid",
- "description": "string"
}
}
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
- Payload
{- "reference": "ref-123",
- "amount": "0.50",
- "bankAccount": "62b48c5b6ba2cd6a040b20a8",
- "customerName": "John Doe",
- "dueDate": "2024-01-24T00:00:00Z",
- "customerEmail": "example@gmail.com",
- "customerEmailCC": [
- "example@gmail.com"
], - "paymentMethod": "fena_ob",
- "description": "string",
- "integration": "62b48c5b6ba2cd6a040b20a8"
}
Response samples
- 200
- 401
- 403
- 404
- 500
{- "created": true,
- "result": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "reference": "ref-123",
- "amount": "0.50",
- "bankAccount": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "sortCode": "123456",
- "accountNumber": "12345678",
- "name": "Default account",
- "provider": "other",
- "isDefault": true,
- "status": "verified",
- "connectionType": "manual",
- "createdAt": "2022-12-24T00:00:00Z",
- "bankStatementAttachmentURL": "string",
- "bankConsentExpired": "day-30"
}, - "customerName": "John Doe",
- "dueDate": "2024-01-24T00:00:00Z",
- "customerEmail": "example@gmail.com",
- "customerEmailCC": [
- "example@gmail.com"
], - "paymentMethod": "fena_ob",
- "createdAt": "2022-12-24T00:00:00Z",
- "currency": "GBP",
- "status": "paid",
- "description": "string"
}
}
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
- 200
- 401
- 403
- 404
- 500
{- "created": true,
- "result": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "reference": "ref-123",
- "amount": "0.50",
- "bankAccount": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "sortCode": "123456",
- "accountNumber": "12345678",
- "name": "Default account",
- "provider": "other",
- "isDefault": true,
- "status": "verified",
- "connectionType": "manual",
- "createdAt": "2022-12-24T00:00:00Z",
- "bankStatementAttachmentURL": "string",
- "bankConsentExpired": "day-30"
}, - "customerName": "John Doe",
- "dueDate": "2024-01-24T00:00:00Z",
- "customerEmail": "example@gmail.com",
- "customerEmailCC": [
- "example@gmail.com"
], - "paymentMethod": "fena_ob",
- "createdAt": "2022-12-24T00:00:00Z",
- "currency": "GBP",
- "status": "paid",
- "description": "string"
}
}
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
- 200
- 401
- 403
- 404
- 500
{- "data": {
- "page": 1,
- "totalDocs": 100,
- "totalPages": 5,
- "limit": 25,
- "hasNextPage": true,
- "docs": [
- {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "reference": "ref-123",
- "amount": "0.50",
- "bankAccount": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "sortCode": "123456",
- "accountNumber": "12345678",
- "name": "Default account",
- "provider": "other",
- "isDefault": true,
- "status": "verified",
- "connectionType": "manual",
- "createdAt": "2022-12-24T00:00:00Z",
- "bankStatementAttachmentURL": "string",
- "bankConsentExpired": "day-30"
}, - "customerName": "John Doe",
- "dueDate": "2024-01-24T00:00:00Z",
- "customerEmail": "example@gmail.com",
- "customerEmailCC": [
- "example@gmail.com"
], - "paymentMethod": "fena_ob",
- "createdAt": "2022-12-24T00:00:00Z",
- "currency": "GBP",
- "status": "paid",
- "description": "string"
}
]
}
}
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
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
- Payload
{- "customerName": "John Doe",
- "dueDate": "2024-01-24T00:00:00Z",
- "customerEmail": "example@gmail.com",
- "customerEmailCC": [
- "example@gmail.com"
], - "description": "string"
}
Response samples
- 200
- 401
- 403
- 404
- 500
{- "saved": true,
- "result": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "reference": "ref-123",
- "amount": "0.50",
- "bankAccount": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "sortCode": "123456",
- "accountNumber": "12345678",
- "name": "Default account",
- "provider": "other",
- "isDefault": true,
- "status": "verified",
- "connectionType": "manual",
- "createdAt": "2022-12-24T00:00:00Z",
- "bankStatementAttachmentURL": "string",
- "bankConsentExpired": "day-30"
}, - "customerName": "John Doe",
- "dueDate": "2024-01-24T00:00:00Z",
- "customerEmail": "example@gmail.com",
- "customerEmailCC": [
- "example@gmail.com"
], - "paymentMethod": "fena_ob",
- "createdAt": "2022-12-24T00:00:00Z",
- "currency": "GBP",
- "status": "paid",
- "description": "string",
- "completedAt": "2022-12-24T00:00:00Z",
- "refundLink": "string",
- "refundQrCodeData": "string"
}
}
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
- 200
- 401
- 403
- 404
- 500
{- "saved": true,
- "result": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "reference": "ref-123",
- "amount": "0.50",
- "bankAccount": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "sortCode": "123456",
- "accountNumber": "12345678",
- "name": "Default account",
- "provider": "other",
- "isDefault": true,
- "status": "verified",
- "connectionType": "manual",
- "createdAt": "2022-12-24T00:00:00Z",
- "bankStatementAttachmentURL": "string",
- "bankConsentExpired": "day-30"
}, - "customerName": "John Doe",
- "dueDate": "2024-01-24T00:00:00Z",
- "customerEmail": "example@gmail.com",
- "customerEmailCC": [
- "example@gmail.com"
], - "paymentMethod": "fena_ob",
- "createdAt": "2022-12-24T00:00:00Z",
- "currency": "GBP",
- "status": "paid",
- "description": "string"
}
}
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
- 200
- 401
- 403
- 404
- 500
{- "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
- 200
- 401
- 403
- 404
- 500
{- "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
- Payload
{- "amount": "string",
- "payeeAccountInfo": {
- "name": "string",
- "externalAccountId": "string",
- "identification": "string",
- "email": "string"
}
}
Response samples
- 200
- 401
- 403
- 404
- 500
{- "saved": true,
- "result": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "reference": "ref-123",
- "amount": "0.50",
- "bankAccount": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "sortCode": "123456",
- "accountNumber": "12345678",
- "name": "Default account",
- "provider": "other",
- "isDefault": true,
- "status": "verified",
- "connectionType": "manual",
- "createdAt": "2022-12-24T00:00:00Z",
- "bankStatementAttachmentURL": "string",
- "bankConsentExpired": "day-30"
}, - "customerName": "John Doe",
- "dueDate": "2024-01-24T00:00:00Z",
- "customerEmail": "example@gmail.com",
- "customerEmailCC": [
- "example@gmail.com"
], - "paymentMethod": "fena_ob",
- "createdAt": "2022-12-24T00:00:00Z",
- "currency": "GBP",
- "status": "paid",
- "completedAt": "2022-12-24T00:00:00Z",
- "refundLink": "string",
- "refundQrCodeData": "string",
- "description": "string"
}
}
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
- Payload
{- "id": "string",
- "provider": "ob-natwest"
}
Response samples
- 200
- 404
- 500
{- "sucess": true,
- "data": {
- "authUrl": "string"
}
}