Create an InboundTransfer object v2

Money Management

Inbound Transfers

Create an InboundTransfer object

InboundTransfers APIs are used to create, retrieve or list InboundTransfers.

Learn more about calling API v2 endpoints.

Parameters

amountobjectRequired
The amount, in specified currency, by which the FinancialAccount balance will increase due to the InboundTransfer.
- amount.currencystringRequired
  A lowercase alpha3 currency code like “usd”.
- amount.valueintegerRequired
  In minor units like 123 for 1.23 USD.

fromobjectRequired
Object containing details about where the funds will originate from.
- from.currencystring
  An optional currency field used to specify which currency is debited from the Payment Method. Since many Payment Methods support only one currency, this field is optional.
- from.payment_methodstringRequired
  ID of the Payment Method using which IBT will be made.

toobjectRequired
Object containing details about where the funds will land.
- to.currencystringRequired
  The currency in which funds will land in.
- to.financial_accountstringRequired
  The FinancialAccount that funds will land in.

descriptionstring
An optional, freeform description field intended to store metadata.

Returns

Response attributes

idstring
Unique identifier for the InboundTransfer.

objectstring, value is "v2.money_management.inbound_transfer"
String representing the object’s type. Objects of the same type share the same value of the object field.

amountobject
The amount in specified currency that will land in the FinancialAccount balance.
- amount.currencystring
  A lowercase alpha3 currency code like “usd”.
- amount.valueinteger
  In minor units like 123 for 1.23 USD.

createdtimestamp
Creation time of the InboundTransfer. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.

descriptionstring
A freeform text field provided by user, containing metadata.

fromobject
A nested object containing information about the origin of the InboundTransfer.
- from.debitedobject
  The amount in specified currency that was debited from the Payment Method.
  from.debited.currencystring
  A lowercase alpha3 currency code like “usd”.
  from.debited.valueinteger
  In minor units like 123 for 1.23 USD.
- from.payment_methodobject
  The Payment Method object used to create the InboundTransfer.
  from.payment_method.typestring
  The type of object this destination represents. For a us bank account, we expect us_bank_account.
  from.payment_method.us_bank_accountnullable string
  The destination US bank account identifier. eg “usba_***”.

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

receipt_urlnullable string
A hosted transaction receipt URL that is provided when money movement is considered regulated under Stripe’s money transmission licenses.

toobject
A nested object containing information about the destination of the InboundTransfer.
- to.creditedobject
  The amount by which the FinancialAccount balance is credited.
  to.credited.currencystring
  A lowercase alpha3 currency code like “usd”.
  to.credited.valueinteger
  In minor units like 123 for 1.23 USD.
- to.financial_accountstring
  The FinancialAccount that funds will land in.

transfer_historyarray of objects

A list of history objects, representing changes in the state of the InboundTransfer.

transfer_history.idstring
A unique ID for the HistoryEntry.

transfer_history.bank_debit_failednullable object

The history entry for a failed InboundTransfer.

transfer_history.bank_debit_failed.failure_reasonenum

The return reason for the failed InboundTransfer.

Possible enum values

bank_account_closed

The Failure Reason when the user’s external Bank Account is closed.

bank_account_not_found

The Failure Reason when the user’s Bank Account is not found.

bank_debit_could_not_be_processed

The Failure Reason when the debit cannot be processed for any other reason.

bank_debit_not_authorized

The Failure Reason when the user hasn’t authorized the debit with their bank.

insufficient_funds

The Failure Reason when there aren’t sufficient funds in the user’s bank account.

transfer_history.bank_debit_processingnullable object
The history entry for a processing InboundTransfer.

transfer_history.bank_debit_queuednullable object
The history entry for a queued InboundTransfer.

transfer_history.bank_debit_returnednullable object

The history entry for a returned InboundTransfer.

transfer_history.bank_debit_returned.return_reasonenum

The return reason for the returned InboundTransfer.

Possible enum values

bank_account_closed

The Failure Reason when the user’s external Bank Account is closed.

bank_account_not_found

The Failure Reason when the user’s Bank Account is not found.

bank_debit_could_not_be_processed

The Failure Reason when the debit cannot be processed for any other reason.

bank_debit_not_authorized

The Failure Reason when the user hasn’t authorized the debit with their bank.

insufficient_funds

The Failure Reason when there aren’t sufficient funds in the user’s bank account.

transfer_history.bank_debit_succeedednullable object
The history entry for a succeeded InboundTransfer.

transfer_history.createdtimestamp
Creation time of the HistoryEntry in RFC 3339 format and UTC.

transfer_history.effective_attimestamp
Effective at time of the HistoryEntry in RFC 3339 format and UTC.

transfer_history.levelenum
The Level of the HistoryEntry.
Possible enum values
canonical
History events that are canonical.
debug
History events that are meant to provide additional information for debugging.

transfer_history.typeenum

The type of the HistoryEntry.

Possible enum values

bank_debit_failed

History Entry type for an InboundTransfer that has failed.

bank_debit_processing

History Entry type for an InboundTransfer that is processing.

bank_debit_queued

History Entry type for a queued InboundTransfer.

bank_debit_returned

History Entry type for an InboundTransfer that has returned, after initially being successful.

bank_debit_succeeded

History Entry type for an InboundTransfer that has succeeded.

Error Codes

400inbound_transfer_from_closed_financial_account_unsupported

Returned if an InboundTransfer is made to a closed FinancialAccount.

400inbound_transfer_from_payment_method_type_unsupported

Returned when a valid, but unsupported PaymentMethod for InboundTransfers is provided.

400inbound_transfer_from_payment_method_unusable

Returned if the PM used for the inbound transfer is based on a tokenized account number that is no longer transactable.

400inbound_transfer_from_payment_method_unverified

Returned when a PaymentMethod that has not been verified, is provided.

400inbound_transfer_not_allowed

Returned if an InboundTransfer is not allowed for risk, legal, regulatory or other unforeseen reasons.

400unsupported_operation_with_managed_financial_account

Creation of an object is not allowed with a managed account.

404inbound_transfer_from_payment_method_not_found

Returned when a PaymentMethod cannot be found.

404inbound_transfer_to_financial_account_not_found

Returned when a FinancialAccount cannot be found.

404not_found

The resource wasn’t found.

409idempotency_error

An idempotent retry occurred with different request parameters.

POST /v2/money_management/inbound_transfers

curl -X POST https://api.stripe.com/v2/money_management/inbound_transfers \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-11-17.preview" \
  --json '{
    "description": "April Payouts",
    "from": {
        "payment_method": "usba_test_61P22mHGGhTkqVEx416Nr2cJ8cSQabKn4q38nZ59E7ea"
    },
    "to": {
        "financial_account": "fa_test_65Nyg0pdsXOSN32kkjg16Nr2cJ8cSQabKn4q38nZ59E50y",
        "currency": "usd"
    },
    "amount": {
        "value": 101,
        "currency": "usd"
    }
  }'

Response

{
  "id": "ibt_test_61Q58XwKMHh5ha3MI16Nr2cJ8cSQabKn4q38nZ59E6yO",
  "object": "v2.money_management.inbound_transfer",
  "amount": {
    "value": 101,
    "currency": "usd"
  },
  "created": "2024-03-18T18:07:12.619131Z",
  "description": "April Payouts",
  "from": {
    "debited": {
      "value": 101,
      "currency": "usd"
    },
    "payment_method": {
      "type": "payment_methods.us_bank_account",
      "us_bank_account": "usba_test_61P22mHGGhTkqVEx416Nr2cJ8cSQabKn4q38nZ59E7ea"
    }
  },
  "receipt_url": "https://payments.stripe.com/transaction_receipt/CCMQARojCiF3a3NwX3Rlc3RfNk5yMmNKOGNTUWFiS240cTM4blo1OUUohIbirwYyBvlQ2PtS3zpGlI2ZkpO8-dpYhb3KfWs1FlYI9eX2I94gJoeJHXOR0QwwesVCRnQwRgsUQqGFloqKV7McODKkoVKAMiuB5lD9htcDuxRtDA",
  "to": {
    "credited": {
      "value": 101,
      "currency": "usd"
    },
    "financial_account": "fa_test_65Nyg0pdsXOSN32kkjg16Nr2cJ8cSQabKn4q38nZ59E50y"
  },
  "transfer_history": [
    {
      "id": "ibthe_test_61Q58Xw5weaazmsWj16Nr2cJ8cSQabKn4q38nZ59E52W",
      "bank_debit_queued": {},
      "created": "2024-03-18T18:07:12.617Z",
      "effective_at": "2024-03-18T18:07:12.617Z",
      "level": "canonical",
      "type": "bank_debit_queued"
    },
    {
      "id": "ibthe_test_61Q58Y2iAWn3U9kNW16Nr2cJ8cSQabKn4q38nZ59EXzc",
      "bank_debit_processing": {},
      "created": "2024-03-18T18:07:18.403Z",
      "effective_at": "2024-03-18T18:07:18.403Z",
      "level": "canonical",
      "type": "bank_debit_processing"
    },
    {
      "id": "ibthe_test_61Q58Y7wNh292msCP16Nr2cJ8cSQabKn4q38nZ59EPz6",
      "bank_debit_succeeded": {},
      "created": "2024-03-18T18:07:23.103Z",
      "effective_at": "2024-03-18T18:07:23.103Z",
      "level": "canonical",
      "type": "bank_debit_succeeded"
    }
  ],
  "livemode": true
}

Need help? Contact Support.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc

Create an InboundTransfer object v2

Parameters

amountobjectRequired

amount.currencystringRequired

amount.valueintegerRequired

fromobjectRequired

from.currencystring

from.payment_methodstringRequired

toobjectRequired

to.currencystringRequired

to.financial_accountstringRequired

descriptionstring

Returns

Response attributes

idstring

objectstring, value is "v2.money_management.inbound_transfer"

amountobject

amount.currencystring

amount.valueinteger

createdtimestamp

descriptionstring

fromobject

from.debitedobject

from.debited.currencystring

from.debited.valueinteger

from.payment_methodobject

from.payment_method.typestring

from.payment_method.us_bank_accountnullable string

livemodeboolean

receipt_urlnullable string

toobject

to.creditedobject

to.credited.currencystring

to.credited.valueinteger

to.financial_accountstring

transfer_historyarray of objects

transfer_history.idstring

transfer_history.bank_debit_failednullable object

transfer_history.bank_debit_failed.failure_reasonenum

transfer_history.bank_debit_processingnullable object

transfer_history.bank_debit_queuednullable object

transfer_history.bank_debit_returnednullable object

transfer_history.bank_debit_returned.return_reasonenum

transfer_history.bank_debit_succeedednullable object

transfer_history.createdtimestamp

transfer_history.effective_attimestamp

transfer_history.levelenum

transfer_history.typeenum