Payment Instrument
The Payment Instrument entity in Payments.
A Payment Instrument is a saved, tokenized funding source attached to a Customer — a card or a bank account. It is what you reference as the source on a Transfer or as the funding side of a Subscription. The raw card or bank-account number never touches your servers: tokenization happens in the iframe / browser SDK, and the API stores only the network token, the last four digits, BIN, brand, expiration, and AVS metadata.
Lifecycle
- Tokenized — the buyer enters card or bank details inside the embedded checkout iframe (or the React tokenization helpers in
@easylabs/react). Tokenization produces an opaque token ID. - Created —
client.createPaymentInstrument({ identityId, tokenId, type, … })exchanges the token for a persistent Payment Instrument tied to the Customer. The response includes derived fields likebrand,last_four, andexpiration_month/expiration_year. - Used — pass the Payment Instrument
idas thesourceonclient.createTransfer({ amount, currency, source }), onclient.createCheckout(...), or asinstrument_idon a Subscription. - Updated —
client.updatePaymentInstrument(id, { enabled, address, name, tags, … })toggles enable state, refreshes the billing address, or patches AVS-related fields. - Disabled — set
enabled: falseto stop accepting new charges against the instrument; existing recurring subscriptions will start failing on next attempt.
Relationships
A Payment Instrument always belongs to one Customer (identity_id). One Customer can own many instruments — typically one default card plus older saved cards or bank accounts. Each Transfer references exactly one Payment Instrument as its source. Subscriptions reference one as instrument_id for recurring collection.
Fields that matter
id(string) — pass assourceon Transfers, asinstrument_idon Subscriptions.type("PAYMENT_CARD" | "BANK_ACCOUNT") — discriminates card vs. ACH; affects which fields are populated and which Transfer rails apply.enabled(boolean) — soft toggle.falseblocks new charges without deleting history.brand,last_four,expiration_month,expiration_year— for displaying "Visa •••• 4242 (12/27)" in your UI.bin,card_type,issuer_country— for routing decisions, fee surcharging, or geo-restricted offers.account_updater_enabled,network_token_enabled— when on, the network refreshes the underlying credential on expiry / re-issuance so saved cards keep working.address(Address | null) — billing address used for AVS.