Payment Instruments

A payment instrument is a tokenized card or bank account attached to a customer (identityId). Card and bank PANs never touch your servers — collect them through the Easy frontend SDK or Basis Theory and pass the resulting tokenId here.

Methods

`createPaymentInstrument(data)`

POST /payment. Validates that tokenId is present, then sends one of two discriminated bodies:

// Card
await easy.createPaymentInstrument({
  type: "PAYMENT_CARD",
  identityId: customer.id,
  tokenId: tokenFromFrontend,
  name: "Ada Lovelace",
  address: {
    line1: "1 Pioneer Way",
    city: "Menlo Park",
    region: "CA",
    postal_code: "94025",
    country: "USA",
  },
});

// Bank account
await easy.createPaymentInstrument({
  type: "BANK_ACCOUNT",
  identityId: customer.id,
  tokenId: tokenFromFrontend,
  name: "Ada Lovelace",
  accountType: "PERSONAL_CHECKING",
  attempt_bank_account_validation_check: true,
});

The SDK throws synchronously if tokenId is missing or type is unrecognized.

`updatePaymentInstrument(paymentInstrumentId, data)`

PATCH /payment/:id. Accepts an UpdatePaymentInstrument shape:

await easy.updatePaymentInstrument(piId, {
  enabled: false,
  account_updater_enabled: true,
  network_token_enabled: true,
  address: { line1: "2 Pioneer Way", city: "Menlo Park", region: "CA", postal_code: "94025", country: "USA", line2: null },
  tags: { source: "manual_review" },
});

`getCustomerPaymentInstruments(customerId)`

Listed under Customers — there is no top-level "list all instruments" endpoint; always scope by customer.

Object shape

Two response shapes show up depending on which endpoint you hit:

FinixPaymentInstrumentData — returned by createPaymentInstrument. Mirrors the underlying processor record (snake_case identifiers, _links, instrument_type, etc.).
PaymentInstrumentData — returned by listing endpoints and updatePaymentInstrument. The application-level shape: id, identity_id, type ("PAYMENT_CARD" | "BANK_ACCOUNT"), brand / last_four / expiration_* for cards, bank_code / masked_account_number / account_type / bank_account_validation_check for bank accounts, plus enabled, account_updater_enabled, network_token_enabled, address, tags.

Examples

Disable an instrument without deleting it

await easy.updatePaymentInstrument(instrumentId, { enabled: false });

Disabled instruments stay attached to the customer for audit but cannot be charged.

Re-trigger bank-account validation

await easy.updatePaymentInstrument(bankAccountId, {
  attempt_bank_account_validation_check: true,
});

Choose the default for a customer

The default-instrument decision is currently part of charge calls (payInvoice({ instrument_id }), createSubscription({ instrument_id }), etc.) rather than a dedicated method on the instrument itself.

Payment Instruments

On this page