Financial Addresses v2

A FinancialAddress contains information needed to transfer money to a Financial Account. A Financial Account can have more than one Financial Address.

Learn more about calling API v2 endpoints.

Endpoints

POST/v2/money_management/financial_addresses

GET/v2/money_management/financial_addresses/:id

GET/v2/money_management/financial_addresses

POST/v2/test_helpers/financial_addresses/:id/credit

POST/v2/test_helpers/financial_addresses/:id/generate_microdeposits

The FinancialAddress object

Attributes

idstring
The ID of a FinancialAddress.

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

createdtimestamp
The creation timestamp of the FinancialAddress.

credentialsnullable object
Object indicates the type of credentials that have been allocated and attached to the FinancialAddress. It contains all necessary banking details with which to perform money movements with the FinancialAddress. This field is only available for FinancialAddresses with an active status.

currencyenum
The currency the FinancialAddress supports.

financial_accountstring
A ID of the FinancialAccount this FinancialAddress corresponds to.

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

settlement_currencynullable enum
The currency the FinancialAddress settles into the FinancialAccount.

statusenum
An enum representing the status of the FinancialAddress. This indicates whether or not the FinancialAddress can be used for any money movement flows.
Possible enum values
active
The Financial Address is active.
archived
The Financial Address is archived, it cannot be used anymore.
failed
The Financial Address creation failed.
pending
The Financial Address is being created.

The FinancialAddress object

{
  "id": "finaddr_61O6nHqDsFuMtECYR16O0lef0dSQgZ0EhGyZsQCXQMls",
  "object": "v2.money_management.financial_address",
  "credentials": {
    "type": "us_bank_account",
    "us_bank_account": {
      "account_number": "123456890",
      "routing_number": "110000000",
      "swift_code": "TSTEZ122",
      "bank_name": "STRIPE TEST BANK",
      "last4": "6890"
    }
  },
  "status": "active",
  "financial_account": "fa_6504m3x1JLdhVIIIT1A16O0lef0dSQgZ0EhGyZsQCXQ28m",
  "created": "2023-03-30T17:32:06.665Z",
  "currency": "usd"
}

Create a FinancialAddress object v2

Create a new FinancialAddress for a FinancialAccount.

Learn more about calling API v2 endpoints.

Parameters

financial_accountstringRequired
The ID of the FinancialAccount the new FinancialAddress should be associated with.

typeenumRequired

The type of FinancialAddress details to provision.

Possible enum values

gb_bank_account

A UK Bank Account credential. This indicates that the associated credentials object contains unique banking details pertinent to a UK bank account.

sepa_bank_account

A SEPA Bank account credential. This indicates that the associated credentials object contains unique banking details pertinent to a SEPA bank account.

us_bank_account

A US Bank Account credential. This indicates that the associated credentials object contains unique banking details pertinent to a US bank account.

Returns

Response attributes

idstring
The ID of a FinancialAddress.

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

createdtimestamp
The creation timestamp of the FinancialAddress.

credentialsnullable object
Object indicates the type of credentials that have been allocated and attached to the FinancialAddress. It contains all necessary banking details with which to perform money movements with the FinancialAddress. This field is only available for FinancialAddresses with an active status.

currencyenum
The currency the FinancialAddress supports.

financial_accountstring
A ID of the FinancialAccount this FinancialAddress corresponds to.

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

settlement_currencynullable enum
The currency the FinancialAddress settles into the FinancialAccount.

statusenum
An enum representing the status of the FinancialAddress. This indicates whether or not the FinancialAddress can be used for any money movement flows.
Possible enum values
active
The Financial Address is active.
archived
The Financial Address is archived, it cannot be used anymore.
failed
The Financial Address creation failed.
pending
The Financial Address is being created.

Error Codes

400storer_capability_missing

The required storer capabilities are missing.

400storer_capability_not_active

The required storer capabilities are not active.

400unsupported_currency

The currency is not supported for Financial Accounts.

404not_found

The resource wasn’t found.

409idempotency_error

An idempotent retry occurred with different request parameters.

POST /v2/money_management/financial_addresses

cURL

curl -X POST https://api.stripe.com/v2/money_management/financial_addresses \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-09-30.preview" \
  --json '{
    "financial_account": "fa_654f0m3x1JLdhVIIIT1A16O0lef0dSQgZ0EhGyZsQCXQ28m",
    "type": "us_bank_account"
  }'

Response

{
  "id": "finaddr_61O5ng8AAMZt30I2YH16O0lef0dSQgZ0EhGyZsQCXQHG4",
  "object": "v2.money_management.financial_address",
  "credentials": null,
  "status": "pending",
  "financial_account": "fa_654f0m3x1JLdhVIIIT1A16O0lef0dSQgZ0EhGyZsQCXQ28m",
  "created": "2023-03-30T17:22:06.188Z",
  "currency": "usd",
  "livemode": true
}

Retrieve a FinancialAddress object v2

Retrieve a FinancialAddress. By default, the FinancialAddress will be returned in its unexpanded state, revealing only the last 4 digits of the account number.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the FinancialAddress to retrieve.

includearray of enums

Open Enum. A list of fields to reveal in the FinancialAddresses returned.

Possible enum values

credentials.gb_bank_account.account_number

The full account number of the FinancialAddress for a UK bank account.

credentials.us_bank_account.account_number

The full account number of the FinancialAddress for a US bank account.

Returns

Response attributes

idstring
The ID of a FinancialAddress.

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

createdtimestamp
The creation timestamp of the FinancialAddress.

credentialsnullable object
Object indicates the type of credentials that have been allocated and attached to the FinancialAddress. It contains all necessary banking details with which to perform money movements with the FinancialAddress. This field is only available for FinancialAddresses with an active status.

currencyenum
The currency the FinancialAddress supports.

financial_accountstring
A ID of the FinancialAccount this FinancialAddress corresponds to.

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

settlement_currencynullable enum
The currency the FinancialAddress settles into the FinancialAccount.

statusenum
An enum representing the status of the FinancialAddress. This indicates whether or not the FinancialAddress can be used for any money movement flows.
Possible enum values
active
The Financial Address is active.
archived
The Financial Address is archived, it cannot be used anymore.
failed
The Financial Address creation failed.
pending
The Financial Address is being created.

Error Codes

404not_found

The resource wasn’t found.

GET /v2/money_management/financial_addresses/:id

curl -G https://api.stripe.com/v2/money_management/financial_addresses/finaddr_61O6nHqDsFuMtECYR16O0lef0dSQgZ0EhGyZsQCXQMls \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-09-30.preview" \
  -d include="credentials.us_bank_account.account_number"

Response

{
  "id": "finaddr_61O6nHqDsFuMtECYR16O0lef0dSQgZ0EhGyZsQCXQMls",
  "object": "v2.money_management.financial_address",
  "credentials": {
    "type": "us_bank_account",
    "us_bank_account": {
      "account_number": "123456890",
      "routing_number": "110000000",
      "swift_code": "TSTEZ122",
      "bank_name": "STRIPE TEST BANK",
      "last4": "6890"
    }
  },
  "status": "active",
  "financial_account": "fa_6504m3x1JLdhVIIIT1A16O0lef0dSQgZ0EhGyZsQCXQ28m",
  "created": "2023-03-30T17:32:06.665Z",
  "currency": "usd",
  "livemode": true
}

List all FinancialAddress objects v2

List all FinancialAddresses for a FinancialAccount.

Learn more about calling API v2 endpoints.

Parameters

financial_accountstring
The ID of the FinancialAccount for which FinancialAddresses are to be returned.

includearray of enums

Open Enum. A list of fields to reveal in the FinancialAddresses returned.

Possible enum values

credentials.gb_bank_account.account_number

The full account number of the FinancialAddress for a UK bank account.

credentials.us_bank_account.account_number

The full account number of the FinancialAddress for a US bank account.

limitinteger
The page limit.

pagestring
The page token.

Returns

Response attributes

dataarray of objects
A list of FinancialAddresses.

next_page_urlnullable string
The next page url.

previous_page_urlnullable string
The previous page url.

GET /v2/money_management/financial_addresses

curl https://api.stripe.com/v2/money_management/financial_addresses \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-09-30.preview"

Response

{
  "data": [
    {
      "id": "finaddr_61O3m0n8AAMZt30I2YH16O0lef0dSQgZ0EhGyZsQCXQHG4",
      "object": "v2.money_management.financial_address",
      "credentials": {
        "type": "us_bank_account",
        "us_bank_account": {
          "account_number": null,
          "routing_number": "110000000",
          "swift_code": "TSTEZ122",
          "bank_name": "STRIPE TEST BANK",
          "last4": "6890"
        }
      },
      "status": "active",
      "financial_account": "fa_6504m3x1JLdhVIIIT1A16O0lef0dSQgZ0EhGyZsQCXQ28m",
      "created": "2023-03-30T17:22:06.188Z",
      "currency": "usd",
      "livemode": true
    },
    {
      "id": "finaddr_61O6nHqDsFuMtECYR16O0lef0dSQgZ0EhGyZsQCXQMls",
      "object": "v2.money_management.financial_address",
      "credentials": {
        "type": "us_bank_account",
        "us_bank_account": {
          "account_number": null,
          "routing_number": "110000000",
          "swift_code": "TSTEZ122",
          "bank_name": "STRIPE TEST BANK",
          "last4": "6891"
        }
      },
      "status": "active",
      "financial_account": "fa_6504m3x1JLdhVIIIT1A16O0lef0dSQgZ0EhGyZsQCXQ28m",
      "created": "2023-03-30T17:32:06.665Z",
      "currency": "usd",
      "livemode": true
    }
  ],
  "next_page_url": null,
  "previous_page_url": null
}

Financial Addresses v2

The FinancialAddress object

Attributes

idstring

objectstring, value is "v2.money_management.financial_address"

createdtimestamp

credentialsnullable object

currencyenum

financial_accountstring

livemodeboolean

settlement_currencynullable enum

statusenum

Create a FinancialAddress object v2

Parameters

financial_accountstringRequired

typeenumRequired

Returns

Response attributes

idstring

objectstring, value is "v2.money_management.financial_address"

createdtimestamp

credentialsnullable object

currencyenum

financial_accountstring

livemodeboolean

settlement_currencynullable enum

statusenum

Retrieve a FinancialAddress object v2

Parameters

idstringRequired

includearray of enums

Returns

Response attributes

idstring

objectstring, value is "v2.money_management.financial_address"

createdtimestamp

credentialsnullable object

currencyenum

financial_accountstring

livemodeboolean

settlement_currencynullable enum

statusenum

List all FinancialAddress objects v2

Parameters

financial_accountstring

includearray of enums

limitinteger

pagestring

Returns

Response attributes

dataarray of objects

next_page_urlnullable string

previous_page_urlnullable string