---
title: "Create transfer"
method: POST
path: "/v2/business-accounts/transfers"
tags: ["Transfers API"]
---

# Create transfer

`POST /v2/business-accounts/transfers`

> 🚧 Beta feature
>
> This feature is currently in beta testing, and the final specification may still change.

Create a SEPA Credit Transfer from your Mollie Business Account.

To initiate a transfer, you must provide the transfer scheme, the amount, the debtor IBAN (your Mollie Business
Account IBAN), and the creditor (recipient) details.

Each request must include an `Idempotency-Key` header to prevent duplicate transfers, and must be signed using the
`X-Client-Signature` and `X-Client-Signed-At` headers.

### Simulating transfer scenarios in test mode

In test mode, you can simulate various transfer scenarios by adjusting the transfer amount. This allows you to
mimic the typical status progression of a real-world transfer. Note that a transfer's progression will stop once
it reaches a final status: `blocked`, `failed`, `processed`, or `returned`.

| Amount  | Scenario                                            | Webhook sequence                                                                                                                                                   |
|---------|-----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `11.00` | Transfer initiated, pending review by Mollie        | `business-account-transfer.requested` → `business-account-transfer.initiated` → `business-account-transfer.pending-review`                                         |
| `12.00` | Transfer initiated, blocked by Mollie               | `business-account-transfer.requested` → `business-account-transfer.initiated` → `business-account-transfer.pending-review` → `business-account-transfer.blocked`   |
| `13.00` | Transfer initiated, failed on scheme submission     | `business-account-transfer.requested` → `business-account-transfer.initiated` → `business-account-transfer.failed`                                                 |
| `14.00` | Transfer processed, then returned by receiving bank | `business-account-transfer.requested` → `business-account-transfer.initiated` → `business-account-transfer.processed` → `business-account-transfer.returned`       |
| Other   | Default: transfer is processed                      | `business-account-transfer.requested` → `business-account-transfer.initiated` → `business-account-transfer.processed`                                              |

## Headers

- `X-Client-Signature` string, required
- `X-Client-Signed-At` string, required
- `Idempotency-Key` string, required
- `idempotency-key` string

## Request body

- TransferRequest
  - `resource` string — Indicates the response contains a transfer object. Will always contain the string `business-account-transfer` for this endpoint.
  - `id` string
  - `mode` 'live' | 'test' — Whether this entity was created in live mode or in test mode.
  - `debtorIban` string, required — The IBAN of the debtor's (sender) Mollie account from which to initiate the transfer.
  - `debtor` TransferParty — A party involved in the transfer, representing either the debtor (sender) or creditor (recipient). Contains the party's name and account details.
    - `fullName` string, required — The full name of the account holder.
    - `account` object, required — The bank account details of the party.
      - `iban` string, required — The IBAN (International Bank Account Number) of the account holder.
  - `creditor` TransferParty, required — A party involved in the transfer, representing either the debtor (sender) or creditor (recipient). Contains the party's name and account details.
    - `fullName` string, required — The full name of the account holder.
    - `account` object, required — The bank account details of the party.
      - `iban` string, required — The IBAN (International Bank Account Number) of the account holder.
  - `amount` Amount, required — In v2 endpoints, monetary amounts are represented as objects with a `currency` and `value` field.
    - `currency` string, required — A three-character ISO 4217 currency code.
    - `value` string, required — A string containing an exact monetary amount in the given currency.
  - `description` string, nullable — A short description of the transfer. This will appear on the bank statement of both the debtor and creditor. It must begin with an alphanumeric character, followed by any combination of letters, numbers, spaces or special characters `/ - ? : ( ) . , ' + _`. Constraints: - Cannot be solely a hyphen (-) or colon (:) - Cannot contain consecutive hyphens (--) - Cannot contain consecutive colons (::)
  - `businessAccountTransactionId` string
  - `transferScheme` TransferScheme, required — The scheme, as requested by the client.
    - `type` 'sepa-credit-inst' | 'sepa-credit', required — The transfer scheme to be used for the transfer. The transfer scheme determines the processing time and method of the transfer.
  - `creditDebitIndicator` 'credit' | 'debit' — Indicates whether the entry is a credit or debit from the perspective of the account holder.
  - `status` 'requested' | 'initiated' | 'pending-review' | 'processed' | 'failed' | 'blocked' | 'returned' — The status of the transfer.
  - `statusHistory` StatusHistoryEntry[] — A chronological list of status transitions the transfer has gone through.
    - `status` 'requested' | 'initiated' | 'pending-review' | 'processed' | 'failed' | 'blocked' | 'returned', required — The status of the transfer.
    - `createdAt` string, required — The entity's date and time of creation, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
    - `statusReason` StatusReason2, nullable — A human-readable reason explaining the current status of the transfer. Only populated when the transfer has reached a terminal status of `failed`, `rejected`, or `blocked`. This field is `null` for transfers that have not reached one of these statuses.
      - `code` 'insufficient-funds' | 'rejected' | 'error' — A machine-readable code indicating the reason for the transfer's terminal status.
      - `message` string — Provides further details about failure indicated. This field is only populated if the`code` field is set to `error`.
  - `createdAt` string — The entity's date and time of creation, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
  - `statusReason` StatusReason2, nullable — A human-readable reason explaining the current status of the transfer. Only populated when the transfer has reached a terminal status of `failed`, `rejected`, or `blocked`. This field is `null` for transfers that have not reached one of these statuses.
    - `code` 'insufficient-funds' | 'rejected' | 'error' — A machine-readable code indicating the reason for the transfer's terminal status.
    - `message` string — Provides further details about failure indicated. This field is only populated if the`code` field is set to `error`.
  - `metadata` union — Provide any data you like, for example a string or a JSON object. We will save the data alongside the entity. Whenever you fetch the entity with our API, we will also include the metadata. You can use up to approximately 1kB.
    - string
    - number
    - object
    - string[]
  - `testmode` boolean, nullable — Whether to create the entity in test mode or live mode. Most API credentials are specifically created for either live mode or test mode, in which case this parameter must not be sent. For organization-level credentials such as OAuth access tokens, you can enable test mode by setting `testmode` to `true`.

## Response `201`

The newly created transfer object.

## Other responses

- `422` — The request contains issues. For example, if the transfer amount is missing, or if the debtor IBAN does not belong to your organization.
- `429` — Rate Limit has been reached.
- `503` — An unexpected error occurred on our end. This is not related to your request. Please try again later. If the problem persists, contact support.

---

[API](https://skmtc.net/mollie/apis/mollie-api.md) · [All operations](https://skmtc.net/mollie/apis/mollie-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mollie/mollie-api/revisions/3fb1b5127a6b/schema)