Skip to main content
Documentation Powered by Redocly

Payments and Recurring Payments Public APIs (1.1)

Download OpenAPI specification:Download

Payments and Recurring Payments Public APIs

Payments

Create a draft payment, which you can later proces

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

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

Reference number for your payment. Due to restrictions on reference length in most banks this field is limited to 12 characters and can only contain letters, numbers and dashes

amount
required
string
customerName
string
dueDate
object

JavaScript Date Object

attachmentUrl
string
customerEmail
string
customerEmailCC
string
customRedirectUrl
string

A custom redirect URL only for the current payment

type
string (PaymentTypes)
Enum: "link" "qr" "mobile"

Responses

Request samples

Content type
application/json
{
  • "invoiceRefNumber": "ref123",
  • "amount": "string",
  • "customerName": "string",
  • "dueDate": { },
  • "attachmentUrl": "string",
  • "customerEmail": "string",
  • "customerEmailCC": "string",
  • "customRedirectUrl": "string",
  • "type": "link"
}

Response samples

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

Create and process payment

Create and process payment

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

Reference number for your payment. Due to restrictions on reference length in most banks this field is limited to 12 characters and can only contain letters, numbers and dashes

amount
required
string
customerName
string
dueDate
object

JavaScript Date Object

attachmentUrl
string
customerEmail
string
customerEmailCC
string
customRedirectUrl
string

A custom redirect URL only for the current payment

type
string (PaymentTypes)
Enum: "link" "qr" "mobile"

Responses

Request samples

Content type
application/json
{
  • "invoiceRefNumber": "string",
  • "amount": "string",
  • "customerName": "string",
  • "dueDate": { },
  • "attachmentUrl": "string",
  • "customerEmail": "string",
  • "customerEmailCC": "string",
  • "customRedirectUrl": "string",
  • "type": "link"
}

Response samples

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

Get payment data

Get payment data

path Parameters
id
required
string
Example: 62b48c5b6ba2cd6a040b20a8

Mongoose Object ID of the payment

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

Responses

Response samples

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

Get list of all payments

Get list of all payments

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

Responses

Response samples

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

Edit payment data

Edit payment data

path Parameters
id
required
string
Example: 62b48c5b6ba2cd6a040b20a8

Mongoose Object ID of the payment

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

Mongoose Object ID

invoiceRefNumber
string
amount
string
customerName
string
dueDate
object

JavaScript Date Object

attachmentUrl
string
customerEmail
string
customerEmailCC
string
customRedirectUrl
string

A custom redirect URL only for the current payment

Responses

Request samples

Content type
application/json
{
  • "_id": "string",
  • "invoiceRefNumber": "string",
  • "amount": "string",
  • "customerName": "string",
  • "dueDate": { },
  • "attachmentUrl": "string",
  • "customerEmail": "string",
  • "customerEmailCC": "string",
  • "customRedirectUrl": "string"
}

Response samples

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

Process payment

Process payment

path Parameters
id
required
string
Example: 62b48c5b6ba2cd6a040b20a8

Mongoose Object ID of the payment

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

Responses

Response samples

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

Delete payment

Delete payment

path Parameters
id
required
string
Example: 62b48c5b6ba2cd6a040b20a8

Mongoose Object ID of the payment

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

Responses

Response samples

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

Refund payment

Refund payment

path Parameters
id
required
string
Example: 62b48c5b6ba2cd6a040b20a8

Mongoose Object ID of the payment

header Parameters
secret-key
required
string <uuid>
Example: 3858f642-e92f-431c-9d38-46d15efb7fba
integration-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": {
    }
}

Recurring payments

Create draft recurring payment

Create draft recurring payment

header Parameters
secret-key
required
string <uuid>
Example: 3858f642-e92f-431c-9d38-46d15efb7fba
integration-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 3 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
customerEmailCC
Array of strings

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",
  • "customerEmailCC": [
    ]
}

Response samples

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

Create and send recurring payment

Create and send recurring payment

header Parameters
secret-key
required
string <uuid>
Example: 3858f642-e92f-431c-9d38-46d15efb7fba
integration-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 3 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
customerEmailCC
Array of strings

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",
  • "customerEmailCC": [
    ]
}

Response samples

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

Get recurring payments data

Get recurring payments data

path Parameters
id
required
string
Example: 62b48c5b6ba2cd6a040b20a8

Mongoose Object ID of the payment

header Parameters
secret-key
required
string <uuid>
Example: 3858f642-e92f-431c-9d38-46d15efb7fba
integration-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",
  • "initialPayment": {
    },
  • "customerName": "John Doe",
  • "customerEmail": "email@example.com",
  • "customerEmailCC": [
    ],
  • "createdAt": "2022-12-24T00:00:00Z",
  • "currency": "string",
  • "link": "https://pay.fena.co/recurring-payments/?rp=8nj78XgqOGs5NmG6G8qy",
  • "qrCodeData": "string",
  • "actionsHistory": [
    ]
}

Get list of all recurring payments

Get list of all recurring payments

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

Responses

Response samples

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

Edit recurring payments

Edit recurring payments

path Parameters
id
required
string
Example: 62b48c5b6ba2cd6a040b20a8

Mongoose Object ID of the payment

header Parameters
secret-key
required
string <uuid>
Example: 3858f642-e92f-431c-9d38-46d15efb7fba
integration-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 3 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
customerEmailCC
Array of strings

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",
  • "customerEmailCC": [
    ]
}

Response samples

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

Send recurring payment

Send recurring payment

path Parameters
id
required
string
Example: 62b48c5b6ba2cd6a040b20a8

Mongoose Object ID of the payment

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

Responses

Response samples

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

Delete recurring payments

Delete recurring payments

path Parameters
id
required
string
Example: 62b48c5b6ba2cd6a040b20a8

Mongoose Object ID of the payment

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

Responses

Response samples

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

Get list of payments of recurring payment

Get list of payments of recurring payment

path Parameters
id
required
string
Example: 62b48c5b6ba2cd6a040b20a8

Mongoose Object ID of the payment

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

Responses

Response samples

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

Common

Get list of all accepted providers

Get list of all accepted providers

Responses

Response samples

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

Initiate payment

Initiate payment

Request Body schema: application/json
type
string

'payment' or 'recurring payment'

id
string

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

externalId
any (ProviderExternalIDs)
Enum: "ob-bos-business" "ob-barclays-personal" "ob-bos-personal" "ob-barclays-business" "ob-halifax-personal" "ob-hsbc-personal" "ob-hsbc-business" "ob-first-direct" "ob-natwest" "ob-nationwide" "ob-monzo" "ob-lloyds-personal" "ob-lloyds-business" "ob-revolut" "ob-ulster" "ob-rbs" "ob-santander" "ob-tsb" "ob-starling" "other" "ob-virgin-money" "ob-tide" "ob-mettle" "ob-chase"

External ID of the provider

Responses

Request samples

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

Response samples

Content type
application/json; charset=utf-8
Example
"ApiToken is expired"

Get bank account connection type.

Returns the connection type of the bank account associated with the current integration.

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

Responses

Response samples

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