> ## 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.

# Card capture

> Create stored card payment methods through the secure proxy without sending PAN or CVC to the public API.

Use this flow when you need to create a stored card payment method from raw card data. Send the request to `https://secure-api.montereyfinancial.app`, not `api.montereyfinancial.app`.

<Warning>
  Never send PAN or CVC to `api.montereyfinancial.app`. Raw card data belongs on `https://secure-api.montereyfinancial.app` only.
</Warning>

<Note>
  Availability is environment-specific. Until Monterey enables secure capture for your environment, this endpoint may return `503`.
</Note>

## Before you call

* An API key that can mint an access token
* The `payment_methods:write` scope
* `curl` and `jq`
* A Basis Theory test card supported by your environment

This page documents the request shape. It does not verify which test cards your Basis Theory environment has enabled.

## Choose the borrower

| If you know\...                            | Send...         | Result                                                     |
| ------------------------------------------ | --------------- | ---------------------------------------------------------- |
| The account's primary borrower             | Omit `party_id` | Monterey uses the primary borrower automatically           |
| A different active borrower on the account | `party_id`      | Monterey creates the card payment method for that borrower |

`party_id` must be visible to the token and attached to the account.

## Choose the billing address

| If you have...                                             | Send...              | Result                                                        |
| ---------------------------------------------------------- | -------------------- | ------------------------------------------------------------- |
| A current billing address already on file for the borrower | Omit both fields     | Monterey uses the selected borrower's current billing address |
| An address already on file for the borrower                | `billing_address_id` | Monterey reuses the saved party address                       |
| A one-time billing address                                 | `billing_address`    | Monterey validates the address for this request only          |

Send at most one of `billing_address_id` or `billing_address`. Omit both to use the selected borrower's current billing address. The inline address is transient and does not create a new saved party address.

## Create the card payment method

```bash theme={null}
set -euo pipefail

ACCESS_TOKEN=$(curl --fail-with-body -sS -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "mfs_AbCd1234",
    "client_secret": "mk_your_key_here"
  }' \
  https://api.montereyfinancial.app/v1/oauth/token | jq -er .access_token)

curl --fail-with-body -sS -X POST \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: 7c4f2e9f-2c5e-4b35-9e1d-01f0a4b0f5f0" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "01J...",
    "party_id": "01J...",
    "billing_address_id": "01J...",
    "card": {
      "number": "YOUR_TEST_CARD_NUMBER",
      "expiration_month": 12,
      "expiration_year": 2030,
      "cvc": "YOUR_TEST_CVC"
    },
    "cardholder_name": "Jane Smith",
    "nickname": "Personal Visa",
    "set_default": true
  }' \
  https://secure-api.montereyfinancial.app/v1/payment-methods/cards
```

Replace the card fields with a test card supported by your Basis Theory environment. Omit `party_id` if you want Monterey to use the account's primary borrower. Swap `billing_address_id` for `billing_address` if you need a transient address for this request.

## Retry behavior

| Case                                                                 | Result                                                                        |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| First submission with a new `Idempotency-Key`                        | `201 Created`                                                                 |
| Safe replay with the same key and the same body after success        | `201 Created` with the stored response                                        |
| Same key with a different body, or an in-flight duplicate            | `409 Conflict`                                                                |
| Upstream tokenization or conversion failure marked `retryable: true` | `502`; retry the same request after backoff                                   |
| Secure capture is not enabled for the environment                    | `503`; check whether Monterey has enabled secure capture for that environment |

Retry only the exact same request body with the same `Idempotency-Key`.

## Read next

<Columns cols={3}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Exchange your API key for an access token and use it on the secure proxy.
  </Card>

  <Card title="Conventions" icon="book" href="/api-reference/conventions">
    Read the shared rate-limit, idempotency, and error rules.
  </Card>

  <Card title="Domain concepts" icon="boxes" href="/api-reference/domain-concepts">
    See how parties, accounts, payment methods, and billing addresses fit together.
  </Card>
</Columns>