> ## Documentation Index > Fetch the complete documentation index at: https://docs.montereyfinancial.com/llms.txt > Use this file to discover all available pages before exploring further. # Add a bank account > Adds an ACH bank account for a borrower on an account and returns the stored payment method. The routing and account numbers are verified with the bank network, then stored encrypted; responses only ever expose the last four digits. **Borrower.** Omit `party_id` to use the account's primary borrower. When given, `party_id` must be an active borrower on the account. **Verification.** On success `validation_status` is `validated`. If the verification service is temporarily unavailable, the bank account is still saved and returned with `validation_status: pending_giact`: it is stored but verification is pending. An account the verification service declines is not saved. **Default.** `set_default: true` makes it the borrower's default payment method; a borrower's first payment method becomes the default regardless. **Errors** (`detail.error_code`): - **403** `insufficient_scope`: the token lacks `payment_methods:write`. - **404** `account_not_found`: the account isn't reachable by this token. - **409** `duplicate_bank_account`: this borrower already has this bank account. `detail.existing_payment_method_id` names it when visible to this token. - **422** `invalid_routing_number`: the routing number fails the ABA checksum. - **422** `bank_account_declined`: verification declined the bank account; nothing was saved. Do not retry with the same numbers. - **422** `party_not_on_account`: `party_id` is not an active borrower on the account. - **422** `account_has_no_primary_borrower`: `party_id` was omitted and the account has no primary borrower. - **422** `invalid_bank_account`: the bank details could not be accepted. - **503** `bank_capture_unavailable`: bank-account capture is not enabled. Request bodies that fail schema validation return the standard 422 `detail` list (submitted values are never echoed). ## OpenAPI ````yaml /api-reference/external_api.openapi.json post /v1/payment-methods/bank openapi: 3.1.0 info: title: Monterey Client API description: >- Org-scoped, token-authenticated account, borrower, and payment endpoints for Monterey Financial clients. version: 1.0.0 servers: - url: https://eapi.montereyfinancial.com description: Production security: - BearerToken: [] tags: - name: Authentication description: Exchange API keys for access tokens. - name: Organizations description: Organizations visible to the API key. - name: Persons description: Borrowers visible through in-scope accounts. - name: Accounts description: Servicing accounts and identifier lookups. - name: Transactions description: Account money-movement history. - name: Payment Methods description: Stored payment instruments. - name: Autopay description: Recurring payment schedules. paths: /v1/payment-methods/bank: post: tags: - Payment Methods summary: Add a bank account description: >- Adds an ACH bank account for a borrower on an account and returns the stored payment method. The routing and account numbers are verified with the bank network, then stored encrypted; responses only ever expose the last four digits. **Borrower.** Omit `party_id` to use the account's primary borrower. When given, `party_id` must be an active borrower on the account. **Verification.** On success `validation_status` is `validated`. If the verification service is temporarily unavailable, the bank account is still saved and returned with `validation_status: pending_giact`: it is stored but verification is pending. An account the verification service declines is not saved. **Default.** `set_default: true` makes it the borrower's default payment method; a borrower's first payment method becomes the default regardless. **Errors** (`detail.error_code`): - **403** `insufficient_scope`: the token lacks `payment_methods:write`. - **404** `account_not_found`: the account isn't reachable by this token. - **409** `duplicate_bank_account`: this borrower already has this bank account. `detail.existing_payment_method_id` names it when visible to this token. - **422** `invalid_routing_number`: the routing number fails the ABA checksum. - **422** `bank_account_declined`: verification declined the bank account; nothing was saved. Do not retry with the same numbers. - **422** `party_not_on_account`: `party_id` is not an active borrower on the account. - **422** `account_has_no_primary_borrower`: `party_id` was omitted and the account has no primary borrower. - **422** `invalid_bank_account`: the bank details could not be accepted. - **503** `bank_capture_unavailable`: bank-account capture is not enabled. Request bodies that fail schema validation return the standard 422 `detail` list (submitted values are never echoed). operationId: create_bank_payment_method_v1_payment_methods_bank_post requestBody: content: application/json: schema: $ref: '#/components/schemas/BankPaymentMethodCreate' required: true responses: '201': description: >- Bank account saved. `validation_status` is `validated`, or `pending_giact` when it is saved but verification is pending. content: application/json: schema: $ref: '#/components/schemas/PaymentMethodRow' '401': description: Missing or invalid access token. '403': description: Token lacks `payment_methods:write` (`insufficient_scope`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '`account_not_found`: the account isn''t reachable by this token.' '409': description: >- `duplicate_bank_account`: the borrower already has this bank account; `existing_payment_method_id` names it when visible. '422': description: >- `invalid_routing_number`, `bank_account_declined`, `party_not_on_account`, `account_has_no_primary_borrower`, `invalid_bank_account`, or a request-body validation error. '429': description: Rate limit exceeded. '503': description: '`bank_capture_unavailable`: bank-account capture is not enabled.' security: - BearerToken: [] components: schemas: BankPaymentMethodCreate: properties: account_id: type: string minLength: 1 title: Account Id description: >- String, required. ID of the account the borrower is on. Must be reachable by the calling access token. party_id: anyOf: - type: string minLength: 1 - type: 'null' title: Party Id description: >- String, optional. The borrower who owns the bank account. When omitted, the account's primary borrower is used. When given, it must be an active borrower on the account. routing_number: type: string pattern: ^[0-9]{9}$ title: Routing Number description: >- String, required. ABA routing number: exactly 9 digits, and it must pass the ABA checksum. account_number: type: string pattern: ^[0-9]{4,17}$ title: Account Number description: 'String, required. Bank account number: 4 to 17 digits.' account_type: type: string enum: - checking - savings title: Account Type description: String, required. One of `checking` or `savings`. name_on_account: anyOf: - type: string maxLength: 255 - type: 'null' title: Name On Account description: >- String, optional, at most 255 characters. Account holder name as it appears at the bank. bank_name: anyOf: - type: string maxLength: 255 - type: 'null' title: Bank Name description: String, optional, at most 255 characters. Bank name for display. nickname: anyOf: - type: string maxLength: 100 - type: 'null' title: Nickname description: >- String, optional, at most 100 characters. Borrower-chosen label for this payment method. set_default: type: boolean title: Set Default description: >- Boolean, optional, default false. Make this the borrower's default payment method. A borrower's first payment method becomes the default regardless. default: false additionalProperties: false type: object required: - account_id - routing_number - account_number - account_type title: BankPaymentMethodCreate description: |- Add an ACH bank account for a borrower on an account. The routing and account numbers are verified, then stored encrypted; responses only ever expose the last four digits. examples: - account_id: 01JABCDEF0123456789ABCDEFG account_number: '000123456789' account_type: checking bank_name: Bank of America name_on_account: Jane Q. Borrower nickname: Primary checking routing_number: '121000358' set_default: true PaymentMethodRow: properties: id: type: string title: Id party_id: type: string title: Party Id description: The person (borrower) this payment method belongs to. instrument_type: type: string title: Instrument Type description: 'Kind of instrument. One of: card, bank_account, wallet.' holder_name: anyOf: - type: string - type: 'null' title: Holder Name description: Name of the card or account holder. nickname: anyOf: - type: string - type: 'null' title: Nickname description: Borrower-chosen label for this payment method. is_active: type: boolean title: Is Active description: >- False once the payment method has been removed. Inactive methods cannot be attached to autopay or payments. last_four: type: string title: Last Four description: Last four digits of the card or account number. card_brand: anyOf: - type: string - type: 'null' title: Card Brand description: Card network (e.g. visa, mastercard). Cards only. card_exp_month: anyOf: - type: integer - type: 'null' title: Card Exp Month description: Card expiration month (1-12). Cards only. card_exp_year: anyOf: - type: integer - type: 'null' title: Card Exp Year description: Card expiration year (four digits). Cards only. bank_name: anyOf: - type: string - type: 'null' title: Bank Name description: Bank name. Bank accounts only. bank_account_type: anyOf: - type: string - type: 'null' title: Bank Account Type description: Bank account type (e.g. checking, savings). Bank accounts only. wallet_type: anyOf: - type: string - type: 'null' title: Wallet Type description: Wallet provider (e.g. apple_pay, google_pay). Wallets only. validation_status: anyOf: - type: string - type: 'null' title: Validation Status description: >- Bank-account verification state. `validated`: the account passed verification. `pending_giact`: the account is saved but verification could not complete yet and is pending. Null for instruments that are not verified this way. created_at: type: string format: date-time title: Created At updated_at: type: string format: date-time title: Updated At type: object required: - id - party_id - instrument_type - is_active - last_four - created_at - updated_at title: PaymentMethodRow description: |- A stored payment instrument (card, bank account, or wallet) belonging to a borrower. Carries display-safe metadata only — never full card or account numbers. ErrorResponse: properties: detail: $ref: '#/components/schemas/ErrorBody' type: object required: - detail title: ErrorResponse description: Standard error envelope. Branch on `detail.error_code`. ErrorBody: properties: error_code: type: string title: Error Code type: object required: - error_code title: ErrorBody description: Standard error body. Branch on `error_code`. securitySchemes: BearerToken: type: http description: Short-lived access token minted by POST /v1/oauth/token. scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.