Create a UsBankAccount object v2

Create a USBankAccount object.

Learn more about calling API v2 endpoints.

Parameters

  • account_numberstringRequired

    The account number of the bank account.

  • bank_account_typeenum

    The type of the bank account (checking or savings).

    Possible enum values
    checking

    Checkings account.

    savings

    Savings account.

  • fedwire_routing_numberstring

    The fedwire routing number of the bank account. Note that certain banks have the same ACH and wire routing number.

  • routing_numberstring

    The ACH routing number of the bank account. Note that certain banks have the same ACH and wire routing number.

Returns

Response attributes

  • idstring

    The ID of the USBankAccount object.

  • objectstring, value is "v2.core.vault.us_bank_account"

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

  • archivedboolean

    Whether this USBankAccount object was archived.

  • bank_account_typeenum

    The type of bank account (checking or savings).

    Possible enum values
    checking

    Checkings account.

    savings

    Savings account.

  • bank_namestring

    The name of the bank this bank account belongs to. This field is populated automatically by Stripe based on the routing number.

  • createdtimestamp

    Creation time of the object.

  • fedwire_routing_numbernullable string

    The fedwire routing number of the bank account.

  • last4string

    The last 4 digits of the account number.

  • livemodeboolean

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

  • routing_numbernullable string

    The ACH routing number of the bank account.

Error Codes
400blocked_us_bank_account

Returned in cases where the bank account cannot be used due to suspicious activity.

400invalid_us_bank_account

Returned in cases where the bank account provided is not valid (wrong format of account number or a routing number that does not correspond to a banking institution).

400limit_us_bank_account

Returned when the number of USBankAccount objects on a given V2 Account has exceeded the limit of 10. USBankAccount objects may be deactivated with /deactivate, at which point they will not count against the limit. If you are not passing a V2 Account ID in the Stripe-Context header you may receive this error since you are creating all your USBankAccount objects in your own workspace.

400unsupported_us_bank

Returned in cases where Stripe is unable to support this bank at this time.

409idempotency_error

An idempotent retry occurred with different request parameters.

POST /v2/core/vault/us_bank_accounts
curl -X POST https://api.stripe.com/v2/core/vault/us_bank_accounts \
-H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
-H "Stripe-Version: 2025-07-30.preview" \
-H "Stripe-Context: {{CONTEXT}}" \
--json '{
"routing_number": "110000000",
"account_number": "000123456789",
"bank_account_type": "checking"
}'
Response
{
"id": "usba_test_61OHSEF60mEpRiXpR16NqdMu76SQRZLd31xuji87MN5M",
"object": "v2.core.vault.us_bank_account",
"bank_account_type": "checking",
"bank_name": "Test Bank",
"created": "2023-05-15T16:29:15.738Z",
"archived": false,
"last4": "6789",
"routing_number": "110000000",
"livemode": true
}

Update a UsBankAccount object v2

Update a USBankAccount object. This is limited to supplying a previously empty routing_number field.

Learn more about calling API v2 endpoints.

Parameters

  • idstringRequired

    The ID of the USBankAccount object.

  • fedwire_routing_numberstring

    The bank account’s fedwire routing number can be provided for update it was were empty previously.

  • routing_numberstring

    The bank account’s ACH routing number can be provided for update if it was empty previously.

Returns

Response attributes

  • idstring

    The ID of the USBankAccount object.

  • objectstring, value is "v2.core.vault.us_bank_account"

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

  • archivedboolean

    Whether this USBankAccount object was archived.

  • bank_account_typeenum

    The type of bank account (checking or savings).

    Possible enum values
    checking

    Checkings account.

    savings

    Savings account.

  • bank_namestring

    The name of the bank this bank account belongs to. This field is populated automatically by Stripe based on the routing number.

  • createdtimestamp

    Creation time of the object.

  • fedwire_routing_numbernullable string

    The fedwire routing number of the bank account.

  • last4string

    The last 4 digits of the account number.

  • livemodeboolean

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

  • routing_numbernullable string

    The ACH routing number of the bank account.

Error Codes
400archived_us_bank_account

Returned in cases where the bank account cannot be updated due to being archived.

400blocked_us_bank_account

Returned in cases where the bank account cannot be used due to suspicious activity.

400invalid_us_bank_account

Returned in cases where the bank account provided is not valid (wrong format of account number or a routing number that does not correspond to a banking institution).

400limit_us_bank_account

Returned when the number of USBankAccount objects on a given V2 Account has exceeded the limit of 10. USBankAccount objects may be deactivated with /deactivate, at which point they will not count against the limit. If you are not passing a V2 Account ID in the Stripe-Context header you may receive this error since you are creating all your USBankAccount objects in your own workspace.

400unsupported_us_bank

Returned in cases where Stripe is unable to support this bank at this time.

400us_bank_account_field_already_exists

Returned in cases where the bank account cannot be updated due to requesting to update a field that already exists.

404not_found

The resource wasn’t found.

409idempotency_error

An idempotent retry occurred with different request parameters.

POST /v2/core/vault/us_bank_accounts/:id
curl -X POST https://api.stripe.com/v2/core/vault/us_bank_accounts/usba_test_61OHSEF60mEpRiXpR16NqdMu76SQRZLd31xuji87MN5M \
-H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
-H "Stripe-Version: 2025-07-30.preview" \
-H "Stripe-Context: {{CONTEXT}}" \
--json {"fedwire_routing_number":"110000000"}
Response
{
"id": "usba_test_61OHSEF60mEpRiXpR16NqdMu76SQRZLd31xuji87MN5M",
"object": "v2.core.vault.us_bank_account",
"bank_account_type": "checking",
"bank_name": "Test Bank",
"created": "2023-05-15T16:29:15.738Z",
"archived": false,
"last4": "6789",
"routing_number": "110000000",
"livemode": true
}

Retrieve a UsBankAccount object v2

Retrieve a USBankAccount object.

Learn more about calling API v2 endpoints.

Parameters

  • idstringRequired

    The ID of the USBankAccount object.

Returns

Response attributes

  • idstring

    The ID of the USBankAccount object.

  • objectstring, value is "v2.core.vault.us_bank_account"

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

  • archivedboolean

    Whether this USBankAccount object was archived.

  • bank_account_typeenum

    The type of bank account (checking or savings).

    Possible enum values
    checking

    Checkings account.

    savings

    Savings account.

  • bank_namestring

    The name of the bank this bank account belongs to. This field is populated automatically by Stripe based on the routing number.

  • createdtimestamp

    Creation time of the object.

  • fedwire_routing_numbernullable string

    The fedwire routing number of the bank account.

  • last4string

    The last 4 digits of the account number.

  • livemodeboolean

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

  • routing_numbernullable string

    The ACH routing number of the bank account.

Error Codes
404not_found

The resource wasn’t found.

GET /v2/core/vault/us_bank_accounts/:id
curl https://api.stripe.com/v2/core/vault/us_bank_accounts/usba_test_61OHSEF60mEpRiXpR16NqdMu76SQRZLd31xuji87MN5M \
-H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
-H "Stripe-Version: 2025-07-30.preview" \
-H "Stripe-Context: {{CONTEXT}}"
Response
{
"id": "usba_test_61OHSEF60mEpRiXpR16NqdMu76SQRZLd31xuji87MN5M",
"object": "v2.core.vault.us_bank_account",
"bank_account_type": "checking",
"bank_name": "Test Bank",
"created": "2023-05-15T16:29:15.738Z",
"archived": false,
"last4": "6789",
"routing_number": "110000000",
"livemode": true
}

Archive a UsBankAccount object v2

Archive a USBankAccount object. USBankAccount objects will not be automatically archived by Stripe. Archived USBankAccount objects cannot be used as outbound destinations and will not appear in the outbound destination list.

Learn more about calling API v2 endpoints.

Parameters

  • idstringRequired

    The ID of the USBankAccount object.

Returns

Response attributes

  • idstring

    The ID of the USBankAccount object.

  • objectstring, value is "v2.core.vault.us_bank_account"

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

  • archivedboolean

    Whether this USBankAccount object was archived.

  • bank_account_typeenum

    The type of bank account (checking or savings).

    Possible enum values
    checking

    Checkings account.

    savings

    Savings account.

  • bank_namestring

    The name of the bank this bank account belongs to. This field is populated automatically by Stripe based on the routing number.

  • createdtimestamp

    Creation time of the object.

  • fedwire_routing_numbernullable string

    The fedwire routing number of the bank account.

  • last4string

    The last 4 digits of the account number.

  • livemodeboolean

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

  • routing_numbernullable string

    The ACH routing number of the bank account.

Error Codes
400us_bank_account_cannot_be_archived

Returned when the US Bank Account in question is controlled by the Stripe Dashboard, and cannot be archived.

404not_found

The resource wasn’t found.

POST /v2/core/vault/us_bank_accounts/:id/archive
curl -X POST https://api.stripe.com/v2/core/vault/us_bank_accounts/usba_test_61OHSEF60mEpRiXpR16NqdMu76SQRZLd31xuji87MN5M/archive \
-H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
-H "Stripe-Version: 2025-07-30.preview"
Response
{
"id": "usba_test_61OHSEF60mEpRiXpR16NqdMu76SQRZLd31xuji87MN5M",
"object": "v2.core.vault.us_bank_account",
"bank_account_type": "checking",
"bank_name": "Test Bank",
"created": "2023-05-15T16:29:15.738Z",
"archived": true,
"last4": "6789",
"routing_number": "110000000",
"livemode": true
}