v55

latestOpenAPI 3.1.0CC-BY-NC-SA-4.0raw.githubusercontent.com2026-08-011243791.8 MB

Transfers API

Create transfer

🚧 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

post/v2/business-accounts/transfers

Headers

X-Client-Signaturestring required

A cryptographic signature of the request payload, used to verify the authenticity of the transfer request.

X-Client-Signed-Atstring required

The timestamp (in ISO 8601 format) indicating when the client signed the request. Used in conjunction with X-Client-Signature for request verification.

Idempotency-Keystring required

A unique value used to identify this request and prevent duplicate transfers. UUIDv4 is recommended to guarantee uniqueness across multiple processes or servers. If two requests are received with the same idempotency key, the second request will be discarded.

View the public documentation to learn more.

idempotency-keystring

Example:123e4567-e89b-12d3-a456-426

A unique key to ensure idempotent requests. This key should be a UUID v4 string.

Request body

resourcestring

Indicates the response contains a transfer object. Will always contain the string business-account-transfer for this endpoint.

idstring

mode'live' | 'test'

Whether this entity was created in live mode or in test mode.

debtorIbanstring required

The IBAN of the debtor's (sender) Mollie account from which to initiate the transfer.

descriptionstring 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 (::)

businessAccountTransactionIdstring

creditDebitIndicator'credit' | 'debit'

Indicates whether the entry is a credit or debit from the perspective of the account holder.

The status of the transfer.

createdAtstring

The entity's date and time of creation, in ISO 8601 format.

testmodeboolean 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.

Example request

{
  "resource": "business-account-transfer",
  "id": "batrf_87GByBuj4UCcUTEbs6aGJ",
  "mode": "live",
  "debtorIban": "NL55MLLE0123456789",
  "debtor": {
    "fullName": "Jan Jansen",
    "account": {
      "iban": "NL02ABNA0123456789"
    }
  },
  "creditor": {
    "fullName": "Jan Jansen",
    "account": {
      "iban": "NL02ABNA0123456789"
    }
  },
  "amount": {
    "currency": "EUR",
    "value": "10.00"
  },
  "description": "Invoice 12345",
  "businessAccountTransactionId": "batr_87GByBuj4UCcUTEbs6aGJ",
  "transferScheme": {
    "type": "sepa-credit-inst"
  },
  "creditDebitIndicator": "debit",
  "status": "initiated",
  "statusHistory": [
    {
      "status": "initiated",
      "createdAt": "2024-03-20T09:13:37+00:00",
      "statusReason": {
        "code": "insufficient-funds",
        "message": "The creditor account does not exist."
      }
    }
  ],
  "createdAt": "2024-03-20T09:13:37+00:00",
  "statusReason": {
    "code": "insufficient-funds",
    "message": "The creditor account does not exist."
  }
}

Response

The newly created transfer object.