Recurring Payments (1.0.1)
Download OpenAPI specification:Download
Recurring Payments API requests specification
Create draft recurring payment
Create draft recurring payment which can be processed later
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 <= 12 characters ^[a-z0-9-]+$ |
recurringAmount required | string^[0-9]*.[0-9]{2}$ The amount of money that will come to your bank account from the client during the active period of regular payments |
recurringPaymentDate required | string Javascript date. First payment date of recurring payment. Note: Due to banks requirements , the first payment date must be 6 working days in the future. |
numberOfPayments required | integer Expected number of payments. Set 0 for indefinite |
frequency required | string Enum: "one_week" "one_month" "three_months" "one_year" Time interval between payments. |
initialPaymentAmount | string^[0-9]*.[0-9]{2}$ Set if you want to request single immediate payment |
customerName | string |
customerEmail | string |
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. Please note that payment status update events are not supported for sandbox bank accounts, manually added bank accounts, or ob-nationwide accounts. For recurring payments set up with such accounts, Fena only knows when the setup is completed. |
integration | string 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": "12345abc",
- "recurringAmount": "0.50",
- "recurringPaymentDate": "2022-12-24T00:00:00Z",
- "numberOfPayments": 0,
- "frequency": "one_week",
- "initialPaymentAmount": "0.50",
- "customerName": "John Doe",
- "customerEmail": "email@example.com",
- "bankAccount": "62b48c5b6ba2cd6a040b20a8",
- "integration": "62b48c5b6ba2cd6a040b20a8"
}
Response samples
- 201
- 401
- 403
- 404
- 500
{- "created": true,
- "result": {
- "id": "3858f642-e92f-431c-9d38-46d15efb7fba",
- "invoiceRefNumber": "ref-123456",
- "recurringAmount": "0.50",
- "firstPaymentDate": "2022-12-24T00:00:00Z",
- "finalPaymentDate": "2022-12-24T00:00:00Z",
- "expectedNumberOfPayments": 0,
- "frequency": "one_week",
- "status": "sent",
- "transactions": [
- {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "amount": "0.50",
- "status": "created",
- "createdAt": "2022-12-24T00:00:00Z",
- "parentEntityType": "Payment",
- "parentEntityId": "62b48c5b6ba2cd6a040b20a8",
- "isSandbox": false,
- "direction": "incoming",
- "expectedCompletedDate": "2024-01-24T00:00:00Z",
- "completedAt": "2022-12-24T00:00:00Z",
- "reference": "ref-123"
}
], - "initialPayment": {
- "id": "string",
- "status": "paid",
- "reference": "ref-123",
- "amount": "0.50",
- "dueDate": "2022-12-24T00:00:00Z",
- "createdAt": "2022-12-24T00:00:00Z",
- "currency": "GBP"
}, - "customerName": "John Doe",
- "customerEmail": "email@example.com",
- "createdAt": "2022-12-24T00:00:00Z",
- "currency": "string",
- "qrCodeData": "string",
- "bankAccount": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "sortCode": "123456",
- "accountNumber": "12345678",
- "name": "Default account",
- "provider": "other",
- "isDefault": true,
- "status": "verified",
- "creationType": "data_api",
- "createdAt": "2022-12-24T00:00:00Z",
- "bankStatementAttachmentURL": "string",
- "consentID": "string",
- "bankConsentExpired": "day-30"
}, - "integration": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "name": "your-app",
- "fenaPaymentPageRedirectEnabled": true,
- "isRetryWebhookEnabled": true
}
}
}
Create and process recurring payment
Create and process recurring payment. Recurring payment and initial payment(if present) status will be 'sent' and 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 <= 12 characters ^[a-z0-9-]+$ |
recurringAmount required | string^[0-9]*.[0-9]{2}$ The amount of money that will come to your bank account from the client during the active period of regular payments |
recurringPaymentDate required | string Javascript date. First payment date of recurring payment. Note: Due to banks requirements , the first payment date must be 6 working days in the future. |
numberOfPayments required | integer Expected number of payments. Set 0 for indefinite |
frequency required | string Enum: "one_week" "one_month" "three_months" "one_year" Time interval between payments. |
initialPaymentAmount | string^[0-9]*.[0-9]{2}$ Set if you want to request single immediate payment |
customerName | string |
customerEmail | string |
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. Please note that payment status update events are not supported for sandbox bank accounts, manually added bank accounts, or ob-nationwide accounts. For recurring payments set up with such accounts, Fena only knows when the setup is completed. |
integration | string 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": "12345abc",
- "recurringAmount": "0.50",
- "recurringPaymentDate": "2022-12-24T00:00:00Z",
- "numberOfPayments": 0,
- "frequency": "one_week",
- "initialPaymentAmount": "0.50",
- "customerName": "John Doe",
- "customerEmail": "email@example.com",
- "bankAccount": "62b48c5b6ba2cd6a040b20a8",
- "integration": "62b48c5b6ba2cd6a040b20a8"
}
Response samples
- 201
- 401
- 403
- 404
- 500
{- "created": true,
- "result": {
- "id": "3858f642-e92f-431c-9d38-46d15efb7fba",
- "invoiceRefNumber": "ref-123456",
- "recurringAmount": "0.50",
- "firstPaymentDate": "2022-12-24T00:00:00Z",
- "finalPaymentDate": "2022-12-24T00:00:00Z",
- "expectedNumberOfPayments": 0,
- "frequency": "one_week",
- "status": "sent",
- "transactions": [
- {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "amount": "0.50",
- "status": "created",
- "createdAt": "2022-12-24T00:00:00Z",
- "parentEntityType": "Payment",
- "parentEntityId": "62b48c5b6ba2cd6a040b20a8",
- "isSandbox": false,
- "direction": "incoming",
- "expectedCompletedDate": "2024-01-24T00:00:00Z",
- "completedAt": "2022-12-24T00:00:00Z",
- "reference": "ref-123"
}
], - "initialPayment": {
- "id": "string",
- "status": "paid",
- "reference": "ref-123",
- "amount": "0.50",
- "dueDate": "2022-12-24T00:00:00Z",
- "createdAt": "2022-12-24T00:00:00Z",
- "currency": "GBP"
}, - "customerName": "John Doe",
- "customerEmail": "email@example.com",
- "createdAt": "2022-12-24T00:00:00Z",
- "currency": "string",
- "qrCodeData": "string",
- "bankAccount": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "sortCode": "123456",
- "accountNumber": "12345678",
- "name": "Default account",
- "provider": "other",
- "isDefault": true,
- "status": "verified",
- "creationType": "data_api",
- "createdAt": "2022-12-24T00:00:00Z",
- "bankStatementAttachmentURL": "string",
- "consentID": "string",
- "bankConsentExpired": "day-30"
}, - "integration": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "name": "your-app",
- "fenaPaymentPageRedirectEnabled": true,
- "isRetryWebhookEnabled": true
}
}
}
Get recurring payment
Get recurring payments data by 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
{- "id": "3858f642-e92f-431c-9d38-46d15efb7fba",
- "invoiceRefNumber": "ref-123456",
- "recurringAmount": "0.50",
- "firstPaymentDate": "2022-12-24T00:00:00Z",
- "finalPaymentDate": "2022-12-24T00:00:00Z",
- "expectedNumberOfPayments": 0,
- "frequency": "one_week",
- "status": "sent",
- "transactions": [
- {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "amount": "0.50",
- "status": "created",
- "createdAt": "2022-12-24T00:00:00Z",
- "parentEntityType": "Payment",
- "parentEntityId": "62b48c5b6ba2cd6a040b20a8",
- "isSandbox": false,
- "direction": "incoming",
- "expectedCompletedDate": "2024-01-24T00:00:00Z",
- "completedAt": "2022-12-24T00:00:00Z",
- "reference": "ref-123"
}
], - "initialPayment": {
- "id": "string",
- "status": "paid",
- "reference": "ref-123",
- "amount": "0.50",
- "dueDate": "2022-12-24T00:00:00Z",
- "createdAt": "2022-12-24T00:00:00Z",
- "currency": "GBP"
}, - "customerName": "John Doe",
- "customerEmail": "email@example.com",
- "createdAt": "2022-12-24T00:00:00Z",
- "currency": "string",
- "qrCodeData": "string",
- "bankAccount": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "sortCode": "123456",
- "accountNumber": "12345678",
- "name": "Default account",
- "provider": "other",
- "isDefault": true,
- "status": "verified",
- "creationType": "data_api",
- "createdAt": "2022-12-24T00:00:00Z",
- "bankStatementAttachmentURL": "string",
- "consentID": "string",
- "bankConsentExpired": "day-30"
}, - "integration": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "name": "your-app",
- "fenaPaymentPageRedirectEnabled": true,
- "isRetryWebhookEnabled": true
}
}
List recurring payments
Get list of recurring payments
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 |
Responses
Response samples
- 200
- 401
- 403
- 404
- 500
{- "data": {
- "page": 1,
- "totalDocs": 100,
- "totalPages": 5,
- "limit": 25,
- "hasNextPage": true,
- "docs": [
- {
- "id": "3858f642-e92f-431c-9d38-46d15efb7fba",
- "invoiceRefNumber": "ref-123456",
- "recurringAmount": "0.50",
- "firstPaymentDate": "2022-12-24T00:00:00Z",
- "finalPaymentDate": "2022-12-24T00:00:00Z",
- "expectedNumberOfPayments": 0,
- "frequency": "one_week",
- "status": "sent",
- "transactions": [
- {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "amount": "0.50",
- "status": "created",
- "createdAt": "2022-12-24T00:00:00Z",
- "parentEntityType": "Payment",
- "parentEntityId": "62b48c5b6ba2cd6a040b20a8",
- "isSandbox": false,
- "direction": "incoming",
- "expectedCompletedDate": "2024-01-24T00:00:00Z",
- "completedAt": "2022-12-24T00:00:00Z",
- "reference": "ref-123"
}
], - "initialPayment": {
- "id": "string",
- "status": "paid",
- "reference": "ref-123",
- "amount": "0.50",
- "dueDate": "2022-12-24T00:00:00Z",
- "createdAt": "2022-12-24T00:00:00Z",
- "currency": "GBP"
}, - "customerName": "John Doe",
- "customerEmail": "email@example.com",
- "createdAt": "2022-12-24T00:00:00Z",
- "currency": "string",
- "qrCodeData": "string",
- "bankAccount": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "sortCode": "123456",
- "accountNumber": "12345678",
- "name": "Default account",
- "provider": "other",
- "isDefault": true,
- "status": "verified",
- "creationType": "data_api",
- "createdAt": "2022-12-24T00:00:00Z",
- "bankStatementAttachmentURL": "string",
- "consentID": "string",
- "bankConsentExpired": "day-30"
}, - "integration": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "name": "your-app",
- "fenaPaymentPageRedirectEnabled": true,
- "isRetryWebhookEnabled": true
}
}
]
}
}
Edit recurring payment
Edit recurring 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
reference required | string <= 12 characters ^[a-z0-9-]+$ |
recurringAmount required | string^[0-9]*.[0-9]{2}$ The amount of money that will come to your bank account from the client during the active period of regular payments |
recurringPaymentDate required | string Javascript date. First payment date of recurring payment. Note: Due to banks requirements , the first payment date must be 6 working days in the future. |
numberOfPayments required | integer Expected number of payments. Set 0 for indefinite |
frequency required | string Enum: "one_week" "one_month" "three_months" "one_year" Time interval between payments. |
initialPaymentAmount | string^[0-9]*.[0-9]{2}$ Set if you want to request single immediate payment |
customerName | string |
customerEmail | string |
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. Please note that payment status update events are not supported for sandbox bank accounts, manually added bank accounts, or ob-nationwide accounts. For recurring payments set up with such accounts, Fena only knows when the setup is completed. |
integration | string (MerchantIntegrationID) 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": "12345abc",
- "recurringAmount": "0.50",
- "recurringPaymentDate": "2022-12-24T00:00:00Z",
- "numberOfPayments": 0,
- "frequency": "one_week",
- "initialPaymentAmount": "0.50",
- "customerName": "John Doe",
- "customerEmail": "email@example.com",
- "bankAccount": "62b48c5b6ba2cd6a040b20a8",
- "integration": "62b48c5b6ba2cd6a040b20a8"
}
Response samples
- 200
- 401
- 403
- 404
- 500
{- "saved": true,
- "result": {
- "reference": "12345abc",
- "recurringAmount": "0.50",
- "recurringPaymentDate": "2022-12-24T00:00:00Z",
- "numberOfPayments": 0,
- "frequency": "one_week",
- "initialPaymentAmount": "0.50",
- "customerName": "John Doe",
- "customerEmail": "email@example.com",
- "bankAccount": "62b48c5b6ba2cd6a040b20a8",
- "integration": "62b48c5b6ba2cd6a040b20a8"
}
}
Process draft recurring payment by ID
Process draft recurring payment. Recurrin payment and initial payment(if present) status will be changed to 'send' and 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 |
Responses
Response samples
- 200
- 401
- 403
- 404
- 500
{- "saved": true,
- "result": {
- "id": "3858f642-e92f-431c-9d38-46d15efb7fba",
- "invoiceRefNumber": "ref-123456",
- "recurringAmount": "0.50",
- "firstPaymentDate": "2022-12-24T00:00:00Z",
- "finalPaymentDate": "2022-12-24T00:00:00Z",
- "expectedNumberOfPayments": 0,
- "frequency": "one_week",
- "status": "sent",
- "transactions": [
- {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "amount": "0.50",
- "status": "created",
- "createdAt": "2022-12-24T00:00:00Z",
- "parentEntityType": "Payment",
- "parentEntityId": "62b48c5b6ba2cd6a040b20a8",
- "isSandbox": false,
- "direction": "incoming",
- "expectedCompletedDate": "2024-01-24T00:00:00Z",
- "completedAt": "2022-12-24T00:00:00Z",
- "reference": "ref-123"
}
], - "initialPayment": {
- "id": "string",
- "status": "paid",
- "reference": "ref-123",
- "amount": "0.50",
- "dueDate": "2022-12-24T00:00:00Z",
- "createdAt": "2022-12-24T00:00:00Z",
- "currency": "GBP"
}, - "customerName": "John Doe",
- "customerEmail": "email@example.com",
- "createdAt": "2022-12-24T00:00:00Z",
- "currency": "string",
- "qrCodeData": "string",
- "bankAccount": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "sortCode": "123456",
- "accountNumber": "12345678",
- "name": "Default account",
- "provider": "other",
- "isDefault": true,
- "status": "verified",
- "creationType": "data_api",
- "createdAt": "2022-12-24T00:00:00Z",
- "bankStatementAttachmentURL": "string",
- "consentID": "string",
- "bankConsentExpired": "day-30"
}, - "integration": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "name": "your-app",
- "fenaPaymentPageRedirectEnabled": true,
- "isRetryWebhookEnabled": true
}
}
}
Delete recurring payment. Active or paid recurring
Delete recurring payment. Active or paid recurring 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
}
Initiate recurring payment
Initiate recurring payment
Request Body schema: application/json
type | string recurring |
id | string Hashed ID from the payment link (the one after rp?=) |
provider | string Selected provider |
Responses
Request samples
- Payload
{- "type": "recurring",
- "id": "string",
- "provider": "string"
}
Response samples
- 401
- 403
- 404
- 500
"Unauthorized"
Response samples
- 200
- 500
{- "data": [
- {
- "_id": "62b48c5b6ba2cd6a040b20a8",
- "name": "NatWest",
- "logo": "string",
- "externalId": "ob-natwest",
- "countryId": "GB",
- "createdAt": "2021-09-01T12:00:00.000Z",
- "deletedAt": null
}
]
}
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.
Webhook for recurring payment events Webhook
Webhook for recurring payment events. Webhook will be sent to merchant integration webhook URL if integration is present. Please note that payment status update events are not supported for sandbox bank accounts, manually added bank accounts, or ob-nationwide accounts. For recurring payments set up with such accounts, Fena only knows when the setup is completed.
Request Body schema: application/json
eventName | string Value: "status-update" The main status of the recurring payment has changed. |
eventScope | string (WebhookEventScope) Value: "recurring-payments" The scope of the webhook |
id | string |
invoiceRefNumber | string <= 12 characters ^[a-z0-9-]+$ |
recurringAmount | string^[0-9]*.[0-9]{2}$ The amount of money that will come to your bank account from the client during the active period of regular payments |
firstPaymentDate | string Javascript date. First payment date of recurring payment. Note: Due to banks requirements , the first payment date must be 3 working days in the future. |
finalPaymentDate | string Javascript date. Final payment date of recurring payment. Calculated date of final payment. If numberOfPayments has been set |
expectedNumberOfPayments | integer Expected number of payments. Set 0 for indefinite |
frequency | string Enum: "one_week" "one_month" "three_months" "one_year" Time interval between payments. |
status | string Enum: "draft" "sent" "active" "paid" "rejected" "warning" "cancelled" "overdue" Draft - draft recurring payments. Sent - link for customer has been generated and can be provided to a customer.Active - The customer successfully set the recurring payment and it is in progress. Paid - All payments have been fully paid Rejected - recurring payments set up has been failed. Warning - one of the payments didn’t arrive on the expected date or amount of money was less than the recurring amount. Cancelled - payment has been cancelled by customer or user set status as cancelled manually.Overdue - link for payment initiation is expired. |
Array of objects (Transaction) [ items ] | |
object (RecurringInitialPaymentResult) | |
customerName | string |
customerEmail | string |
createdAt | string |
currency | string |
link | string payment link |
qrCodeData | string |
object (BankAccountData) | |
object (IntegrationData) |
Responses
Request samples
- Payload
{- "eventName": "status-update",
- "eventScope": "recurring-payments",
- "id": "3858f642-e92f-431c-9d38-46d15efb7fba",
- "invoiceRefNumber": "ref-123456",
- "recurringAmount": "0.50",
- "firstPaymentDate": "2022-12-24T00:00:00Z",
- "finalPaymentDate": "2022-12-24T00:00:00Z",
- "expectedNumberOfPayments": 0,
- "frequency": "one_week",
- "status": "sent",
- "transactions": [
- {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "amount": "0.50",
- "status": "created",
- "createdAt": "2022-12-24T00:00:00Z",
- "parentEntityType": "Payment",
- "parentEntityId": "62b48c5b6ba2cd6a040b20a8",
- "isSandbox": false,
- "direction": "incoming",
- "expectedCompletedDate": "2024-01-24T00:00:00Z",
- "completedAt": "2022-12-24T00:00:00Z",
- "reference": "ref-123"
}
], - "initialPayment": {
- "id": "string",
- "status": "paid",
- "reference": "ref-123",
- "amount": "0.50",
- "dueDate": "2022-12-24T00:00:00Z",
- "createdAt": "2022-12-24T00:00:00Z",
- "currency": "GBP"
}, - "customerName": "John Doe",
- "customerEmail": "email@example.com",
- "createdAt": "2022-12-24T00:00:00Z",
- "currency": "string",
- "qrCodeData": "string",
- "bankAccount": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "sortCode": "123456",
- "accountNumber": "12345678",
- "name": "Default account",
- "provider": "other",
- "isDefault": true,
- "status": "verified",
- "creationType": "data_api",
- "createdAt": "2022-12-24T00:00:00Z",
- "bankStatementAttachmentURL": "string",
- "consentID": "string",
- "bankConsentExpired": "day-30"
}, - "integration": {
- "id": "62b48c5b6ba2cd6a040b20a8",
- "name": "your-app",
- "fenaPaymentPageRedirectEnabled": true,
- "isRetryWebhookEnabled": true
}
}