Core Resources
Payment Methods
Products
Commerce
Agentic Commerce
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury for Platforms
Payment Records
Account Evaluation
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

The Transfer object

Attributes

  • idstring

    Unique identifier for the object.

  • amountinteger

    Amount in the smallest currency unit to be transferred.

  • currencyenum

    Three-letter ISO currency code, in lowercase. Must be a supported currency.

  • descriptionnullable string

    An arbitrary string attached to the object. Often useful for displaying to users.

  • destinationnullable stringExpandable

    ID of the Stripe account the transfer was sent to.

  • metadatamap

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

More attributes

  • objectstring, value is "transfer"

  • amount_reversedinteger

  • balance_transactionnullable stringExpandable

  • createdtimestamp

  • destination_paymentnullable stringExpandable

  • livemodeboolean

  • reversalsobject

  • reversedboolean

  • source_transactionnullable stringExpandable

  • source_typenullable string

  • transfer_groupnullable string

The Transfer object
{
  "id": "",
  "object": "transfer",
  "amount": 400,
  "amount_reversed": 0,
  "balance_transaction": "",
  "created": 1678043844,
  "currency": "usd",
  "description": null,
  "destination": "",
  "destination_payment": "py_1MiN3gQ9PRzxEwkZWTPGNq9o",
  "livemode": false,
  "metadata": {},
  "reversals": {
    "object": "list",
    "data": [],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_1MiN3gLkdIwHu7ixNCZvFdgA/reversals"
  },
  "reversed": false,
  "source_transaction": null,
  "source_type": "card",
  "transfer_group": "ORDER_95"
}

Create a transfer

POST /v1/transfers

To send funds from your Stripe account to a connected account, you create a new transfer object. Your Stripe balance must be able to cover the transfer amount, or you’ll receive an “Insufficient Funds” error.

Parameters

  • currencyenumRequired

    Three-letter ISO code for currency in lowercase. Must be a supported currency.

  • destinationstringRequired

    The ID of a connected Stripe account. See the Connect documentation for details.

  • amountintegerRequired

    A positive integer in the smallest currency unit representing how much to transfer.

  • descriptionstring

    An arbitrary string attached to the object. Often useful for displaying to users.

  • metadatamap

    Set of key-value pairs 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.

More parameters

  • source_transactionstring

  • source_typestring

  • transfer_groupstring

Returns

Returns a transfer object if there were no initial errors with the transfer creation (e.g., insufficient funds).

curl https://api.stripe.com/v1/transfers \
  -u "sk_test_BQokikJOvBiI2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d amount=400 \
  -d currency=usd \
  -d destination= \
  -d transfer_group=ORDER_95
Response
{
  "id": "",
  "object": "transfer",
  "amount": 400,
  "amount_reversed": 0,
  "balance_transaction": "",
  "created": 1678043844,
  "currency": "usd",
  "description": null,
  "destination": "",
  "destination_payment": "py_1MiN3gQ9PRzxEwkZWTPGNq9o",
  "livemode": false,
  "metadata": {},
  "reversals": {
    "object": "list",
    "data": [],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_1MiN3gLkdIwHu7ixNCZvFdgA/reversals"
  },
  "reversed": false,
  "source_transaction": null,
  "source_type": "card",
  "transfer_group": "ORDER_95"
}

Update a transfer

POST /v1/transfers/:id

Updates the specified transfer by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

This request accepts only metadata as an argument.

Parameters

  • descriptionstring

    An arbitrary string attached to the object. Often useful for displaying to users.

  • metadatamap

    Set of key-value pairs 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.

Returns

Returns the transfer object if the update succeeded. This call will raise an error if update parameters are invalid.

curl https://api.stripe.com/v1/transfers/ \
  -u "sk_test_BQokikJOvBiI2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d "metadata[order_id]=6735"
Response
{
  "id": "",
  "object": "transfer",
  "amount": 400,
  "amount_reversed": 0,
  "balance_transaction": "",
  "created": 1678043844,
  "currency": "usd",
  "description": null,
  "destination": "",
  "destination_payment": "py_1MiN3gQ9PRzxEwkZWTPGNq9o",
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "reversals": {
    "object": "list",
    "data": [],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/transfers/tr_1MiN3gLkdIwHu7ixNCZvFdgA/reversals"
  },
  "reversed": false,
  "source_transaction": null,
  "source_type": "card",
  "transfer_group": "ORDER_95"
}