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

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

> [!NOTE]
>
> Availability is environment-specific. Until Monterey enables secure capture for your environment, this endpoint may return `503`.

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

> **[Authentication](https://docs.montereyfinancial.com/api-reference/authentication.md)**
>
> Exchange your API key for an access token and use it on the secure proxy.

> **[Conventions](https://docs.montereyfinancial.com/api-reference/conventions.md)**
>
> Read the shared rate-limit, idempotency, and error rules.

> **[Domain concepts](https://docs.montereyfinancial.com/api-reference/domain-concepts.md)**
>
> See how parties, accounts, payment methods, and billing addresses fit together.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.