Payment Instruments

A payment instrument is a tokenised card or bank account attached to a customer. The Easy API stores Finix-shaped payment-instrument objects; the SDK exposes the two server-safe operations: create (with a token from the front-end) and update (e.g. to disable an instrument).

Tokenisation itself happens client-side via BasisTheory — the basis_theory_public_api_key returned at client construction is what you hand to the browser SDK. Never send raw card data to the API.

Accessed via client.payment_instruments.

Methods

create(**body)

POST /payment. Attach a tokenised instrument to a customer.

client.payment_instruments.create(
  tokenId:    "tok_…",          # from BasisTheory tokenisation
  identityId: customer[:id],
  type:       "PAYMENT_CARD",
  name:       "Card on file"
)

update(id, **body)

PATCH /payment/:id. Mutate metadata, disable, or set as default.

client.payment_instruments.update("pi_…", enabled: false)

Object shape

Returned shape mirrors the Finix payment-instrument object — :id, :type, :name, :enabled, :identity, :tags, :bin, :last_four, :brand, …

Examples

Customer with a single card on file

customer = client.customers.create(
  first_name: "Ada", last_name: "Lovelace", email: "ada@example.com"
)

card = client.payment_instruments.create(
  tokenId:    token_from_browser,
  identityId: customer[:id],
  type:       "PAYMENT_CARD",
  name:       "Personal card"
)

client.transfers.create(amount: 1000, currency: "USD", source: card[:id])

Disable an instrument without deleting it

client.payment_instruments.update(card[:id], enabled: false)