> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qonto.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a SEPA recurring transfer
> OAuth scope: `payment.write`
This operation requires [Strong Customer Authentication](/api-reference/business-api/authentication/sca/sca-flows).
Example of SCA usage: [Postman visual flow](https://www.postman.com/qontoteam/workspace/qonto-public-api/flow/6670429eb7bd63003156bd57)
Creates a new SEPA recurring transfer for a beneficiary. You can either provide a `beneficiary_id` for a known beneficiary or `beneficiary` data which will create an untrusted beneficiary on the fly.
**Note**:
- if a beneficiary with the same IBAN already exists, the provided details (such as name) will be updated;
- this endpoint is not trusting the beneficiary - you can trust a beneficiary through the Qonto app (for more details, please refer to [this article](https://support-de.qonto.com/hc/en-us/articles/23949206250641-How-can-I-mark-a-payee-as-trustworthy#h_925061f25d)) or through [this endpoint](/api-reference/business-api/payments-transfers/sepa-transfers/beneficiaries/sepa-beneficiaries/trust) (available for Embed partners only).
The subsequent transfer will be executed according to the specified frequency between the first and last execution dates. If no last execution date is provided the transfer will be executed indefinitely.
For recurring transfers above 30,000 EUR, at least one attachment is required.
## OpenAPI
````yaml POST /v2/sepa/recurring_transfers
openapi: 3.1.1
info:
version: v2
title: Qonto
servers:
- url: https://thirdparty.qonto.com
description: Production URL
- url: https://thirdparty-sandbox.staging.qonto.co
description: Sandbox URL
security:
- OAuth:
- organization.read
- membership.read
- membership.write
- attachment.write
- internal_transfer.write
- payment.write
- supplier_invoice.write
- supplier_invoice.read
- client_invoices.read
- client_invoice.write
- client.read
- client.write
- product.read
- product.write
- request_review.write
- request_review.read
- team.read
- team.write
- request_transfers.write
- insurance_contract.read
- insurance_contract.write
- card.read
- card.write
- bank_account.write
- beneficiary.trust
- webhook
- payment_link.write
- payment_link.read
- sepa_direct_debit.read
- sepa_direct_debit.write
- terminal.read
- terminal.write
- SecretKey: []
paths:
/v2/sepa/recurring_transfers:
parameters:
- $ref: '#/components/parameters/X-Qonto-Staging-Token'
post:
tags:
- SEPA Transfers
summary: Create a SEPA recurring transfer
description: >
OAuth scope: `payment.write`
This operation requires [Strong Customer
Authentication](/api-reference/business-api/authentication/sca/sca-flows).
Example of SCA usage: [Postman visual flow](https://www.postman.com/qontoteam/workspace/qonto-public-api/flow/6670429eb7bd63003156bd57)
Creates a new SEPA recurring transfer for a beneficiary. You can either
provide a `beneficiary_id` for a known beneficiary or `beneficiary` data
which will create an untrusted beneficiary on the fly.
**Note**:
- if a beneficiary with the same IBAN already exists, the provided
details (such as name) will be updated;
- this endpoint is not trusting the beneficiary - you can trust a
beneficiary through the Qonto app (for more details, please refer to
[this
article](https://support-de.qonto.com/hc/en-us/articles/23949206250641-How-can-I-mark-a-payee-as-trustworthy#h_925061f25d))
or through [this
endpoint](/api-reference/business-api/payments-transfers/sepa-transfers/beneficiaries/sepa-beneficiaries/trust)
(available for Embed partners only).
The subsequent transfer will be executed according to the specified
frequency between the first and last execution dates. If no last
execution date is provided the transfer will be executed indefinitely.
For recurring transfers above 30,000 EUR, at least one attachment is
required.
operationId: createSepaRecurringTransfer
parameters:
- $ref: '#/components/parameters/X-Qonto-2fa-Preference'
- $ref: '#/components/parameters/X-Qonto-Idempotency-Key'
- $ref: '#/components/parameters/X-Qonto-Sca-Session-Token'
- $ref: '#/components/parameters/X-Qonto-MFA'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSepaRecurringTransferRequest'
examples:
valid:
value:
vop_proof_token: proof_1234567890abcdef
recurring_transfer:
beneficiary_id: 66b7e300-0126-4905-9688-27b445a48c4e
bank_account_id: 420e13ac-9d3e-4c11-93a1-0c3c8304f2df
reference: Lease payment
amount: '1100.50'
frequency: monthly
first_execution_date: '2025-04-22'
last_execution_date: '2026-08-21'
note: Lease payment for offices in Paris
attachment_ids:
- 394f77f1-0d2c-46fb-8a7e-a959dbdeee63
responses:
'200':
description: SEPA recurring transfer created successfully
content:
application/json:
schema:
type: object
required:
- recurring_transfer
properties:
recurring_transfer:
$ref: '#/components/schemas/SepaRecurringTransfer'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseBody'
examples:
with invalid dates:
value:
errors:
- code: invalid_date_after_reference
detail: >-
first_execution_date must be before
last_execution_date
source:
pointer: /recurring_transfer/first_execution_date
with invalid amount:
value:
errors:
- code: invalid
detail: amount must be greater than 0
source:
pointer: /recurring_transfer/amount
with recurring transfer amount above 30000 EUR:
value:
errors:
- code: attachment_required
detail: >-
The recurring transfer must have at least one
attachment
source:
pointer: /recurring_transfer/attachment_ids
with unknown beneficiary:
value:
errors:
- code: beneficiary_not_found
detail: >-
Beneficiary with
id=66b7e300-0126-4905-9688-27b445a48c4e not found
source:
pointer: /recurring_transfer/beneficiary_id
with unknown bank account:
value:
errors:
- code: bank_account_not_found
detail: >-
BankAccount with
id=420e13ac-9d3e-4c11-93a1-0c3c8304f2df not found
source:
pointer: /recurring_transfer/bank_account_id
with an internal transfer:
value:
errors:
- code: transfer_to_same_organization
detail: >-
The beneficiary bank account belongs to the same
organization. Please use our internal transfers
endpoints instead.
source:
pointer: /recurring_transfer/beneficiary_id
invalid vop proof token:
value:
errors:
- code: vop_proof_token_invalid
detail: VOP proof token is invalid
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/UnauthorizedError'
examples:
missing vop proof token:
value:
errors:
- code: vop_proof_token_missing
detail: VOP proof token is required
authorization_header_missing:
value:
errors:
- code: authorization_header_missing
detail: authorization header missing
authorization_token_invalid:
value:
errors:
- code: authorization_token_invalid
detail: authorization token invalid
'403':
$ref: '#/components/responses/403-Forbidden'
description: Forbidden
security:
- OAuth:
- payment.write
components:
parameters:
X-Qonto-Staging-Token:
name: X-Qonto-Staging-Token
in: header
description: >-
Required only for Sandbox API requests; to get one, please sign up to
the [Developer Portal](https://developers.qonto.com/).
schema:
type: string
X-Qonto-2fa-Preference:
name: X-Qonto-2fa-Preference
in: header
description: >-
Learn more in [Strong Customer
Authentication](/api-reference/business-api/authentication/sca/sca-flows).
schema:
type: string
enum:
- paired-device
- passkey
- mock
- sms-otp
default: paired-device
X-Qonto-Idempotency-Key:
name: X-Qonto-Idempotency-Key
in: header
required: true
description: >-
Learn more in [Idempotent
Requests](/get-started/general/idempotent-requests).
schema:
type: string
example: 123e4567-e89b-12d3-a456-426614174000
X-Qonto-Sca-Session-Token:
name: X-Qonto-Sca-Session-Token
in: header
description: >-
Learn more in [Strong Customer
Authentication](/api-reference/business-api/authentication/sca/sca-flows).
schema:
type: string
X-Qonto-MFA:
name: X-Qonto-MFA
in: header
description: >-
Learn more in the [SMS OTP
Flow](/api-reference/business-api/authentication/sca/sca-flows#sms-otp-flow).
schema:
type: string
schemas:
CreateSepaRecurringTransferRequest:
type: object
required:
- recurring_transfer
- vop_proof_token
properties:
vop_proof_token:
type: string
description: >-
Proof token from a payee verification attempt or skip verification
request. Use the token from [verify
payee](/api-reference/business-api/payments-transfers/sepa-transfers/verify-payee#tag/Verify-SEPA-Payee/operation/verifyPayee).
example: proof_1234567890abcdef
recurring_transfer:
type: object
required:
- bank_account_id
- reference
- amount
- frequency
- first_execution_date
properties:
beneficiary_id:
type:
- string
- 'null'
format: uuid
description: The ID of the SEPA beneficiary
beneficiary:
type:
- object
- 'null'
required:
- name
- iban
properties:
name:
type: string
description: The name of the beneficiary
example: Alice In Wonderland
iban:
type: string
description: The IBAN of the beneficiary
example: DE91100000000123456789
bic:
type: string
description: The BIC of the beneficiary
example: DEUTDEDDXXX
email:
type: string
description: The email of the beneficiary
example: beneficiary@example.com
activity_tag:
$ref: '#/components/schemas/ActivityTagEnum'
bank_account_id:
type: string
description: ID of the bank account to debit from
reference:
type: string
description: Payment reference (max 140 characters)
maxLength: 140
amount:
type: string
description: Amount in EUR with up to 2 decimal places
pattern: ^-?[0-9]+(\.[0-9]{1,2})?$
frequency:
type: string
description: Frequency of the recurring transfer
enum:
- weekly
- monthly
- quarterly
- half_yearly
- yearly
first_execution_date:
type: string
format: date
description: First execution date (must be in the future)
last_execution_date:
type: string
format: date
description: >-
Last execution date (must be in the future and after
first_execution_date)
note:
type: string
description: Optional note (max 140 characters)
maxLength: 140
attachment_ids:
type: array
description: Array of attachment IDs (max 5)
items:
type: string
maxItems: 5
SepaRecurringTransfer:
type: object
required:
- id
- initiator_id
- bank_account_id
- amount
- amount_cents
- amount_currency
- beneficiary_id
- reference
- note
- first_execution_date
- last_execution_date
- next_execution_date
- frequency
- created_at
- updated_at
properties:
id:
type: string
format: uuid
initiator_id:
type: string
format: uuid
description: ID of the membership that initiated the transfer
bank_account_id:
type: string
format: uuid
description: ID of the bank account to debit from
status:
type: string
amount:
type: number
format: float
example: 1100.5
amount_cents:
type: integer
example: 110050
amount_currency:
type: string
enum:
- EUR
beneficiary_id:
type: string
format: uuid
reference:
type: string
example: Lease payment
note:
type: string
example: Lease payment for offices in Paris
first_execution_date:
type: string
format: date
example: '2025-04-22'
last_execution_date:
type: string
format: date
example: '2026-08-21'
next_execution_date:
type: string
format: date
example: '2025-05-22'
frequency:
type: string
enum:
- weekly
- monthly
- quarterly
- half_yearly
- yearly
created_at:
type: string
format: date-time
example: '2025-04-22T12:00:00Z'
updated_at:
type: string
format: date-time
example: '2025-04-22T12:00:00Z'
BadRequestResponseBody:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/BadRequestError'
required:
- errors
UnauthorizedError:
type: object
properties:
code:
type: string
description: Error code.
detail:
type: string
description: Human readable error that explains error `code`.
required:
- code
- detail
x-examples:
Invalid credentials:
code: unauthorized
detail: Invalid credentials
ActivityTagEnum:
type:
- string
- 'null'
enum:
- atm
- fallback
- fees
- finance
- food_and_grocery
- gas_station
- hardware_and_equipment
- hotel_and_lodging
- insurance
- it_and_electronics
- legal_and_accounting
- logistics
- manufacturing
- marketing
- office_rental
- office_supply
- online_service
- other_expense
- other_income
- other_service
- pending
- refund
- restaurant_and_bar
- sales
- salary
- subscription
- tax
- transport
- treasury_and_interco
- utility
- voucher
BadRequestError:
type: object
properties:
code:
type: string
description: Error code.
detail:
type: string
description: Human readable error that explains error `code`.
source:
type: object
properties:
pointer:
type: string
description: >-
The property in the request body that caused the error
(optional).
parameter:
type: string
description: The query parameter that caused the error (optional).
required:
- code
- detail
x-examples:
Authorization field missing:
code: bad_request
detail: Authorization field missing
ForbiddenResponseBody:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ForbiddenError'
required:
- errors
ForbiddenError:
type: object
properties:
code:
type: string
description: Error code.
detail:
type: string
description: Human readable error that explains error `code`.
required:
- code
- detail
x-examples:
Insufficient permissions:
code: forbidden
detail: User does not have sufficient permissions for this action.
responses:
403-Forbidden:
description: Returns a forbidden error.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenResponseBody'
examples:
Insufficient permissions:
value:
errors:
- code: forbidden
detail: User does not have sufficient permissions for this action.
securitySchemes:
OAuth:
type: oauth2
description: >
Bearer authorization header: `Bearer `, where `` is the
access token received from the authorization server at the end of the
[OAuth 2.0
flow](/get-started/business-api/authentication/oauth/oauth-flow).
flows:
authorizationCode:
refreshUrl: https://oauth.qonto.com/oauth2/token
authorizationUrl: https://oauth.qonto.com/oauth2/auth
scopes:
attachment.read: Retrieve attachments
attachment.write: Upload attachments and remove attachments from transactions
bank_account.write: Create, update and close bank accounts
beneficiary.trust: Trust SEPA beneficiaries
card.read: Retrieve cards
card.write: Create or update cards
client.read: Retrieve clients
client.write: Create clients
client_invoice.write: Create client invoices
client_invoices.read: Retrieve client invoices and credit notes
einvoicing.read: Retrieve e-invoicing settings
embed_auth_link.write: Create Embed auth links
insurance_contract.read: Retrieve insurance contracts
insurance_contract.write: Create and update insurance contracts
internal_transfer.write: >-
Create internal transfers (between 2 Qonto accounts of the same
organization)
international_transfer.write: Create international transfers
membership.read: Retrieve the authentified membership
membership.write: Invite team members
offline_access: Retrieve a refresh token
organization.read: >-
Retrieve organization, bank accounts, transactions, transfers,
beneficiaries, labels, memberships, requests & statements
payment.write: Create external transfers and untrust beneficiaries
payment_link.read: >-
Retrieve payment links, their payments, and the available payment
methods
payment_link.write: >-
Connect to the payment links provider, create and deactivate
payment links
product.read: Retrieve products
product.write: Create products
request_cards.write: Create card requests
request_review.write: Approve or decline requests
request_transfers.write: Create transfer requests
sepa_direct_debit.read: View SEPA Direct Debit payments
sepa_direct_debit.write: Manage SEPA Direct Debit payments
supplier_invoice.read: Retrieve supplier invoices
supplier_invoice.write: Create supplier invoices
team.read: Retrieve teams
team.write: Create teams
terminal.read: View your payment terminals
terminal.write: Configure your terminals and initiate payments
webhook: >-
Receive a notification each time a particular event occurs in
Qonto
tokenUrl: https://oauth.qonto.com/oauth2/token
SecretKey:
type: apiKey
description: cf. [API key](/get-started/business-api/authentication/api-key)
name: Authorization
in: header
````