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
}

Credit a FinancialAddress object v2Test helper

Simulate crediting a FinancialAddress in a Sandbox environment. This can be used to add virtual funds and increase your balance for testing.

Learn more about calling API v2 endpoints.

Parameters

amountobjectRequired
Object containing the amount value and currency to credit.

idstringRequired
The ID of the FinancialAddress to credit.

networkenumRequired
The network to use in simulating the funds flow. This will be the reflected in the resulting ReceivedCredit.
Possible enum values
ach
US - The Automated Clearing House (ACH) money movement.
fps
UK - Faster Payments System (FPS) money movement.
rtp
US - Real-Time Payments (RTP) money movement.
wire
A wire transfer money movement.

statement_descriptorstring
String explaining funds flow. Use this field to populate the statement descriptor of the ReceivedCredit created as an eventual result of this simulation.

Returns

Response attributes

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

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

statusstring
The status of the request, signifying whether a simulated credit was initiated.

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/test_helpers/financial_addresses/:id/credit

curl -X POST https://api.stripe.com/v2/test_helpers/financial_addresses/finaddr_test_61O6nHqDsFuMtECYR16O0lef0dSQgZ0EhGyZsQCXQMls/credit \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-09-30.preview" \
  --json '{
    "amount": {
        "value": 2500,
        "currency": "usd"
    },
    "network": "ach"
  }'

Response

{
  "object": "financial_address_credit_simulation",
  "status": "accepted",
  "livemode": true
}

Generates microdeposits for a FinancialAddress v2Test helper

Generates microdeposits for a FinancialAddress in a Sandbox environment.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The id of the financial address to generate microdeposits for.

Returns

Response attributes

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

amountsarray of objects
The amounts of the microdeposits that were generated.

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

statusenum
The status of the request.
Possible enum values
accepted
The microdeposits were successfully generated.

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/test_helpers/financial_addresses/:id/generate_microdeposits

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

Response

{
  "object": "financial_address_generated_microdeposits",
  "amounts": [
    {
      "value": 24,
      "currency": "usd"
    },
    {
      "value": 46,
      "currency": "usd"
    }
  ],
  "status": "accepted",
  "livemode": true
}

FinancialAddress event types v2

This is a list of all public thin events we currently send for updates to FinancialAddress, which are continually evolving and expanding. The payload of thin events is unversioned. During processing, you must fetch the versioned event from the API or fetch the resource’s current state.

Event types

Type

Filter events by type

Type

v2.money_management.financial_address.activated

Occurs when a FinancialAddress is activated and is ready to receive funds.

v2.money_management.financial_address.failed

Occurs when a FinancialAddress fails to activate and can not receive funds.

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

Credit a FinancialAddress object v2Test helper

Parameters

amountobjectRequired

idstringRequired

networkenumRequired

statement_descriptorstring

Returns

Response attributes

objectstring, value is "financial_address_credit_simulation"

livemodeboolean

statusstring

Generates microdeposits for a FinancialAddress v2Test helper

Parameters

idstringRequired

Returns

Response attributes

objectstring, value is "financial_address_generated_microdeposits"

amountsarray of objects

livemodeboolean

statusenum

FinancialAddress event types v2

Event types