> ## 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 transfer
> OAuth scope: `payment.write`
This operation requires [Strong Customer Authentication](/api-reference/business-api/authentication/sca/sca-flows) unless the [beneficiary is trusted](/api-reference/business-api/payments-transfers/sepa-transfers/beneficiaries/sepa-beneficiaries/trust).
Example of SCA usage: [Postman visual flow](https://www.postman.com/qontoteam/workspace/qonto-public-api/flow/6670429eb7bd63003156bd57)
Creates a new SEPA 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).
For transfers above 30,000 EUR, at least one attachment is required.
By default, the transfer will be processed as **instant**. If instant processing isn't possible, it will automatically fall back to standard processing. It will be the case if the amount of the transfer is above the following thresholds 👇
- The transfer is above 5,000 EUR;
- More than 20,000 EUR have been sent to this beneficairy within 24 hours.
- The transfer is above 10,000 EUR;
- More than 50,000 EUR have been sent to this beneficairy within 24 hours.
To learn more about instant transfers, please read [this article](https://support-fr.qonto.com/hc/en-us/articles/23947629441681-How-to-make-an-instant-transfer-in-euros-SEPA).
## OpenAPI
````yaml POST /v2/sepa/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/transfers:
parameters:
- $ref: '#/components/parameters/X-Qonto-Staging-Token'
post:
tags:
- SEPA Transfers
summary: Create a SEPA transfer
description: >
OAuth scope: `payment.write`
This operation requires [Strong Customer
Authentication](/api-reference/business-api/authentication/sca/sca-flows)
unless the [beneficiary is
trusted](/api-reference/business-api/payments-transfers/sepa-transfers/beneficiaries/sepa-beneficiaries/trust).
Example of SCA usage: [Postman visual flow](https://www.postman.com/qontoteam/workspace/qonto-public-api/flow/6670429eb7bd63003156bd57)
Creates a new SEPA 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).
For transfers above 30,000 EUR, at least one attachment is required.
By default, the transfer will be processed as **instant**. If instant
processing isn't possible, it will automatically fall back to standard
processing. It will be the case if the amount of the transfer is above
the following thresholds 👇
- The transfer is above 5,000 EUR;
- More than 20,000 EUR have been sent to this beneficairy within 24 hours.
- The transfer is above 10,000 EUR;
- More than 50,000 EUR have been sent to this beneficairy within 24 hours.
To learn more about instant transfers, please read [this
article](https://support-fr.qonto.com/hc/en-us/articles/23947629441681-How-to-make-an-instant-transfer-in-euros-SEPA).
operationId: createSepaTransfer
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/CreateSepaTransferRequest'
examples:
valid:
value:
vop_proof_token: proof_1234567890abcdef
transfer:
beneficiary_id: 66b7e300-0126-4905-9688-27b445a48c4e
bank_account_id: 420e13ac-9d3e-4c11-93a1-0c3c8304f2df
reference: Lease payment
amount: '1100.50'
note: Lease payment for offices in Paris
attachment_ids:
- 394f77f1-0d2c-46fb-8a7e-a959dbdeee63
scheduled_date: '2026-01-11'
responses:
'200':
description: SEPA transfer created successfully
content:
application/json:
schema:
type: object
required:
- transfer
properties:
transfer:
$ref: '#/components/schemas/SepaTransfer'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseBody'
examples:
reference is missing:
value:
errors:
- code: missing_key
detail: reference is missing
source:
pointer: /transfer/reference
amount is missing:
value:
errors:
- code: missing_key
detail: amount is missing
source:
pointer: /transfer/amount
with invalid amount:
value:
errors:
- code: invalid
detail: amount must be greater than 0
source:
pointer: /transfer/amount
Not enough funds in the account:
value:
errors:
- code: insufficient_funds
detail: The account has insufficient funds
source:
pointer: /transfer/bank_account_id
attachment_id cannot be found:
value:
errors:
- code: not_found
detail: >-
Attachment not found
id=6cc7f2dd-ea0d-4cc2-ba30-f3e1ce0a8eb4
source:
pointer: /transfer/attachment_ids/1
attachment_ids exceeds max limit:
value:
errors:
- code: above_max_size
detail: attachment_ids cannot be greater than 5
source:
pointer: /transfer/attachment_ids
amount above 30000 EUR:
value:
errors:
- code: attachment_required
detail: The transfer must have at least one attachment
source:
pointer: /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: /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: /transfer/bank_account_id
with non-internal bank account:
value:
errors:
- code: debit_bank_account_external
detail: Can only create transfers with internal bank accounts
source:
pointer: /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: /transfer/beneficiary_id
invalid vop proof token:
value:
errors:
- code: vop_proof_token_invalid
detail: VOP proof token is invalid
payment policy approval required:
value:
errors:
- code: payment_policy_approval_required
detail: Approval required by payment policy
payment policy approver missing:
value:
errors:
- code: payment_policy_approver_missing
detail: No approver available for payment policy
insufficient per transfer limits:
value:
errors:
- code: insufficient_per_transfer_limits
detail: The transfer amount exceeds your per-transfer limit
insufficient monthly limits:
value:
errors:
- code: insufficient_monthly_limits
detail: >-
The transfer amount would exceed your monthly transfer
limit
'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:
CreateSepaTransferRequest:
type: object
required:
- 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
transfer:
type: object
required:
- bank_account_id
- reference
- amount
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
format: uuid
description: >-
The ID of the bank account from which the amount will be debited
from.
reference:
type: string
description: The reference of the transfer
example: Inventory
maxLength: 140
amount:
type: string
example: '100.50'
pattern: ^\d+(\.\d{1,2})?$
description: >-
Corresponds to the amount of the transaction in the `currency`
of the bank account. Amounts must be
https://www.w3.org/TR/payment-request/#dfn-valid-decimal-monetary-value.
scheduled_date:
type: string
format: date
description: >-
The date for the transfer to be executed in YYYY-MM-DD format.
If not provided, the transfer will be executed the same day or
the next available date.
note:
type: string
description: A note for the transfer
example: Inventory goods for restaurant in Paris
attachment_ids:
type: array
description: >-
You can link up to 5 attachments per transfer by passing the
`attachment_ids` parameter. You can upload your attachments
using our [POST
/v2/attachments](/api-reference/business-api/endpoints/attachments/upload-an-attachment)
endpoint.
**Note: For SEPA transfers above 30,000 EUR at
least one attachment is required**
items:
type: string
format: uuid
SepaTransfer:
type: object
required:
- id
- initiator_id
- amount
- amount_cents
- amount_currency
- beneficiary_id
- status
- scheduled_date
- created_at
- updated_at
- bank_account_id
- reference
- note
- declined_reason
- processed_at
- completed_at
- transaction_id
- recurring_transfer_id
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
amount:
type: number
format: float
example: 1100.5
amount_cents:
type: integer
example: 110050
amount_currency:
type: string
enum:
- EUR
status:
type: string
enum:
- pending
- processing
- canceled
- declined
- settled
description: >-
Can contain the following values:
* `pending`: SEPA transfer is created and has not been processed
yet. If transfer is not processed within next minute, it means
either execution date may not been reached yet or we are running
some compliance checks on this transfer.
* `processing`: SEPA transfer processing means account balance is
debited and a transaction has been created. Processing status can
last up to multiple hours until transfer is sent in the network to
the beneficiary.
* `canceled`: When the SEPA transfer is canceled by a user in the
interface. This is a permanent status.
* `declined`: When the SEPA transfer is declined by the screening
service, fraud service or, once sent on the network, for many
various reasons which are listed in [those
guidelines](https://www.europeanpaymentscouncil.eu/sites/default/files/kb/file/2023-11/EPC135-18%20v5.0%20Guidance%20on%20Reason%20Codes%20for%20SCT%20R-transactions.pdf).
This is a permanent status.
* `settled`: When the SEPA transfer is sent to the network, transfer
is settled. This is a permanent status.
example: pending
beneficiary_id:
type: string
format: uuid
reference:
type: string
example: Lease payment
note:
type:
- string
- 'null'
example: Lease payment for offices in Paris
declined_reason:
type:
- string
- 'null'
enum:
- beneficiary_bic_invalid
- beneficiary_iban_invalid
- beneficiary_status
- beneficiary_network_rules_error
- organisation_compliance_reasons
- debit_account_insufficient_funds
- qonto_processing_failed
- null
description: >-
Populated only when transfer status is declined. Possible values:
`beneficiary_bic_invalid`, `beneficiary_iban_invalid`,
`beneficiary_status`, `beneficiary_network_rules_error`,
`organisation_compliance_reasons`,
`debit_account_insufficient_funds`, `qonto_processing_failed`.
scheduled_date:
type: string
format: date
description: >-
YYYY-MM-DD, indicates when the external transfer was scheduled to be
sent by Qonto.
created_at:
type: string
format: date-time
example: '2025-04-22T12:00:00Z'
description: UTC, the time at which the external transfer was first recorded.
updated_at:
type: string
format: date-time
example: '2025-04-22T12:00:00Z'
description: UTC, the time at which the external transfer was last updated.
processed_at:
type:
- string
- 'null'
format: date-time
description: >-
UTC, when the external transfer has been started to be processed by
Qonto.
example: '2025-04-22T12:00:00Z'
completed_at:
type:
- string
- 'null'
format: date-time
description: >-
UTC, when the external transfer is in its final state, either
settled or declined.
example: '2025-04-22T12:00:00Z'
transaction_id:
type:
- string
- 'null'
format: uuid
description: The ID of the transaction associated with the transfer.
recurring_transfer_id:
type:
- string
- 'null'
format: uuid
description: The ID of the recurring transfer associated with the transfer.
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
````