Payment Instruments

A PaymentInstrument is a saved payment method (card or bank account) attached to a customer. The SDK surfaces the two server-side mutation endpoints; reads come through client.customers.payment_instruments(...).

Namespace: client.payment_instruments.

Cards must be tokenized client-side first (via Basis Theory) — the server only ever receives the resulting token_id. The tokenization step happens in the browser, not in the Python SDK.

Methods

`create`

instrument = client.payment_instruments.create(
    type="PAYMENT_CARD",                   # or "BANK_ACCOUNT"
    name="Ada Lovelace",
    identity_id="ident_123",
    token_id="tok_abc",                    # required
    address={
        "line1": "1 Babbage St",
        "city": "London",
        "country": "GB",
    },
    idempotency_key="inst-ada-2025-01-01",
)

Returns: FinixPaymentInstrument. Pass type="BANK_ACCOUNT" for ACH instead, with account_type="checking" (or "savings") and an attempt_bank_account_validation_check=True/False. Any extra keyword arguments are forwarded as-is to the API.

token_id is required — the SDK raises ValueError if you pass an empty string.

`update`

instrument = client.payment_instruments.update(
    "pi_123",
    enabled=False,
    tags={"deprecated": True},
)

PATCHes any combination of writable fields. Returns the updated PaymentInstrument.

Object shape

PaymentInstrument (returned by reads):

Field	Type
`id`	`str`
`identity_id`	`str \| None`
`type`	`str \| None`
`enabled`	`bool \| None`
`currency`	`str \| None`
`last_four`	`str \| None`
`brand` / `card_type`	`str \| None`
`expiration_month` / `expiration_year`	`int \| None`
`bank_code`, `masked_account_number`, `account_type`	`str \| None`
`name`, `fingerprint`	`str \| None`
`address`, `tags`	`dict[str, Any] \| None`
`created_at`, `updated_at`	`str \| None`

FinixPaymentInstrument (returned by create) includes processor- specific fields like bin, issuer_country, and address_verification.

Examples

Save a card and immediately charge it

inst = client.payment_instruments.create(
    type="PAYMENT_CARD",
    name="Ada Lovelace",
    identity_id="ident_123",
    token_id="tok_abc",
)

transfer = client.transfers.create(
    amount=2500,
    currency="USD",
    source=inst.id,
    idempotency_key=f"order-{order_id}",
)

Disable a card without deleting it

client.payment_instruments.update("pi_123", enabled=False)