---
title: "Create a transfer"
method: POST
path: "/transfer/create"
tags: ["plaid"]
---

# Create a transfer

`POST /transfer/create`

Use the `/transfer/create` endpoint to initiate a new transfer.

## Request body

- TransferCreateRequest — Defines the request schema for `/transfer/create`
  - `client_id` string — Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body.
  - `secret` string — Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body.
  - `idempotency_key` string — Deprecated. `authorization_id` is now used as idempotency instead. A random key provided by the client, per unique transfer. Maximum of 50 characters. The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a transfer fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single transfer is created.
  - `access_token` string, required — The Plaid `access_token` for the account that will be debited or credited.
  - `account_id` string, required — The Plaid `account_id` corresponding to the end-user account that will be debited or credited.
  - `authorization_id` string, required — Plaid’s unique identifier for a transfer authorization. This parameter also serves the purpose of acting as an idempotency identifier.
  - `type` 'debit' | 'credit' — The type of transfer. This will be either `debit` or `credit`. A `debit` indicates a transfer of money into the origination account; a `credit` indicates a transfer of money out of the origination account.
  - `network` 'ach' | 'same-day-ach' | 'rtp' | 'wire' — The network or rails used for the transfer. For transfers submitted as `ach`, the next-day cutoff is 5:30 PM Eastern Time. For transfers submitted as `same-day-ach`, the same-day cutoff is 3:30 PM Eastern Time. If the transfer is submitted after this cutoff but before the next-day cutoff, it will be sent over next-day rails and will not incur same-day charges; this will apply to both legs of the transfer if applicable. For transfers submitted as `rtp`, Plaid will automatically route between Real Time Payment rail by TCH or FedNow rails as necessary. If a transfer is submitted as `rtp` and the counterparty account is not eligible for RTP, the `/transfer/authorization/create` request will fail with an `INVALID_FIELD` error code. To pre-check to determine whether a counterparty account can support RTP, call `/transfer/capabilities/get` before calling `/transfer/authorization/create`.
  - `amount` string — The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling `/transfer/authorization/create`, specify the maximum amount to authorize. When calling `/transfer/create`, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling `/transfer/create`, the maximum amount authorized in the `authorization_id` will be sent.
  - `description` string, required — The transfer description. Maximum of 15 characters. If reprocessing a returned transfer, please note that the `description` field must be `"Retry 1"` or `"Retry 2"` to indicate that it's a retry of a previously returned transfer. You may retry a transfer up to 2 times, within 180 days of creating the original transfer. Only transfers that were returned with code `R01` or `R09` may be retried. For a full listing of ACH return codes, see [Transfer errors](https://plaid.com/docs/errors/transfer/#ach-return-codes).
  - `ach_class` 'ccd' | 'ppd' | 'tel' | 'web' — Specifies the use case of the transfer. Required for transfers on an ACH network. `"ccd"` - Corporate Credit or Debit - fund transfer between two corporate bank accounts `"ppd"` - Prearranged Payment or Deposit - the transfer is part of a pre-existing relationship with a consumer, e.g. bill payment `"tel"` - Telephone-Initiated Entry `"web"` - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet
  - `user` TransferUserInRequestDeprecated, nullable — The legal name and other information for the account holder.
    - `legal_name` string — The user's legal name.
    - `phone_number` string — The user's phone number.
    - `email_address` string — The user's email address.
    - `address` TransferUserAddressInRequest — The address associated with the account holder.
      - `street` string — The street number and name (i.e., "100 Market St.").
      - `city` string — Ex. "San Francisco"
      - `region` string — The state or province (e.g., "CA").
      - `postal_code` string — The postal code (e.g., "94103").
      - `country` string — A two-letter country code (e.g., "US").
  - `metadata` TransferMetadata, nullable — The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters
  - `origination_account_id` string, nullable — Plaid’s unique identifier for the origination account for this transfer. If you have more than one origination account, this value must be specified. Otherwise, this field should be left blank.
  - `iso_currency_code` string — The currency of the transfer amount. The default value is "USD".
  - `test_clock_id` string, nullable — Plaid’s unique identifier for a test clock. This field may only be used when using `sandbox` environment. If provided, the `transfer` is created at the `virtual_time` on the provided `test_clock`.
  - `facilitator_fee` string — The amount to deduct from `transfer.amount` and distribute to the platform’s Ledger balance as a facilitator fee (decimal string with two digits of precision e.g. "10.00"). The remainder will go to the end-customer’s Ledger balance. This must be less than or equal to the `transfer.amount`.

## Response `200`

OK

- TransferCreateResponse — Defines the response schema for `/transfer/create`
  - `transfer` Transfer, required — Represents a transfer within the Transfers API.
    - `id` string, required — Plaid’s unique identifier for a transfer.
    - `authorization_id` string, required — Plaid’s unique identifier for a transfer authorization.
    - `ach_class` 'ccd' | 'ppd' | 'tel' | 'web' — Specifies the use case of the transfer. Required for transfers on an ACH network. `"ccd"` - Corporate Credit or Debit - fund transfer between two corporate bank accounts `"ppd"` - Prearranged Payment or Deposit - the transfer is part of a pre-existing relationship with a consumer, e.g. bill payment `"tel"` - Telephone-Initiated Entry `"web"` - Internet-Initiated Entry - debits from a consumer’s account where their authorization is obtained over the Internet
    - `account_id` string — The Plaid `account_id` corresponding to the end-user account that will be debited or credited.
    - `funding_account_id` string, nullable, required — The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited.
    - `type` 'debit' | 'credit', required — The type of transfer. This will be either `debit` or `credit`. A `debit` indicates a transfer of money into the origination account; a `credit` indicates a transfer of money out of the origination account.
    - `user` TransferUserInResponse, required — The legal name and other information for the account holder.
      - `legal_name` string, required — The user's legal name.
      - `phone_number` string, nullable, required — The user's phone number.
      - `email_address` string, nullable, required — The user's email address.
      - `address` TransferUserAddressInResponse, nullable, required — The address associated with the account holder.
        - `street` string, nullable, required — The street number and name (i.e., "100 Market St.").
        - `city` string, nullable, required — Ex. "San Francisco"
        - `region` string, nullable, required — The state or province (e.g., "CA").
        - `postal_code` string, nullable, required — The postal code (e.g., "94103").
        - `country` string, nullable, required — A two-letter country code (e.g., "US").
    - `amount` string, required — The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling `/transfer/authorization/create`, specify the maximum amount to authorize. When calling `/transfer/create`, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling `/transfer/create`, the maximum amount authorized in the `authorization_id` will be sent.
    - `description` string, required — The description of the transfer.
    - `created` string, date-time, required — The datetime when this transfer was created. This will be of the form `2006-01-02T15:04:05Z`
    - `status` 'pending' | 'posted' | 'settled' | 'cancelled' | 'failed' | 'returned', required — The status of the transfer. `pending`: A new transfer was created; it is in the pending state. `posted`: The transfer has been successfully submitted to the payment network. `settled`: Credits are available to be withdrawn or debits have been deducted from the Plaid linked account. `cancelled`: The transfer was cancelled by the client. `failed`: The transfer failed, no funds were moved. `returned`: A posted transfer was returned.
    - `sweep_status` 'null' | 'unswept' | 'swept' | 'swept_settled' | 'return_swept', nullable — The status of the sweep for the transfer. `unswept`: The transfer hasn't been swept yet. `swept`: The transfer was swept to the sweep account. `swept_settled`: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account. `return_swept`: The transfer was returned, funds were pulled back or pushed back to the sweep account. `null`: The transfer will never be swept (e.g. if the transfer is cancelled or returned before being swept)
    - `network` 'ach' | 'same-day-ach' | 'rtp' | 'wire', required — The network or rails used for the transfer. For transfers submitted as `ach`, the next-day cutoff is 5:30 PM Eastern Time. For transfers submitted as `same-day-ach`, the same-day cutoff is 3:30 PM Eastern Time. If the transfer is submitted after this cutoff but before the next-day cutoff, it will be sent over next-day rails and will not incur same-day charges; this will apply to both legs of the transfer if applicable. For transfers submitted as `rtp`, Plaid will automatically route between Real Time Payment rail by TCH or FedNow rails as necessary. If a transfer is submitted as `rtp` and the counterparty account is not eligible for RTP, the `/transfer/authorization/create` request will fail with an `INVALID_FIELD` error code. To pre-check to determine whether a counterparty account can support RTP, call `/transfer/capabilities/get` before calling `/transfer/authorization/create`.
    - `wire_details` TransferWireDetails, nullable — Information specific to wire transfers.
      - `message_to_beneficiary` string, nullable — Additional information from the wire originator to the beneficiary. Max 140 characters.
    - `cancellable` boolean, required — When `true`, you can still cancel this transfer.
    - `failure_reason` TransferFailure, nullable, required — The failure reason if the event type for a transfer is `"failed"` or `"returned"`. Null value otherwise.
      - `ach_return_code` string, nullable — The ACH return code, e.g. `R01`. A return code will be provided if and only if the transfer status is `returned`. For a full listing of ACH return codes, see [Transfer errors](https://plaid.com/docs/errors/transfer/#ach-return-codes).
      - `description` string — A human-readable description of the reason for the failure or reversal.
    - `metadata` TransferMetadata, nullable, required — The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters
    - `origination_account_id` string, required — Plaid’s unique identifier for the origination account that was used for this transfer.
    - `guarantee_decision` 'GUARANTEED' | 'NOT_GUARANTEED' | 'null', nullable, required — Indicates whether the transfer is guaranteed by Plaid (Guarantee customers only). This field will contain either `GUARANTEED` or `NOT_GUARANTEED` indicating whether Plaid will guarantee the transfer. If the transfer is not guaranteed, additional information will be provided in the `guarantee_decision_rationale` field. Refer to the `code` field in `guarantee_decision_rationale` for details.
    - `guarantee_decision_rationale` TransferAuthorizationGuaranteeDecisionRationale, nullable, required — The rationale for Plaid's decision to not guarantee a transfer. Will be `null` unless `guarantee_decision` is `NOT_GUARANTEED`.
      - `code` 'RETURN_BANK' | 'RETURN_CUSTOMER' | 'GUARANTEE_LIMIT_REACHED' | 'RISK_ESTIMATE_UNAVAILABLE' | 'REQUIRED_PARAM_MISSING', required — A code representing the reason Plaid declined to guarantee this transfer: `RETURN_BANK`: The risk of a bank-initiated return (for example, an R01/NSF) is too high to guarantee this transfer. `RETURN_CUSTOMER`: The risk of a customer-initiated return (for example, a R10/Unauthorized) is too high to guarantee this transfer. `GUARANTEE_LIMIT_REACHED`: This transfer is low-risk, but Guarantee has exhausted an internal limit on the number or rate of guarantees that applies to this transfer. `RISK_ESTIMATE_UNAVAILABLE`: A risk estimate is unavailable for this Item. `REQUIRED_PARAM_MISSING`: Required fields are missing.
      - `description` string, required — A human-readable description of why the transfer cannot be guaranteed.
    - `iso_currency_code` string, required — The currency of the transfer amount, e.g. "USD"
    - `standard_return_window` string, date, nullable, required — The date 3 business days from settlement date indicating the following ACH returns can no longer happen: R01, R02, R03, R29. This will be of the form YYYY-MM-DD.
    - `unauthorized_return_window` string, date, nullable, required — The date 61 business days from settlement date indicating the following ACH returns can no longer happen: R05, R07, R10, R11, R51, R33, R37, R38, R51, R52, R53. This will be of the form YYYY-MM-DD.
    - `expected_settlement_date` string, date, nullable, required — The expected date when the full amount of the transfer settles at the consumers’ account, if the transfer is credit; or at the customer's business checking account, if the transfer is debit. Only set for ACH transfers and is null for non-ACH transfers. Only set for ACH transfers. This will be of the form YYYY-MM-DD.
    - `originator_client_id` string, nullable, required — The Plaid client ID that is the originator of this transfer. Only present if created on behalf of another client as a [Platform customer](https://plaid.com/docs/transfer/application/#originators-vs-platforms).
    - `refunds` TransferRefund[], required — A list of refunds associated with this transfer.
      - `id` string, required — Plaid’s unique identifier for a refund.
      - `transfer_id` string, required — The ID of the transfer to refund.
      - `amount` string, required — The amount of the refund (decimal string with two digits of precision e.g. "10.00").
      - `status` 'pending' | 'posted' | 'cancelled' | 'failed' | 'settled' | 'returned', required — The status of the refund. `pending`: A new refund was created; it is in the pending state. `posted`: The refund has been successfully submitted to the payment network. `settled`: Credits have been refunded to the Plaid linked account. `cancelled`: The refund was cancelled by the client. `failed`: The refund has failed. `returned`: The refund was returned.
      - `failure_reason` TransferRefundFailure, nullable, required — The failure reason if the event type for a refund is `"failed"` or `"returned"`. Null value otherwise.
        - `ach_return_code` string, nullable — The ACH return code, e.g. `R01`. A return code will be provided if and only if the refund status is `returned`. For a full listing of ACH return codes, see [Transfer errors](https://plaid.com/docs/errors/transfer/#ach-return-codes).
        - `description` string — A human-readable description of the reason for the failure or reversal.
      - `created` string, date-time, required — The datetime when this refund was created. This will be of the form `2006-01-02T15:04:05Z`
      - `network_trace_id` string, nullable — The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For `ach` or `same-day-ach` transfers, this is the ACH trace number. For `wire` transfers, this is the IMAD (Input Message Accountability Data) number. The field will remain null for transfers on other rails.
    - `recurring_transfer_id` string, nullable, required — The id of the recurring transfer if this transfer belongs to a recurring transfer.
    - `expected_sweep_settlement_schedule` TransferExpectedSweepSettlementScheduleItem[] — The expected sweep settlement schedule of this transfer, assuming this transfer is not `returned`. Only applies to ACH debit transfers.
      - `sweep_settlement_date` string, date, required — The settlement date of a sweep for this transfer.
      - `swept_settled_amount` string, required — The accumulated amount that has been swept by `sweep_settlement_date`.
    - `credit_funds_source` 'sweep' | 'prefunded_rtp_credits' | 'prefunded_ach_credits' | 'null', nullable, required — This field is now deprecated. You may ignore it for transfers created on and after 12/01/2023. Specifies the source of funds for the transfer. Only valid for `credit` transfers, and defaults to `sweep` if not specified. This field is not specified for `debit` transfers. `sweep` - Sweep funds from your funding account `prefunded_rtp_credits` - Use your prefunded RTP credit balance with Plaid `prefunded_ach_credits` - Use your prefunded ACH credit balance with Plaid
    - `facilitator_fee` string — The amount to deduct from `transfer.amount` and distribute to the platform’s Ledger balance as a facilitator fee (decimal string with two digits of precision e.g. "10.00"). The remainder will go to the end-customer’s Ledger balance. This must be less than or equal to the `transfer.amount`.
    - `network_trace_id` string, nullable — The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For `ach` or `same-day-ach` transfers, this is the ACH trace number. For `wire` transfers, this is the IMAD (Input Message Accountability Data) number. The field will remain null for transfers on other rails.
  - `request_id` string, required — A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

## Other responses

- `default` — Error response

## Changes

- **2024-02-21** `5de70cc1e6ca` — 2 breaking, 13 warning, 18 info
  - the response property `transfer/guarantee_decision` became nullable for the status `200`
  - the `transfer/guarantee_decision` response's property type/format changed from ``/`` to `string`/`` for status `200`
  - removed the optional property `error_code_reason` from the response with the `default` status
  - removed the optional property `provided_account_subtypes` from the response with the `default` status
  - …29 more

[Change history](https://skmtc.dev/plaid/apis/the-plaid-api/changes/transfer/create/post.md)

---

[API](https://skmtc.dev/plaid/apis/the-plaid-api.md) · [All operations](https://skmtc.dev/plaid/apis/the-plaid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/plaid/the-plaid-api/revisions/ec7541420dd2/schema)