Skip to main content

Payment Instruments API

Manage payment methods including credit cards and bank accounts.

Methods​

createPaymentInstrument​

Create a payment instrument (requires tokenId from client-side tokenization).

Payment Card:

const cardInstrument = await easy.createPaymentInstrument({
  type: "PAYMENT_CARD",
  name: "Primary Card",
  identityId: "cust_123",
  tokenId: "tok_abc123", // From client-side tokenization
  address: {
    line1: "123 Main St",
    city: "Anytown",
    state: "CA",
    postal_code: "12345",
    country: "US",
  },
  tags: {
    default: "true",
  },
});

Bank Account:

const bankInstrument = await easy.createPaymentInstrument({
  type: "BANK_ACCOUNT",
  name: "Checking Account",
  identityId: "cust_123",
  tokenId: "tok_xyz789", // From client-side tokenization
  accountType: "CHECKING",
  attempt_bank_account_validation_check: false,
  tags: {
    primary: "true",
  },
});

Parameters​

  • data (object, required)
    • type (string, required): 'PAYMENT_CARD' or 'BANK_ACCOUNT'
    • name (string, required): Display name for the payment method
    • identityId (string, required): Customer ID
    • tokenId (string, required): Token from client-side tokenization
    • address (object, optional): Billing address (for cards)
    • accountType (string, optional): 'CHECKING' or 'SAVINGS' (for bank accounts)
    • attempt_bank_account_validation_check (boolean, optional): Validate bank account
    • tags (object, optional): Custom metadata

Returns​

Promise<ApiResponse<PaymentInstrumentData>>;
Important

The tokenId must be obtained from client-side tokenization using @easylabs/react or similar client SDK. Never send raw card or bank account details to your server.

updatePaymentInstrument​

Update a payment instrument.

const updated = await easy.updatePaymentInstrument("pi_123", {
  name: "Updated Card Name",
  tags: {
    status: "verified",
  },
});

Parameters​

  • instrumentId (string, required): The ID of the payment instrument
  • data (object, required): Fields to update
    • name (string, optional): New display name
    • tags (object, optional): Updated metadata

Returns​

Promise<ApiResponse<PaymentInstrumentData>>;

getCustomerPaymentInstruments​

Get all payment instruments for a customer.

const instruments = await easy.getCustomerPaymentInstruments("cust_123");

Parameters​

  • customerId (string, required): The ID of the customer

Returns​

Promise<ApiResponse<PaymentInstrumentData[]>>;

Type Definitions​

PaymentInstrumentData​

interface PaymentInstrumentData {
  id: string;
  type: "PAYMENT_CARD" | "BANK_ACCOUNT";
  name: string;
  identity_id: string;
  created_at: string;
  updated_at: string;

  // Card-specific fields
  card_brand?: string;
  card_last4?: string;
  card_exp_month?: number;
  card_exp_year?: number;

  // Bank account-specific fields
  bank_name?: string;
  account_last4?: string;
  account_type?: "CHECKING" | "SAVINGS";

  tags?: Record<string, unknown>;
}