Stripe: Create a transfer

← Transfers operations · Get started

Operation stripe.posttransfers

Provider route: POST /v1/transfers. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/stripe with npm, or alter-sdk-stripe with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { StripeIntegration } from "@alter-ai/stripe";

async function execute(input: Parameters<StripeIntegration["transfers"]["postTransfers"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new StripeIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.transfers.postTransfers(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_stripe import StripeIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = StripeIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.transfers.post_transfers(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
headers	object	Optional	Additional keys: not allowed
headers.Idempotency-Key	string	Optional	Minimum length: 1 Maximum length: 255
body	object	Required within parent	Additional keys: not allowed
body.amount	integer	Optional	A positive integer in cents (or local equivalent) representing how much to transfer.
body.currency	string	Required within parent	Three-letter [ISO code for currency](https://www.iso.org/iso-4217-currency-codes.html) in lowercase. Must be a [supported currency](https://docs.stripe.com/currencies). Format: currency
body.description	string	Optional	An arbitrary string attached to the object. Often useful for displaying to users. Maximum length: 5000
body.destination	string	Required within parent	The ID of a connected Stripe account. <a href=“/docs/connect/separate-charges-and-transfers”>See the Connect documentation</a> for details.
body.expand	array	Optional	Specifies which fields in the response should be expanded.
body.expand[]	string	Each item	Maximum length: 5000
body.metadata	object	Optional	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`. Additional keys: see wildcard field
body.metadata.*	string	Additional keys
body.source_transaction	string	Optional	You can use this parameter to transfer funds from a charge before they are added to your available balance. A pending balance will transfer immediately but the funds will not become available until the original charge becomes available. [See the Connect documentation](https://docs.stripe.com/connect/separate-charges-and-transfers#transfer-availability) for details.
body.source_type	string	Optional	The source balance to use for this transfer. One of `bank_account`, `card`, or `fpx`. For most users, this will default to `card`. One of: bank_account, card, fpx Maximum length: 5000
body.transfer_group	string	Optional	A string that identifies this transaction as part of a group. See the [Connect documentation](https://docs.stripe.com/connect/separate-charges-and-transfers#transfer-options) for details.

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Create a transfer — response body

Referenced models: Create a transfer — response body

Schemas

704 more schemas are linked from the tables above, on the schema pages.

Create a transfer — response body

Field	Type	Presence	Description and constraints
$	object	Root	A `Transfer` object is created when you move funds between Stripe accounts as part of Connect. Before April 6, 2017, transfers also represented movement of funds from a Stripe account to a card or bank account. This behavior has since been split out into a [Payout](https://docs.stripe.com/api#payout_object) object, with corresponding payout endpoints. For more information, read about the [transfer/payout split](https://docs.stripe.com/transfer-payout-split). Related guide: [Creating separate charges and transfers](https://docs.stripe.com/connect/separate-charges-and-transfers)
amount	JSON	Required within parent
amount (anyOf 1)	integer	Alternative	Amount in cents (or local equivalent) to be transferred.
amount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
amount_reversed	JSON	Required within parent
amount_reversed (anyOf 1)	integer	Alternative	Amount in cents (or local equivalent) reversed (can be less than the amount attribute on the transfer if a partial reversal was issued).
amount_reversed (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
balance_transaction	JSON	Optional
balance_transaction (anyOf 1)	JSON	Alternative	Balance transaction that describes the impact of this transfer on your account balance.
balance_transaction (anyOf 1) (anyOf 1)	string	Alternative	Maximum length: 5000
balance_transaction (anyOf 1) (anyOf 2)	Model	Alternative	Expand Retrieve a balance transaction — balance get Balance History Id — response body
balance_transaction (anyOf 2)	null	Alternative
created	JSON	Required within parent
created (anyOf 1)	integer	Alternative	Time that this record of the transfer was first created. Format: unix-time
created (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
currency	string	Required within parent	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). Format: currency
description	JSON	Optional
description (anyOf 1)	string	Alternative	An arbitrary string attached to the object. Often useful for displaying to users. Maximum length: 5000
description (anyOf 2)	null	Alternative
destination	JSON	Optional
destination (anyOf 1)	JSON	Alternative	ID of the Stripe account the transfer was sent to.
destination (anyOf 1) (anyOf 1)	string	Alternative	Maximum length: 5000
destination (anyOf 1) (anyOf 2)	Model	Alternative	Expand Create an account — response body
destination (anyOf 2)	null	Alternative
destination_payment	JSON	Optional	If the destination is a Stripe account, this will be the ID of the payment that the destination account received for the transfer.
destination_payment (anyOf 1)	string	Alternative	Maximum length: 5000
destination_payment (anyOf 2)	Model	Alternative	Expand Create a charge — response body
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
livemode	boolean	Required within parent	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
metadata	object	Required within parent	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Additional keys: see wildcard field
metadata.*	string	Additional keys	Maximum length: 500
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: transfer
reversals	object	Required within parent	A list of reversals that have been applied to the transfer.
reversals.data	array	Required within parent	Details about each object.
reversals.data[]	Model	Each item	Expand Update a reversal — response body
reversals.has_more	boolean	Required within parent	True if this list has another page of items after this one that can be fetched.
reversals.object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Always has the value `list`. Known values: list
reversals.url	string	Required within parent	The URL where this list can be accessed. Maximum length: 5000
reversed	boolean	Required within parent	Whether the transfer has been fully reversed. If the transfer is only partially reversed, this attribute will still be false.
source_transaction	JSON	Optional
source_transaction (anyOf 1)	JSON	Alternative	ID of the charge that was used to fund the transfer. If null, the transfer was funded from the available balance.
source_transaction (anyOf 1) (anyOf 1)	string	Alternative	Maximum length: 5000
source_transaction (anyOf 1) (anyOf 2)	Model	Alternative	Expand Create a charge — response body
source_transaction (anyOf 2)	null	Alternative
source_type	string	Optional	The source balance this transfer came from. One of `card`, `fpx`, or `bank_account`. Maximum length: 5000
transfer_group	JSON	Optional
transfer_group (anyOf 1)	string	Alternative	A string that identifies this transaction as part of a group. See the [Connect documentation](https://docs.stripe.com/connect/separate-charges-and-transfers#transfer-options) for details. Maximum length: 5000
transfer_group (anyOf 2)	null	Alternative

Referenced models: Create an account — response body, Retrieve a balance transaction — balance get Balance History Id — response body, Create a charge — response body, Update a reversal — response body

Create an account — response body — groups The groups associated with the account payments pricing

Field	Type	Presence	Description and constraints
$	object	Root
payments_pricing	JSON	Optional
payments_pricing (anyOf 1)	string	Alternative	The group the account is in to determine their payments pricing, and null if the account is on customized pricing. [See the Platform pricing tool documentation](https://docs.stripe.com/connect/platform-pricing-tools) for details. Maximum length: 5000
payments_pricing (anyOf 2)	null	Alternative

Create an account — response body — tos acceptance

Field	Type	Presence	Description and constraints
$	object	Root
date	JSON	Optional
date (anyOf 1)	JSON	Alternative
date (anyOf 1) (anyOf 1)	integer	Alternative	The Unix timestamp marking when the account representative accepted their service agreement Format: unix-time
date (anyOf 1) (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
date (anyOf 2)	null	Alternative
ip	JSON	Optional
ip (anyOf 1)	string	Alternative	The IP address from which the account representative accepted their service agreement Maximum length: 5000
ip (anyOf 2)	null	Alternative
service_agreement	string	Optional	The user's service agreement type Maximum length: 5000
user_agent	JSON	Optional
user_agent (anyOf 1)	string	Alternative	The user agent of the browser from which the account representative accepted their service agreement Maximum length: 5000
user_agent (anyOf 2)	null	Alternative

Create an account — response body — controller

Field	Type	Presence	Description and constraints
$	object	Root
fees	Model	Optional	Expand Create an account — response body — controller fees
is_controller	boolean	Optional	`true` if the Connect application retrieving the resource controls the account and can therefore exercise [platform controls](https://docs.stripe.com/connect/platform-controls-for-standard-accounts). Otherwise, this field is null.
losses	Model	Optional	Expand Create an account — response body — controller losses
requirement_collection	string	Optional	A value indicating responsibility for collecting requirements on this account. Only returned when the Connect application retrieving the resource controls the account. Known values: application, stripe
stripe_dashboard	Model	Optional	Expand Create an account — response body — controller stripe dashboard
type	string	Required within parent	The controller type. Can be `application`, if a Connect application controls the account, or `account`, if the account controls itself. Known values: account, application

Referenced models: Create an account — response body — controller fees, Create an account — response body — controller losses, Create an account — response body — controller stripe dashboard

Create an account — response body — settings value bacs debit payments, branding, card issuing, card payments, dashboard, invoices, payments, payouts, paypay payments, sepa debit payments, treasury sepa debit payments

Field	Type	Presence	Description and constraints
$	object	Root
creditor_id	string	Optional	SEPA creditor identifier that identifies the company making the payment. Maximum length: 5000

Policy, approvals and errors

SDK function policy ID: stripe.posttransfers. Catalog operation: PostTransfers. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"Stripe-Version": "2026-09-30.endive"}

Official provider source