Card capture

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.

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

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

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.

Authentication

Exchange your API key for an access token and use it on the secure proxy.

Conventions

Read the shared rate-limit, idempotency, and error rules.

Domain concepts

See how parties, accounts, payment methods, and billing addresses fit together.

Getting started

Core concepts

How-to guides

Before you call

Choose the borrower

Choose the billing address

Create the card payment method

Retry behavior

Read next

Authentication

Conventions

Domain concepts

​Before you call

​Choose the borrower

​Choose the billing address

​Create the card payment method

​Retry behavior

​Read next

Authentication

Conventions

Domain concepts

Before you call

Choose the borrower

Choose the billing address

Create the card payment method

Retry behavior

Read next