> ## 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 transfer request
> OAuth scope: `request_transfers.write`
Creates a single transfer request that should be approved by a membership of the authenticated organization with permissions to review requests.
Use this endpoint as the fallback when [Create a SEPA transfer](/api-reference/business-api/payments-transfers/sepa-transfers/sepa-transfers/create) returns `payment_policy_approval_required` or `payment_policy_approver_missing`.
For batches of multiple beneficiaries in one request, use [Create multi transfer request](/api-reference/business-api/expense-management/requests/create-multi-transfer-request) instead.
**Price plans**: this endpoint is accessible by organizations with all plans except Solo Basic.
## OpenAPI
````yaml post /v2/requests/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/requests/transfers:
post:
tags:
- Requests
summary: Create transfer request
description: >
OAuth scope: `request_transfers.write`
Creates a single transfer request that should be approved by a
membership of the authenticated organization with permissions to review
requests.
Use this endpoint as the fallback when [Create a SEPA
transfer](/api-reference/business-api/payments-transfers/sepa-transfers/sepa-transfers/create)
returns `payment_policy_approval_required` or
`payment_policy_approver_missing`.
For batches of multiple beneficiaries in one request, use [Create multi
transfer
request](/api-reference/business-api/expense-management/requests/create-multi-transfer-request)
instead.
**Price plans**: this endpoint is accessible by organizations with all plans except Solo Basic.
parameters:
- $ref: '#/components/parameters/X-Qonto-Staging-Token'
- $ref: '#/components/parameters/X-Qonto-Idempotency-Key'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
request_transfer:
type: object
properties:
note:
type: string
description: >-
Description of a nature of request. Helps approver to
understand the reason of this request.
example: Q1 marketing invoice — pending admin approval
credit_iban:
type: string
description: >-
International beneficiary Bank Account Identifier (IBAN)
of creditor. Must respect ISO 13616.
example: FR7630001007941234567890183
credit_account_name:
type: string
description: >-
Free format for the name of the beneficiary. Limited to
140 chars.
maxLength: 140
example: URSSAF
credit_account_currency:
type: string
description: 'ISO 4217 formatted. Allowed values: EUR.'
example: EUR
amount:
type: string
description: >-
Should be decimal with 2 digits after coma, ex: "1",
"1.99", "1.1"
example: '2000.50'
currency:
type: string
description: 'ISO 4217 formatted. Allowed values: EUR.'
example: EUR
reference:
type: string
description: Reference of a transfer. Limited to 140 chars.
maxLength: 140
example: Invoice 2026-01
attachment_ids:
type: array
items:
type: string
description: >-
Array of UUID that are linked to this transfer.
Attachment must be uploaded thanks to a dedicated
endpoints before the transfer to be done.
example: d840f1cb-6adb-48af-9f89-540dcf5ba741
scheduled_date:
type: string
description: >
Start date of the transfer (YYYY-MM-DD). If the request
is approved, the transfer will be executed on this date
at midnight (GMT).
Required when `recurrence` is set. Optional otherwise —
defaults to the current date.
format: date
example: '2026-03-06'
recurrence:
type: string
description: >
Frequency of the standing order. When set, the transfer
repeats automatically at the given frequency starting
from `scheduled_date`.
When `recurrence` is present, `scheduled_date` must also
be provided. Use `last_recurrence_date` to set an end
date for the standing order — if omitted, the standing
order runs indefinitely.
Omit this field to create a one-off scheduled transfer.
enum:
- weekly
- monthly
- quarterly
- half_yearly
- yearly
example: monthly
last_recurrence_date:
type: string
description: >
End date of the standing order (YYYY-MM-DD). The last
transfer will be executed on or before this date.
Requires `recurrence` to be set. Omit for an open-ended
standing order.
format: date
example: '2026-12-06'
debit_iban:
type: string
description: >-
International Bank Account Identifier (IBAN) of the
debit account. Must respect ISO 13616. Must match an
active bank account of the authenticated organization.
example: FR0807277000000000000000911
required:
- note
- credit_iban
- credit_account_name
- credit_account_currency
- amount
- currency
- reference
required:
- request_transfer
responses:
'200':
description: Returns the request created.
content:
application/json:
schema:
type: object
properties:
request_transfer:
type: object
properties:
id:
type: string
example: bb8f8d1d-5f12-486e-8f8e-90cc2af76038
request_type:
type: string
example: transfer
status:
type: string
example: pending
initiator_id:
type: string
description: >-
ID of the membership that initiated the request.
When the request is initiated through the API, the
initiator is the authenticated membership.
example: 6b1872e4-08e4-42ec-9c82-b441ec242a9b
approver_id:
type:
- string
- 'null'
note:
type: string
example: Q1 marketing invoice — pending admin approval
declined_note:
type:
- string
- 'null'
creditor_name:
type: string
description: >-
Beneficiary's account name, echoed back from
`credit_account_name`.
example: URSSAF
reference:
type: string
example: Invoice 2026-01
amount:
type: string
example: '2000.50'
currency:
type: string
example: EUR
attachment_ids:
type: array
items:
type: string
example: d840f1cb-6adb-48af-9f89-540dcf5ba741
scheduled_date:
type:
- string
- 'null'
format: date
example: '2026-03-06'
recurrence:
type:
- string
- 'null'
description: >-
Frequency of the standing order. `null` for one-off
transfers.
enum:
- weekly
- monthly
- quarterly
- half_yearly
- yearly
example: monthly
last_recurrence_date:
type:
- string
- 'null'
description: >-
End date of the standing order. `null` for open-ended
standing orders and one-off transfers.
format: date
example: '2026-12-06'
processed_at:
type:
- string
- 'null'
created_at:
type: string
example: '2026-02-16T17:33:38.215Z'
required:
- id
- request_type
- status
- initiator_id
- note
- creditor_name
- reference
- amount
- currency
- attachment_ids
- created_at
required:
- request_transfer
examples:
One-off transfer:
value:
request_transfer:
id: bb8f8d1d-5f12-486e-8f8e-90cc2af76038
request_type: transfer
status: pending
initiator_id: 6b1872e4-08e4-42ec-9c82-b441ec242a9b
approver_id: null
note: Q1 marketing invoice — pending admin approval
declined_note: null
creditor_name: URSSAF
reference: Invoice 2026-01
amount: '2000.50'
currency: EUR
attachment_ids: []
scheduled_date: '2026-03-06'
recurrence: null
last_recurrence_date: null
processed_at: null
created_at: '2026-02-16T17:33:38.215Z'
Standing transfer:
value:
request_transfer:
id: cc9f9e2e-6g23-597f-9g9f-01dd3bg87149
request_type: transfer
status: pending
initiator_id: 6b1872e4-08e4-42ec-9c82-b441ec242a9b
approver_id: null
note: Monthly office rent
declined_note: null
creditor_name: Landlord SAS
reference: Rent 2026
amount: '1500.00'
currency: EUR
attachment_ids: []
scheduled_date: '2026-04-01'
recurrence: monthly
last_recurrence_date: '2026-12-01'
processed_at: null
created_at: '2026-03-15T09:00:00.000Z'
'400':
$ref: '#/components/responses/400-Bad-request'
'401':
$ref: '#/components/responses/401-Unauthorized'
'403':
$ref: '#/components/responses/403-Forbidden'
'422':
description: Returns an unprocessable entity error.
content:
application/json:
schema:
type: object
properties:
errors:
$ref: '#/components/schemas/UnprocessableEntityError'
required:
- errors
examples:
Invalid IBAN:
value:
errors:
- detail: >-
It looks like the IBAN you entered isn't valid. Could
you verify and try again?
code: invalid_iban
source:
pointer: /request_transfer/credit_iban
Reference exceeds the limit:
value:
errors:
- code: above_max_size
detail: reference size cannot be greater than 140
source:
pointer: /request_transfer/reference
Missing body parameter:
value:
errors:
- code: blank
detail: note must be filled
source:
pointer: /request_transfer/note
Currency is not supported:
value:
errors:
- code: not_in_list
detail: 'currency must be one of: EUR'
source:
pointer: /request_transfer/currency
Credit account currency is not supported:
value:
errors:
- code: not_in_list
detail: 'credit_account_currency must be one of: EUR'
source:
pointer: /request_transfer/credit_account_currency
Debit account not found or inactive:
value:
errors:
- code: debit_account_error
detail: Debit account is not found or inactive
source:
pointer: /request_transfer/debit_iban
Invalid recurrence value:
value:
errors:
- code: not_in_list
detail: >-
must be one of: weekly, monthly, quarterly,
half_yearly, yearly
source:
pointer: /request_transfer/recurrence
last_recurrence_date requires recurrence:
value:
errors:
- code: blank
detail: >-
recurrence must be filled when last_recurrence_date is
present
source:
pointer: /request_transfer/recurrence
scheduled_date required for standing transfer:
value:
errors:
- code: blank
detail: >-
scheduled_date must be filled when recurrence is
present
source:
pointer: /request_transfer/scheduled_date
scheduled_date in the past:
value:
errors:
- code: in_the_past
detail: 2026-01-01 is in the past
source:
pointer: /request_transfer/scheduled_date
'500':
$ref: '#/components/responses/500-Internal-Server-Error'
security:
- OAuth:
- request_transfers.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-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
responses:
400-Bad-request:
description: Returns a bad request error.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponseBody'
examples:
Authorization field missing:
value:
errors:
- code: bad_request
detail: Authorization field missing
401-Unauthorized:
description: Returns an unauthorized error.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponseBody'
examples:
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-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.
500-Internal-Server-Error:
description: Returns an internal server error.
schemas:
UnprocessableEntityError:
type: object
properties:
status:
type: string
example: unprocessable entity
code:
type: string
description: Error code.
example: missing_key
detail:
type: string
description: Human readable error that explains error `code`.
example: property is missing
message:
type: string
example: property id is missing
source:
type: object
properties:
pointer:
type: string
description: >-
The property and the item in an array (if applicable) that
causes the error.
example: id
required:
- code
- detail
BadRequestResponseBody:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/BadRequestError'
required:
- errors
UnauthorizedResponseBody:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/UnauthorizedError'
required:
- errors
ForbiddenResponseBody:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ForbiddenError'
required:
- errors
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
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
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.
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
cash_flow_category.read: Retrieve cash flow categories
cash_flow_category.write: Create cash flow categories and assign them to transactions
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
````