Skip to main content
Documentation Powered by Redocly

Recurring Payments (1.1.0)

Download OpenAPI specification:Download

Recurring Payments API requests specification

Recurring payments

Recurring payments Public 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.

Array of objects[ items ]
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

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

Response samples

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

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.

Array of objects[ items ]
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

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

Response samples

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

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

Content type
application/json; charset=utf-8
{
  • "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": [
    ],
  • "initialPayment": {
    },
  • "customerName": "John Doe",
  • "customerEmail": "email@example.com",
  • "createdAt": "2022-12-24T00:00:00Z",
  • "currency": "string",
  • "link": "https://pay.fena.co/payments/recurring/?rp=8nj78XgqOGs5NmG6G8qy",
  • "qrCodeData": "string",
  • "bankAccount": {
    },
  • "notes": [
    ],
  • "integration": {}
}

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

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

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.

Array of objects (PaymentNoteBody) [ items ]
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

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

Response samples

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

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

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

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

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

Recurring 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" "restricted"

Note visibility. Public notes are visible to the customer in emails. Private notes are visible only to the managed company user in the Fena Portal and API. Restricted notes are visible only in the API.

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

Note visibility. Public notes are visible to the customer in emails. Private notes are visible only to the managed company user in the Fena Portal and API. Restricted notes are visible only in the API.

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 recurring payment

Initiate recurring payment. This endpoint is used to initiate a recurring payment from the customer side. Please note that if recurring payment has initial payment, then you will need to call this endpoint twice. First time to initiate initial payment and after it is completed, call this endpoint to 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 id

Responses

Request samples

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

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.

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
One of
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)
Array of objects[ items ]
object (IntegrationData)

Responses

Request samples

Content type
application/json
Example
{
  • "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": [
    ],
  • "initialPayment": {
    },
  • "customerName": "John Doe",
  • "customerEmail": "email@example.com",
  • "createdAt": "2022-12-24T00:00:00Z",
  • "currency": "string",
  • "link": "https://pay.fena.co/payments/recurring/?rp=8nj78XgqOGs5NmG6G8qy",
  • "qrCodeData": "string",
  • "bankAccount": {
    },
  • "notes": [
    ],
  • "integration": {}
}