Financial Addresses v2

Learn more about calling API v2 endpoints.

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

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.

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

Learn more about calling API v2 endpoints.

Create a new FinancialAddress for a FinancialAccount.

Parameters

currencyenumRequired
The currency the FinancialAddress should support. Currently, only the usd and gbp values are supported.

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

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.

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.

409idempotency_error

An idempotent retry occurred with different request parameters.

POST /v2/money_management/financial_addresses

Server-side language

curl -X POST https://api.stripe.com/v2/money_management/financial_addresses \
  -H "Authorization: Bearer {{YOUR_API_KEY}}{{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2025-04-30.preview" \
  --json '{
    "financial_account": "fa_654f0m3x1JLdhVIIIT1A16O0lef0dSQgZ0EhGyZsQCXQ28m",
    "currency": "usd"
  }'

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"
}

Retrieve a FinancialAddress object v2

Learn more about calling API v2 endpoints.

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

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.

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

Server-side language

curl -G https://api.stripe.com/v2/money_management/financial_addresses/finaddr_61O6nHqDsFuMtECYR16O0lef0dSQgZ0EhGyZsQCXQMls \
  -H "Authorization: Bearer {{YOUR_API_KEY}}{{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2025-04-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"
}

List all FinancialAddress objects v2

Learn more about calling API v2 endpoints.

List all FinancialAddresses for a FinancialAccount.

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

Server-side language

curl https://api.stripe.com/v2/money_management/financial_addresses \
  -H "Authorization: Bearer {{YOUR_API_KEY}}{{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2025-04-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"
    },
    {
      "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"
    }
  ],
  "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

statusenum

Create a FinancialAddress object v2

Parameters

currencyenumRequired

financial_accountstringRequired

Returns

Response attributes

idstring

objectstring, value is "v2.money_management.financial_address"

createdtimestamp

credentialsnullable object

currencyenum

financial_accountstring

livemodeboolean

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

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