{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/plaid/main/json-schema/plaid-transfer-authorization-create-request-schema.json",
  "title": "TransferAuthorizationCreateRequest",
  "description": "Defines the request schema for `/transfer/authorization/create`",
  "x-generated": "2026-09-23",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/plaid-plaid-api-openapi.yml#/components/schemas/TransferAuthorizationCreateRequest",
  "type": "object",
  "properties": {
    "client_id": {
      "$ref": "#/$defs/APIClientID"
    },
    "secret": {
      "$ref": "#/$defs/APISecret"
    },
    "access_token": {
      "$ref": "#/$defs/TransferAccessToken"
    },
    "account_id": {
      "$ref": "#/$defs/TransferAccountID"
    },
    "funding_account_id": {
      "$ref": "#/$defs/TransferMigratedFundingAccountIDRequest"
    },
    "ledger_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Specify which ledger balance should be used to fund the transfer. You can find a list of `ledger_id`s in the Accounts page of your Plaid Dashboard. If this field is left blank, this will default to the id of the default ledger balance."
    },
    "payment_profile_token": {
      "$ref": "#/$defs/TransferPaymentProfileToken"
    },
    "type": {
      "$ref": "#/$defs/TransferType"
    },
    "network": {
      "$ref": "#/$defs/TransferNetwork"
    },
    "amount": {
      "$ref": "#/$defs/TransferAmount"
    },
    "ach_class": {
      "$ref": "#/$defs/ACHClass"
    },
    "wire_details": {
      "$ref": "#/$defs/TransferWireDetails"
    },
    "user": {
      "$ref": "#/$defs/TransferAuthorizationUserInRequest"
    },
    "device": {
      "$ref": "#/$defs/TransferAuthorizationDevice"
    },
    "origination_account_id": {
      "type": "string",
      "description": "Plaid's unique identifier for the origination account for this authorization. If not specified, the default account will be used.",
      "deprecated": true,
      "x-hidden-from-docs": true
    },
    "iso_currency_code": {
      "type": "string",
      "description": "The currency of the transfer amount. The default value is \"USD\"."
    },
    "idempotency_key": {
      "$ref": "#/$defs/TransferAuthorizationIdempotencyKey"
    },
    "user_present": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "If the end user is initiating the specific transfer themselves via an interactive UI, this should be `true`; for automatic recurring payments where the end user is not actually initiating each individual transfer, it should be `false`. This field is not currently used and is present to support planned future functionality."
    },
    "with_guarantee": {
      "type": [
        "boolean",
        "null"
      ],
      "default": true,
      "x-hidden-from-docs": true,
      "deprecated": true,
      "description": "If set to `false`, Plaid will not offer a `guarantee_decision` for this request (Guarantee customers only). This field is deprecated in favor of `guarantee`."
    },
    "request_guarantee": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Indicates whether the transfer should be evaluated for guarantee coverage. When set to `true`, Plaid assesses the transfer for guarantee coverage and returns a decision in the authorization response. When omitted or set to `false`, the authorization is evaluated without guarantee coverage."
    },
    "beacon_session_id": {
      "x-hidden-from-docs": true,
      "deprecated": true,
      "type": [
        "string",
        "null"
      ],
      "description": "The unique identifier returned by Plaid's [beacon](https://plaid.com/docs/transfer/guarantee/#using-a-beacon) when it is run on your webpage."
    },
    "originator_client_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "The Plaid client ID that is the originator of this transfer. Only needed if creating transfers on behalf of another client as a [Platform customer](https://plaid.com/docs/transfer/application/#originators-vs-platforms)."
    },
    "credit_funds_source": {
      "x-hidden-from-docs": true,
      "deprecated": true,
      "allOf": [
        {
          "$ref": "#/$defs/TransferCreditFundsSource"
        }
      ]
    },
    "test_clock_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Plaid's unique identifier for a test clock. This field may only be used when using `sandbox` environment. If provided, the `authorization` is created at the `virtual_time` on the provided test clock."
    },
    "ruleset_key": {
      "type": [
        "string",
        "null"
      ],
      "description": "The key of the Ruleset for the transaction. If not provided, Signal will use the `default` ruleset."
    },
    "custom_attributes": {
      "$ref": "#/$defs/TransferAuthorizationCustomAttributes"
    }
  },
  "required": [
    "type",
    "network",
    "amount",
    "user",
    "access_token",
    "account_id"
  ],
  "$defs": {
    "ACHClass": {
      "type": "string",
      "title": "ACHClass",
      "enum": [
        "ccd",
        "ppd",
        "tel",
        "web"
      ],
      "description": "Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see [ACH SEC codes](https://plaid.com/docs/transfer/creating-transfers/#ach-sec-codes).\n\nCodes supported for credits: `ccd`, `ppd`\nCodes supported for debits: `ccd`, `ppd`, `tel`, `web`\n\n`\"ccd\"` - Corporate Credit or Debit - fund transfer between two corporate bank accounts\n\n`\"ppd\"` - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits.\n\n`\"web\"` - Internet-Initiated Entry. The transfer debits a consumer's bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits.\n\n`\"tel\"` - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call."
    },
    "APIClientID": {
      "title": "ClientID",
      "type": "string",
      "description": "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."
    },
    "APISecret": {
      "title": "APISecret",
      "type": "string",
      "description": "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."
    },
    "TransferAccessToken": {
      "description": "The Plaid `access_token` for the account that will be debited or credited.",
      "type": "string"
    },
    "TransferAccountID": {
      "type": "string",
      "description": "The Plaid `account_id` corresponding to the end-user account that will be debited or credited."
    },
    "TransferAmount": {
      "title": "TransferAmount",
      "type": "string",
      "description": "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."
    },
    "TransferAuthorizationCustomAttributes": {
      "type": [
        "object",
        "null"
      ],
      "title": "TransferAuthorizationCustomAttributes",
      "maxProperties": 50,
      "additionalProperties": {
        "type": "string",
        "maxLength": 500
      },
      "description": "A free-form map of client-supplied risk-relevant context for this authorization. Plaid may use these attributes to inform future versions of our risk models.\n\nThe following limitations apply:\nKeys must match the regular expression `^[A-Za-z0-9_.-]{1,40}$`\nValues must be strings (no nested objects, arrays, numbers, or booleans allowed; stringify non-string values client-side)\nMaximum of 50 key/value pairs\nMaximum value length of 500 characters\n\nDo not include personally identifiable information or other sensitive data.\n"
    },
    "TransferAuthorizationDevice": {
      "title": "TransferAuthorizationDevice",
      "type": "object",
      "additionalProperties": true,
      "description": "Information about the device being used to initiate the authorization. These fields are not currently incorporated into the risk check.",
      "properties": {
        "ip_address": {
          "type": "string",
          "description": "The IP address of the device being used to initiate the authorization."
        },
        "user_agent": {
          "type": "string",
          "description": "The user agent of the device being used to initiate the authorization."
        }
      }
    },
    "TransferAuthorizationIdempotencyKey": {
      "title": "TransferAuthorizationIdempotencyKey",
      "type": [
        "string",
        "null"
      ],
      "maxLength": 50,
      "description": "A random key provided by the client, per unique authorization, which expires after 48 hours. Maximum of 50 characters.\n\nThe API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create an authorization fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single authorization is created.\n\nIdempotency does not apply to authorizations whose decisions are `user_action_required`. Therefore you may re-attempt the authorization after completing the required user action without changing `idempotency_key`.\n\nThis idempotency key expires after 48 hours, after which the same key can be reused. Failure to provide this key may result in duplicate charges."
    },
    "TransferAuthorizationUserInRequest": {
      "title": "TransferAuthorizationUserInRequest",
      "type": "object",
      "description": "The legal name and other information for the account holder.  If the account has multiple account holders, provide the information for the account holder on whose behalf the authorization is being requested. The `user.legal_name` field is required. Other fields are not currently used and are present to support planned future functionality.",
      "properties": {
        "legal_name": {
          "type": "string",
          "description": "The user's legal name. If the user is a business, provide the business name."
        },
        "phone_number": {
          "type": "string",
          "description": "The user's phone number."
        },
        "email_address": {
          "type": "string",
          "description": "The user's email address."
        },
        "address": {
          "$ref": "#/$defs/TransferUserAddressInRequest"
        }
      },
      "required": [
        "legal_name"
      ]
    },
    "TransferCreditFundsSource": {
      "type": [
        "string",
        "null"
      ],
      "title": "TransferCreditFundsSource",
      "deprecated": true,
      "enum": [
        "sweep",
        "prefunded_rtp_credits",
        "prefunded_ach_credits",
        null
      ],
      "description": "This field is now deprecated. You may ignore it for transfers created on and after 12/01/2023.\n\nSpecifies 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.\n\n`sweep` - Sweep funds from your funding account\n`prefunded_rtp_credits` - Use your prefunded RTP credit balance with Plaid\n`prefunded_ach_credits` - Use your prefunded ACH credit balance with Plaid"
    },
    "TransferMigratedFundingAccountIDRequest": {
      "type": [
        "string",
        "null"
      ],
      "description": "Specify the account used to fund the transfer. Should be specified if using legacy funding methods only. If using Plaid Ledger, leave this field blank. Customers can find a list of `funding_account_id`s in the Accounts page of your Plaid Dashboard, under the \"Account ID\" column. If this field is left blank and you are using legacy funding methods, this will default to the default `funding_account_id` specified during onboarding. Otherwise, Plaid Ledger will be used.",
      "x-hidden-from-docs": true
    },
    "TransferNetwork": {
      "type": "string",
      "title": "TransferNetwork",
      "description": "The network or rails used for the transfer.\n\nFor transfers submitted as `ach` or `same-day-ach`, the Standard ACH cutoff is 8:30 PM Eastern Time.\n\nFor transfers submitted as `same-day-ach`, the Same Day ACH cutoff is 3:00 PM Eastern Time.  It is recommended to send the request 15 minutes prior to the cutoff to ensure that it will be processed in time for submission before the cutoff. If the transfer is processed after this cutoff but before the Standard ACH cutoff, it will be sent over Standard ACH rails and will not incur same-day charges; this will apply to both legs of the transfer if applicable. The transaction limit for a Same Day ACH transfer is $1,000,000. Authorization requests sent with an amount greater than $1,000,000 will fail.\n\nFor transfers submitted as `rtp`, Plaid will automatically route between the Real-Time Payments (RTP) 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`.\n\nWire transfers are currently in early availability. To request access to `wire` as a payment network, contact your account manager. For transfers submitted as `wire`, the `type` must be `credit`; wire debits are not supported. The cutoff to submit a wire payment is 6:30 PM Eastern Time on a business day; wires submitted after that time will be processed on the next business day. The transaction limit for a wire is $999,999.99. Authorization requests sent with an amount greater than $999,999.99 will fail.\n\nSupport for `rfp` (request for payment) is currently in closed beta. To learn more, contact your Plaid account manager. For transfers submitted as `rfp`, the `type` must be `debit`.",
      "enum": [
        "ach",
        "same-day-ach",
        "rtp",
        "wire",
        "rfp"
      ]
    },
    "TransferPaymentProfileToken": {
      "description": "The payment profile token associated with the Payment Profile that will be debited or credited. Required if not using `access_token`.",
      "type": "string",
      "x-hidden-from-docs": true
    },
    "TransferType": {
      "type": "string",
      "title": "TransferType",
      "description": "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.",
      "enum": [
        "debit",
        "credit"
      ]
    },
    "TransferUserAddressInRequest": {
      "title": "TransferUserAddressInRequest",
      "type": "object",
      "description": "The address associated with the account holder.",
      "properties": {
        "street": {
          "type": "string",
          "description": "The street number and name (i.e., \"100 Market St.\")."
        },
        "city": {
          "type": "string",
          "description": "Ex. \"San Francisco\""
        },
        "region": {
          "type": "string",
          "description": "The state or province (e.g., \"CA\")."
        },
        "postal_code": {
          "type": "string",
          "description": "The postal code (e.g., \"94103\")."
        },
        "country": {
          "type": "string",
          "description": "A two-letter country code (e.g., \"US\")."
        }
      }
    },
    "TransferWireDetails": {
      "title": "TransferWireDetails",
      "type": [
        "object",
        "null"
      ],
      "description": "Information specific to wire transfers.",
      "properties": {
        "message_to_beneficiary": {
          "type": [
            "string",
            "null"
          ],
          "description": "Additional information from the wire originator to the beneficiary. Max 140 characters."
        },
        "wire_return_fee": {
          "type": [
            "string",
            "null"
          ],
          "description": "The fee amount deducted from the original transfer during a wire return, if applicable."
        }
      }
    }
  }
}