> ## Documentation Index
> Fetch the complete documentation index at: https://docs.montereyfinancial.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a card payment method

> Create a stored card payment method without sending PAN or CVC to `api.montereyfinancial.app`. Send raw card requests only to `secure-api.montereyfinancial.app`, which forwards tokenized card data through the Basis Theory inbound proxy.



## OpenAPI

````yaml /api-reference/external_api.openapi.json post /v1/payment-methods/cards
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://api.montereyfinancial.app
    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/cards:
    post:
      tags:
        - Payment Methods
      summary: Create a card payment method
      description: >-
        Create a stored card payment method without sending PAN or CVC to
        `api.montereyfinancial.app`. Send raw card requests only to
        `secure-api.montereyfinancial.app`, which forwards tokenized card data
        through the Basis Theory inbound proxy.
      operationId: createCardPaymentMethod
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: >-
            Unique client-generated key for this create-card attempt. Re-use the
            same value only when retrying the same request.
          schema:
            type: string
            minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - account_id
                - card
              not:
                required:
                  - billing_address_id
                  - billing_address
              properties:
                account_id:
                  type: string
                party_id:
                  type: string
                cardholder_name:
                  type: string
                  maxLength: 255
                billing_address_id:
                  type: string
                nickname:
                  type: string
                  maxLength: 100
                set_default:
                  type: boolean
                  default: false
                billing_address:
                  type: object
                  additionalProperties: false
                  required:
                    - address_line1
                    - city
                    - state
                    - postal_code
                  properties:
                    address_line1:
                      type: string
                      minLength: 1
                      maxLength: 255
                    address_line2:
                      type:
                        - string
                        - 'null'
                      maxLength: 255
                    city:
                      type: string
                      minLength: 1
                      maxLength: 120
                    state:
                      type: string
                      minLength: 2
                      maxLength: 120
                    postal_code:
                      type: string
                      minLength: 3
                      maxLength: 20
                    country:
                      type: string
                      minLength: 2
                      maxLength: 120
                      default: US
                card:
                  type: object
                  additionalProperties: false
                  required:
                    - number
                    - expiration_month
                    - expiration_year
                    - cvc
                  properties:
                    number:
                      type: string
                      minLength: 12
                      maxLength: 19
                    expiration_month:
                      type: integer
                      maximum: 12
                      minimum: 1
                    expiration_year:
                      type: integer
                      minimum: 2000
                      maximum: 9999
                    cvc:
                      type: string
                      minLength: 3
                      maxLength: 4
              description: >-
                Raw card payload accepted only on the secure card-capture
                hostname. At most one billing-address input may be supplied: use
                `billing_address_id` to re-use an existing party address, send
                `billing_address` to use a transient address for this card, or
                omit both so Monterey falls back to the selected borrower's
                current billing address.
      responses:
        '201':
          description: Card payment method created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethodRow'
        '400':
          description: Proxy request shape invalid before tokenization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Bearer token invalid, expired, or proxy signature invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            Authenticated token lacks `payment_methods:write`
            (`insufficient_scope`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Account not found or not visible to the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Duplicate card, idempotency conflict, or in-progress retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Billing address selection invalid or request validation failed.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorResponse'
                  - $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
        '502':
          description: Gateway tokenization or token-intent conversion failed.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                description: >-
                  Gateway-side or token-intent conversion failure. Retry only
                  when `detail.retryable` is true.
                required:
                  - detail
                properties:
                  detail:
                    type: object
                    additionalProperties: false
                    required:
                      - error_code
                      - retryable
                    properties:
                      error_code:
                        type: string
                        enum:
                          - gateway_tokenization_failed
                          - token_intent_conversion_failed
                      retryable:
                        type: boolean
        '503':
          description: Card capture is disabled or upstream capture is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerToken: []
      servers:
        - url: https://secure-api.montereyfinancial.app
components:
  schemas:
    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.
        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`.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
      description: >-
        Parameter-validation error (HTTP 422). `detail` lists each violated
        constraint with its location, message, and type.
    RateLimitErrorResponse:
      properties:
        detail:
          $ref: '#/components/schemas/RateLimitErrorBody'
      type: object
      required:
        - detail
      title: RateLimitErrorResponse
      description: Rate-limit error envelope returned with HTTP 429.
    ErrorBody:
      properties:
        error_code:
          type: string
          title: Error Code
      type: object
      required:
        - error_code
      title: ErrorBody
      description: Standard error body. Branch on `error_code`.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
      description: >-
        A single parameter-validation failure: `loc` is the path to the
        offending input, `msg` is human-readable, and `type` is the rule that
        failed.
    RateLimitErrorBody:
      properties:
        error_code:
          type: string
          const: rate_limited
          title: Error Code
        bucket:
          type: string
          enum:
            - api
            - token
          title: Bucket
        limit_per_minute:
          type: integer
          title: Limit Per Minute
        burst_capacity:
          type: integer
          title: Burst Capacity
        retry_after_seconds:
          type: integer
          title: Retry After Seconds
        reset_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Reset At
      type: object
      required:
        - error_code
        - bucket
        - limit_per_minute
        - burst_capacity
        - retry_after_seconds
        - reset_at
      title: RateLimitErrorBody
      description: Self-tuning details returned after a rate-limit denial.
  securitySchemes:
    BearerToken:
      type: http
      description: Short-lived access token minted by POST /v1/oauth/token.
      scheme: bearer
      bearerFormat: JWT

````