Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Payment Records
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks

The Transfer object 

Attributes

  • idstring

    Unique identifier for the object.

  • amountinteger

    Amount in cents 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.

  • metadataobject

    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

  • 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": "tr_1MiN3gLkdIwHu7ixNCZvFdgA",
  "object": "transfer",
  "amount": 400,
  "amount_reversed": 0,
  "balance_transaction": "txn_1MiN3gLkdIwHu7ixxapQrznl",
  "created": 1678043844,
  "currency": "usd",
  "description": null,
  "destination": "acct_1MTfjCQ9PRzxEwkZ",
  "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 

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 cents representing how much to transfer.

  • descriptionstring

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

  • metadataobject

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

POST /v1/transfers
curl https://api.stripe.com/v1/transfers \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d amount=400 \
  -d currency=usd \
  -d destination=acct_1MTfjCQ9PRzxEwkZ \
  -d transfer_group=ORDER_95
Response
{
  "id": "tr_1MiN3gLkdIwHu7ixNCZvFdgA",
  "object": "transfer",
  "amount": 400,
  "amount_reversed": 0,
  "balance_transaction": "txn_1MiN3gLkdIwHu7ixxapQrznl",
  "created": 1678043844,
  "currency": "usd",
  "description": null,
  "destination": "acct_1MTfjCQ9PRzxEwkZ",
  "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 

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.

  • metadataobject

    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.

POST /v1/transfers/:id
curl https://api.stripe.com/v1/transfers/tr_1MiN3gLkdIwHu7ixNCZvFdgA \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d "metadata[order_id]"=6735
Response
{
  "id": "tr_1MiN3gLkdIwHu7ixNCZvFdgA",
  "object": "transfer",
  "amount": 400,
  "amount_reversed": 0,
  "balance_transaction": "txn_1MiN3gLkdIwHu7ixxapQrznl",
  "created": 1678043844,
  "currency": "usd",
  "description": null,
  "destination": "acct_1MTfjCQ9PRzxEwkZ",
  "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"
}

Retrieve a transfer 

Retrieves the details of an existing transfer. Supply the unique transfer ID from either a transfer creation request or the transfer list, and Stripe will return the corresponding transfer information.

Parameters

No parameters.

Returns

Returns a transfer object if a valid identifier was provided, and raises an error otherwise.

GET /v1/transfers/:id
curl https://api.stripe.com/v1/transfers/tr_1MiN3gLkdIwHu7ixNCZvFdgA \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"
Response
{
  "id": "tr_1MiN3gLkdIwHu7ixNCZvFdgA",
  "object": "transfer",
  "amount": 400,
  "amount_reversed": 0,
  "balance_transaction": "txn_1MiN3gLkdIwHu7ixxapQrznl",
  "created": 1678043844,
  "currency": "usd",
  "description": null,
  "destination": "acct_1MTfjCQ9PRzxEwkZ",
  "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"
}

List all transfers 

Returns a list of existing transfers sent to connected accounts. The transfers are returned in sorted order, with the most recently created transfers appearing first.

Parameters

  • destinationstring

    Only return transfers for the destination specified by this account ID.

More parameters

  • createdobject

  • ending_beforestring

  • limitinteger

  • starting_afterstring

  • transfer_groupstring

Returns

A dictionary with a data property that contains an array of up to limit transfers, starting after transfer starting_after. Each entry in the array is a separate transfer object. If no more transfers are available, the resulting array will be empty.

GET /v1/transfers
curl -G https://api.stripe.com/v1/transfers \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d limit=3
Response
{
  "object": "list",
  "url": "/v1/transfers",
  "has_more": false,
  "data": [
    {
      "id": "tr_1MiN3gLkdIwHu7ixNCZvFdgA",
      "object": "transfer",
      "amount": 400,
      "amount_reversed": 0,
      "balance_transaction": "txn_1MiN3gLkdIwHu7ixxapQrznl",
      "created": 1678043844,
      "currency": "usd",
      "description": null,
      "destination": "acct_1MTfjCQ9PRzxEwkZ",
      "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"
    }
  ]
}