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

Outbound Transfers v2

Learn more about calling API v2 endpoints.

OutboundTransfer represents a single money movement from one FinancialAccount you own to a payout method you also own.

Endpoints

The OutboundTransfer object 

Attributes

  • idstring

    Unique identifier for the OutboundTransfer.

  • objectstring, value is "v2.money_management.outbound_transfer"

    String representing the object’s type. Objects of the same type share the same value of the object field.

  • amountobject

    The “presentment amount” for the OutboundTransfer.

  • cancelableboolean

    Returns true if the OutboundTransfer can be canceled, and false otherwise.

  • createdtimestamp

    Time at which the OutboundTransfer was created. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.

  • delivery_optionsnullable object

    Delivery options to be used to send the OutboundTransfer.

  • descriptionnullable string

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

  • expected_arrival_datenullable timestamp

    The date when funds are expected to arrive in the payout method. This field is not set if the payout method is in a failed, canceled, or returned state. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.

  • fromobject

    The FinancialAccount that funds were pulled from.

  • livemodeboolean

    Has the value true if the object exists in live mode or the value false if the object exists in test mode.

  • metadatanullable map

    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.

  • receipt_urlnullable string

    A link to the Stripe-hosted receipt for this OutboundTransfer. The receipt link remains active for 60 days from the OutboundTransfer creation date. After this period, the link will expire and the receipt url value will be null.

  • statement_descriptorstring

    The description that appears on the receiving end for an OutboundTransfer (for example, bank statement for external bank transfer).

  • statusenum

    Current status of the OutboundTransfer: processing, failed, posted, returned, canceled. An OutboundTransfer is processing if it has been created and is processing. The status changes to posted once the OutboundTransfer has been “confirmed” and funds have left the account, or to failed or canceled. If an OutboundTransfer fails to arrive at its payout method, its status will change to returned.

    Possible enum values
    canceled

    A user canceled the OutboundTransfer before posting. Stripe returns the funds to the user by voiding the pending Transaction.

    failed

    The OutboundTransfer failed to confirm. Stripe returns the funds to the user by voiding the pending Transaction.

    posted

    The OutboundTransfer posted and funds have left the account. The underlying Transaction posts.

    processing

    The OutboundTransfer starting state. Funds are “held” by a pending Transaction (but are still part of the current balance). The OutboundTransfer might be cancelable by the user, depending on the value of the cancelable field.

    returned

    The OutboundTransfer failed to successfully arrive at the destination. Funds return to the user with a second posted Transaction attached to the same flow.

  • status_detailsnullable object

    Status details for an OutboundTransfer in a failed or returned state.

  • status_transitionsnullable object

    Hash containing timestamps of when the object transitioned to a particular status.

  • toobject

    To which payout method the OutboundTransfer was sent.

  • trace_idobjectPreview feature

    A unique identifier that can be used to track this OutboundTransfer with recipient bank. Banks might call this a “reference number” or something similar.

The OutboundTransfer object
{
  "id": "obt_test_65OAfZuGepEX92sRECO16NybHIZ4SQ3LORe4rpuNGDIDb6",
  "object": "v2.money_management.outbound_transfer",
  "from": {
    "financial_account": "fa_test_65NybHaQx7KJxDc22rZ16NybHIZ4SQ3LORe4rpuNGDIXEO",
    "debited": {
      "value": 50,
      "currency": "usd"
    }
  },
  "to": {
    "payout_method": "usba_test_61NyccB7UY8KzlWh916NybHIZ4SQ3LORe4rpuNGDIRWC",
    "credited": {
      "value": 50,
      "currency": "usd"
    }
  },
  "delivery_options": {
    "bank_account": "automatic"
  },
  "amount": {
    "value": 50,
    "currency": "usd"
  },
  "statement_descriptor": "Stripe payout",
  "cancelable": true,
  "description": "Paying out Stripe earnings",
  "status": "pending",
  "status_transitions": {
    "canceled_at": null,
    "failed_at": null,
    "posted_at": null,
    "returned_at": null
  },
  "status_details": null,
  "created": "2023-04-26T23:19:35.123Z",
  "expected_arrival_date": "2023-04-28T00:00:00Z",
  "receipt_url": "https://payments.stripe.com/transaction_receipt/CCMaIwohd2tzcF90ZXN0XzZOeWJISVo0U1EzTE9SZTRycHVOR0RJKJLjpqIGMgb4C6zLsmw6SJS1ua8HSKbV2I5kVA6XOZ553eVPu8d3RUAxIsLylBkQcU9X1Ljx2U3j33Or9GNxKKizf9YGvg1aDEohr4VnhlRVBZpF6maT0w",
  "trace_id": {
    "status": "processing",
    "value": ""
  }
}

Create an OutboundTransfer object v2

Learn more about calling API v2 endpoints.

Creates an OutboundTransfer.

Parameters

  • amountobjectRequired

    The “presentment amount” for the OutboundPayment.

  • fromobjectRequired

    The FinancialAccount to pull funds from.

  • toobjectRequired

    To which payout method to send the OutboundTransfer.

  • delivery_optionsobject

    Delivery options to be used to send the OutboundTransfer.

  • descriptionstring

    An arbitrary string attached to the OutboundTransfer. 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.

Returns

Response attributes

  • idstring

    Unique identifier for the OutboundTransfer.

  • objectstring, value is "v2.money_management.outbound_transfer"

    String representing the object’s type. Objects of the same type share the same value of the object field.

  • amountobject

    The “presentment amount” for the OutboundTransfer.

  • cancelableboolean

    Returns true if the OutboundTransfer can be canceled, and false otherwise.

  • createdtimestamp

    Time at which the OutboundTransfer was created. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.

  • delivery_optionsnullable object

    Delivery options to be used to send the OutboundTransfer.

  • descriptionnullable string

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

  • expected_arrival_datenullable timestamp

    The date when funds are expected to arrive in the payout method. This field is not set if the payout method is in a failed, canceled, or returned state. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.

  • fromobject

    The FinancialAccount that funds were pulled from.

  • livemodeboolean

    Has the value true if the object exists in live mode or the value false if the object exists in test mode.

  • metadatanullable map

    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.

  • receipt_urlnullable string

    A link to the Stripe-hosted receipt for this OutboundTransfer. The receipt link remains active for 60 days from the OutboundTransfer creation date. After this period, the link will expire and the receipt url value will be null.

  • statement_descriptorstring

    The description that appears on the receiving end for an OutboundTransfer (for example, bank statement for external bank transfer).

  • statusenum

    Current status of the OutboundTransfer: processing, failed, posted, returned, canceled. An OutboundTransfer is processing if it has been created and is processing. The status changes to posted once the OutboundTransfer has been “confirmed” and funds have left the account, or to failed or canceled. If an OutboundTransfer fails to arrive at its payout method, its status will change to returned.

    Possible enum values
    canceled

    A user canceled the OutboundTransfer before posting. Stripe returns the funds to the user by voiding the pending Transaction.

    failed

    The OutboundTransfer failed to confirm. Stripe returns the funds to the user by voiding the pending Transaction.

    posted

    The OutboundTransfer posted and funds have left the account. The underlying Transaction posts.

    processing

    The OutboundTransfer starting state. Funds are “held” by a pending Transaction (but are still part of the current balance). The OutboundTransfer might be cancelable by the user, depending on the value of the cancelable field.

    returned

    The OutboundTransfer failed to successfully arrive at the destination. Funds return to the user with a second posted Transaction attached to the same flow.

  • status_detailsnullable object

    Status details for an OutboundTransfer in a failed or returned state.

  • status_transitionsnullable object

    Hash containing timestamps of when the object transitioned to a particular status.

  • toobject

    To which payout method the OutboundTransfer was sent.

  • trace_idobjectPreview feature

    A unique identifier that can be used to track this OutboundTransfer with recipient bank. Banks might call this a “reference number” or something similar.

Error Codes
400outbound_transfer_amount_too_large_for_selected_delivery_option

Error returned when user selected a delivery option but the specified amount exceeds the method limits.

400outbound_transfer_card_payout_method_unsupported

Error returned when the payout method in the OutboundTransfer request is a card which is not currently supported.

400outbound_transfer_cop_not_accepted

Error returned when the Confirmation of Payee is not accepted.

400outbound_transfer_delivery_option_not_supported

Error returned when the selected delivery option is not supported for the payout method.

400outbound_transfer_from_balance_unsupported_currency

Error returned when the balance type in the OutboundTransfer request does not support the provided currency.

400outbound_transfer_insufficient_funds

Error returned when the balance of provided financial account and balance type in the OutboundTransfer request does not have enough funds.

400outbound_transfer_invalid_payout_method_country

Error returned when the payout method country does not match the sender account country.

400outbound_transfer_no_suitable_delivery_options_for_large_amount

Error returned when user does not specify the delivery option or provides automatic, and the amount exceeds all the possible delivery options for this payout method allows.

400outbound_transfer_not_allowed

Error returned when the user is not allowed to make this OutboundTransfer request.

404outbound_transfer_from_balance_type_not_found

Error returned when balance type of provided financial account in the OutboundTransfer request cannot be identified.

404outbound_transfer_from_financial_account_not_found

Error returned when financial account in the OutboundTransfer request cannot be identified.

404outbound_transfer_invalid_payout_method

Error returned when the payout method in the OutboundTransfer request cannot be identified.

409idempotency_error

An idempotent retry occurred with different request parameters.

POST /v2/money_management/outbound_transfers
curl -X POST https://api.stripe.com/v2/money_management/outbound_transfers \
  -H "Authorization: Bearer {{YOUR_API_KEY}}{{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2025-04-30.preview" \
  --json '{
    "from": {
        "financial_account": "fa_test_65NybHaQx7KJxDc22rZ16NybHIZ4SQ3LORe4rpuNGDIXEO",
        "currency": "usd"
    },
    "to": {
        "payout_method": "usba_test_61NyccB7UY8KzlWh916NybHIZ4SQ3LORe4rpuNGDIRWC",
        "currency": "usd"
    },
    "amount": {
        "value": 50,
        "currency": "usd"
    },
    "description": "Paying out Stripe earnings"
  }'
Response
{
  "id": "obt_test_65OAfYe4XKyMwZeHlcV16NybHIZ4SQ3LORe4rpuNGDIRZw",
  "object": "v2.money_management.outbound_transfer",
  "from": {
    "financial_account": "fa_test_65NybHaQx7KJxDc22rZ16NybHIZ4SQ3LORe4rpuNGDIXEO",
    "debited": {
      "value": 50,
      "currency": "usd"
    }
  },
  "to": {
    "credited": {
      "value": 50,
      "currency": "usd"
    },
    "payout_method": "usba_test_61NyccB7UY8KzlWh916NybHIZ4SQ3LORe4rpuNGDIRWC"
  },
  "delivery_options": {
    "bank_account": "automatic"
  },
  "amount": {
    "value": 50,
    "currency": "usd"
  },
  "statement_descriptor": "Stripe payout",
  "cancelable": true,
  "description": "Paying out Stripe earnings",
  "status": "processing",
  "status_transitions": {
    "canceled_at": null,
    "failed_at": null,
    "posted_at": null,
    "returned_at": null
  },
  "status_details": null,
  "created": "2023-04-26T23:18:16.777Z",
  "expected_arrival_date": "2023-04-28T00:00:00Z",
  "receipt_url": "https://payments.stripe.com/transaction_receipt/CCMaIwohd2tzcF90ZXN0XzZOeWJISVo0U1EzTE9SZTRycHVOR0RJKLjipqIGMgYk_Zatd6o6SJTkdgTDenznPtxy9kHSWhpBX0QEYqbR8_OPno6qVa79eu4rNCFiXFjzwfzKlMF16O028YAwyJ2T1sRMDLkbsqtVSR5r4dV-nw",
  "trace_id": {
    "status": "pending",
    "value": ""
  }
}

Retrieve an OutboundTransfer object v2

Learn more about calling API v2 endpoints.

Retrieves the details of an existing OutboundTransfer by passing the unique OutboundTransfer ID from either the OutboundPayment create or list response.

Parameters

  • idstringRequired

    The ID of the OutboundTransfer to retrieve.

Returns

Response attributes

  • idstring

    Unique identifier for the OutboundTransfer.

  • objectstring, value is "v2.money_management.outbound_transfer"

    String representing the object’s type. Objects of the same type share the same value of the object field.

  • amountobject

    The “presentment amount” for the OutboundTransfer.

  • cancelableboolean

    Returns true if the OutboundTransfer can be canceled, and false otherwise.

  • createdtimestamp

    Time at which the OutboundTransfer was created. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.

  • delivery_optionsnullable object

    Delivery options to be used to send the OutboundTransfer.

  • descriptionnullable string

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

  • expected_arrival_datenullable timestamp

    The date when funds are expected to arrive in the payout method. This field is not set if the payout method is in a failed, canceled, or returned state. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.

  • fromobject

    The FinancialAccount that funds were pulled from.

  • livemodeboolean

    Has the value true if the object exists in live mode or the value false if the object exists in test mode.

  • metadatanullable map

    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.

  • receipt_urlnullable string

    A link to the Stripe-hosted receipt for this OutboundTransfer. The receipt link remains active for 60 days from the OutboundTransfer creation date. After this period, the link will expire and the receipt url value will be null.

  • statement_descriptorstring

    The description that appears on the receiving end for an OutboundTransfer (for example, bank statement for external bank transfer).

  • statusenum

    Current status of the OutboundTransfer: processing, failed, posted, returned, canceled. An OutboundTransfer is processing if it has been created and is processing. The status changes to posted once the OutboundTransfer has been “confirmed” and funds have left the account, or to failed or canceled. If an OutboundTransfer fails to arrive at its payout method, its status will change to returned.

    Possible enum values
    canceled

    A user canceled the OutboundTransfer before posting. Stripe returns the funds to the user by voiding the pending Transaction.

    failed

    The OutboundTransfer failed to confirm. Stripe returns the funds to the user by voiding the pending Transaction.

    posted

    The OutboundTransfer posted and funds have left the account. The underlying Transaction posts.

    processing

    The OutboundTransfer starting state. Funds are “held” by a pending Transaction (but are still part of the current balance). The OutboundTransfer might be cancelable by the user, depending on the value of the cancelable field.

    returned

    The OutboundTransfer failed to successfully arrive at the destination. Funds return to the user with a second posted Transaction attached to the same flow.

  • status_detailsnullable object

    Status details for an OutboundTransfer in a failed or returned state.

  • status_transitionsnullable object

    Hash containing timestamps of when the object transitioned to a particular status.

  • toobject

    To which payout method the OutboundTransfer was sent.

  • trace_idobjectPreview feature

    A unique identifier that can be used to track this OutboundTransfer with recipient bank. Banks might call this a “reference number” or something similar.

Error Codes
404not_found

The resource wasn’t found.

GET /v2/money_management/outbound_transfers/:id
curl https://api.stripe.com/v2/money_management/outbound_transfers/obt_test_65OAfZuGepEX92sRECO16NybHIZ4SQ3LORe4rpuNGDIDb6 \
  -H "Authorization: Bearer {{YOUR_API_KEY}}{{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2025-04-30.preview"
Response
{
  "id": "obt_test_65OAfZuGepEX92sRECO16NybHIZ4SQ3LORe4rpuNGDIDb6",
  "object": "v2.money_management.outbound_transfer",
  "from": {
    "financial_account": "fa_test_65NybHaQx7KJxDc22rZ16NybHIZ4SQ3LORe4rpuNGDIXEO",
    "debited": {
      "value": 50,
      "currency": "usd"
    }
  },
  "to": {
    "payout_method": "usba_test_61NyccB7UY8KzlWh916NybHIZ4SQ3LORe4rpuNGDIRWC",
    "credited": {
      "value": 50,
      "currency": "usd"
    }
  },
  "delivery_options": {
    "bank_account": "automatic"
  },
  "amount": {
    "value": 50,
    "currency": "usd"
  },
  "statement_descriptor": "Stripe payout",
  "cancelable": true,
  "description": "Paying out Stripe earnings",
  "status": "pending",
  "status_transitions": {
    "canceled_at": null,
    "failed_at": null,
    "posted_at": null,
    "returned_at": null
  },
  "status_details": null,
  "created": "2023-04-26T23:19:35.123Z",
  "expected_arrival_date": "2023-04-28T00:00:00Z",
  "receipt_url": "https://payments.stripe.com/transaction_receipt/CCMaIwohd2tzcF90ZXN0XzZOeWJISVo0U1EzTE9SZTRycHVOR0RJKJLjpqIGMgb4C6zLsmw6SJS1ua8HSKbV2I5kVA6XOZ553eVPu8d3RUAxIsLylBkQcU9X1Ljx2U3j33Or9GNxKKizf9YGvg1aDEohr4VnhlRVBZpF6maT0w",
  "trace_id": {
    "status": "processing",
    "value": ""
  }
}

List all OutboundTransfer objects v2

Learn more about calling API v2 endpoints.

Returns a list of OutboundTransfers that match the provided filters.

Parameters

  • createdtimestamp

    Filter for objects created at the specified timestamp. Must be an RFC 3339 date & time value, for example: 2022-09-18T13:22:00Z.

  • created_gttimestamp

    Filter for objects created after the specified timestamp. Must be an RFC 3339 date & time value, for example: 2022-09-18T13:22:00Z.

  • created_gtetimestamp

    Filter for objects created on or after the specified timestamp. Must be an RFC 3339 date & time value, for example: 2022-09-18T13:22:00Z.

  • created_lttimestamp

    Filter for objects created before the specified timestamp. Must be an RFC 3339 date & time value, for example: 2022-09-18T13:22:00Z.

  • created_ltetimestamp

    Filter for objects created on or before the specified timestamp. Must be an RFC 3339 date & time value, for example: 2022-09-18T13:22:00Z.

  • limitinteger

    The maximum number of results to return.

  • pagestring

    The page token to use to retrieve the page being requested.

  • statusarray of enums

    Closed Enum. Only return OutboundTransfers with this status.

    Possible enum values
    canceled

    A user canceled the OutboundTransfer before posting. Stripe returns the funds to the user by voiding the pending Transaction.

    failed

    The OutboundTransfer failed to confirm. Stripe returns the funds to the user by voiding the pending Transaction.

    posted

    The OutboundTransfer posted and funds have left the account. The underlying Transaction posts.

    processing

    The OutboundTransfer starting state. Funds are “held” by a pending Transaction (but are still part of the current balance). The OutboundTransfer might be cancelable by the user, depending on the value of the cancelable field.

    returned

    The OutboundTransfer failed to successfully arrive at the destination. Funds return to the user with a second posted Transaction attached to the same flow.

Returns

Response attributes

  • dataarray of objects

    The OutboundTransfers retrieved.

  • next_page_urlnullable string

    The URL for the next page of results.

  • previous_page_urlnullable string

    The URL for the previous page of results.

Error Codes
400outbound_transfer_invalid_page_token

Error returned when the page token provided in the OutboundTransfers list request is invalid.

GET /v2/money_management/outbound_transfers
curl -G https://api.stripe.com/v2/money_management/outbound_transfers \
  -H "Authorization: Bearer {{YOUR_API_KEY}}{{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2025-04-30.preview" \
  -d status=processing
Response
{
  "data": [
    {
      "id": "obt_test_65OAfZuGepEX92sRECO16NybHIZ4SQ3LORe4rpuNGDIDb6",
      "object": "v2.money_management.outbound_transfer",
      "from": {
        "financial_account": "fa_test_65NybHaQx7KJxDc22rZ16NybHIZ4SQ3LORe4rpuNGDIXEO",
        "debited": {
          "value": 50,
          "currency": "usd"
        }
      },
      "to": {
        "payout_method": "usba_test_61NyccB7UY8KzlWh916NybHIZ4SQ3LORe4rpuNGDIRWC",
        "credited": {
          "value": 50,
          "currency": "usd"
        }
      },
      "delivery_options": {
        "bank_account": "automatic"
      },
      "amount": {
        "value": 50,
        "currency": "usd"
      },
      "statement_descriptor": "Stripe payout",
      "cancelable": true,
      "description": "Paying out Stripe earnings",
      "status": "processing",
      "status_transitions": {
        "canceled_at": null,
        "failed_at": null,
        "posted_at": null,
        "returned_at": null
      },
      "status_details": null,
      "created": "2023-04-26T23:19:35.123Z",
      "expected_arrival_date": "2023-04-28T00:00:00Z",
      "receipt_url": "https://payments.stripe.com/transaction_receipt/CCMaIwohd2tzcF90ZXN0XzZOeWJISVo0U1EzTE9SZTRycHVOR0RJKLnjpqIGMgZNKstJGOg6SJSQrFGi6Bb85dAepu7uG2MVwM9VElVM0ekthEzf2MRmX19dnfFuZpKcVeukNldg5CAYFdFCUWWc_AHfQyYgL7fSAUONrbxPhg",
      "trace_id": {
        "status": "pending",
        "value": ""
      }
    },
    {
      "id": "obt_test_65OAfYe4XKyMwZeHlcV16NybHIZ4SQ3LORe4rpuNGDIRZw",
      "object": "v2.money_management.outbound_transfer",
      "from": {
        "financial_account": "fa_test_65NybHaQx7KJxDc22rZ16NybHIZ4SQ3LORe4rpuNGDIXEO",
        "debited": {
          "value": 80,
          "currency": "usd"
        }
      },
      "to": {
        "payout_method": "usba_test_61NyccB7UY8KzlWh916NybHIZ4SQ3LORe4rpuNGDIRWC",
        "credited": {
          "value": 80,
          "currency": "usd"
        }
      },
      "delivery_options": {
        "bank_account": "automatic"
      },
      "amount": {
        "value": 80,
        "currency": "usd"
      },
      "statement_descriptor": "Stripe payout",
      "cancelable": false,
      "description": "Paying out Stripe earnings",
      "status": "canceled",
      "status_transitions": {
        "canceled_at": "2023-04-26T23:18:28.412Z",
        "failed_at": null,
        "posted_at": null,
        "returned_at": null
      },
      "status_details": null,
      "created": "2023-04-26T23:18:16.777Z",
      "expected_arrival_date": "2023-04-28T00:00:00Z",
      "receipt_url": "https://payments.stripe.com/transaction_receipt/CCMaIwohd2tzcF90ZXN0XzZOeWJISVo0U1EzTE9SZTRycHVOR0RJKLnjpqIGMgZ4ixuDAAY6SJQGxQoU7gIawmH6g8uvKmtgds_fctxW9OclrMHT0XrtLo5HV8bCBdjfFxZ9UIQqiEvXN78CMyXlPu5gyap_a3jtVVdFeid7vw",
      "trace_id": {
        "status": "pending",
        "value": ""
      }
    }
  ],
  "next_page_url": null,
  "previous_page_url": null
}