CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-stripe

Stripe API wrapper for Node.js providing comprehensive payment processing, subscription management, and financial services integration.

—

Pending
Overview
Eval results
Files

core-resources.mddocs/

Core Resources

Core resources are the fundamental building blocks of Stripe's payment processing system. These resources are directly accessible on the main Stripe instance and handle payment processing, customer management, and basic business operations.

Payment Processing

PaymentIntents

Primary resource for accepting payments with support for complex payment flows:

interface PaymentIntent {
  id: string;
  object: 'payment_intent';
  amount: number;
  currency: string;
  status: 'requires_payment_method' | 'requires_confirmation' | 'requires_action' | 'processing' | 'requires_capture' | 'canceled' | 'succeeded';
  customer?: string;
  payment_method?: string;
  confirmation_method: 'automatic' | 'manual';
  capture_method: 'automatic' | 'manual';
}

// Create payment intent
const paymentIntent = await stripe.paymentIntents.create({
  amount: 2000,
  currency: 'usd',
  customer: 'cus_123',
  payment_method_types: ['card', 'us_bank_account'],
  confirmation_method: 'automatic',
  capture_method: 'automatic'
});

// Retrieve payment intent
const retrieved = await stripe.paymentIntents.retrieve('pi_123', {
  expand: ['customer', 'payment_method']
});

// Update payment intent
const updated = await stripe.paymentIntents.update('pi_123', {
  description: 'Updated payment description',
  metadata: { order_id: '12345' }
});

// List payment intents
const paymentIntents = await stripe.paymentIntents.list({
  limit: 10,
  customer: 'cus_123'
});

// Confirm payment intent
const confirmed = await stripe.paymentIntents.confirm('pi_123', {
  payment_method: 'pm_card_visa',
  return_url: 'https://example.com/return'
});

// Cancel payment intent
const canceled = await stripe.paymentIntents.cancel('pi_123', {
  cancellation_reason: 'requested_by_customer'
});

// Capture payment intent (for manual capture)
const captured = await stripe.paymentIntents.capture('pi_123', {
  amount_to_capture: 1500
});

// Apply customer balance
const applied = await stripe.paymentIntents.applyCustomerBalance('pi_123', {
  amount: 500,
  currency: 'usd'
});

// Increment authorization
const incremented = await stripe.paymentIntents.incrementAuthorization('pi_123', {
  amount: 500
});

// Verify microdeposits
const verified = await stripe.paymentIntents.verifyMicrodeposits('pi_123', {
  amounts: [32, 45]
});

// Search payment intents
const searchResults = await stripe.paymentIntents.search({
  query: 'status:"succeeded" AND metadata["order_id"]:"12345"'
});

PaymentMethods

Represents a customer's payment instruments:

interface PaymentMethod {
  id: string;
  object: 'payment_method';
  type: 'card' | 'us_bank_account' | 'sepa_debit' | 'ideal' | string;
  customer?: string;
  card?: {
    brand: string;
    last4: string;
    exp_month: number;
    exp_year: number;
  };
}

// Create payment method
const paymentMethod = await stripe.paymentMethods.create({
  type: 'card',
  card: {
    number: '4242424242424242',
    exp_month: 12,
    exp_year: 2025,
    cvc: '123'
  },
  billing_details: {
    name: 'John Doe',
    email: 'john.doe@example.com'
  }
});

// Retrieve payment method
const retrieved = await stripe.paymentMethods.retrieve('pm_123');

// Update payment method
const updated = await stripe.paymentMethods.update('pm_123', {
  billing_details: {
    name: 'Jane Doe'
  }
});

// List payment methods
const paymentMethods = await stripe.paymentMethods.list({
  customer: 'cus_123',
  type: 'card'
});

// Attach to customer
const attached = await stripe.paymentMethods.attach('pm_123', {
  customer: 'cus_123'
});

// Detach from customer
const detached = await stripe.paymentMethods.detach('pm_123');

Charges

Represents completed payments:

interface Charge {
  id: string;
  object: 'charge';
  amount: number;
  currency: string;
  status: 'pending' | 'succeeded' | 'failed';
  customer?: string;
  payment_intent?: string;
  captured: boolean;
  refunded: boolean;
}

// Create charge (legacy, use PaymentIntents instead)
const charge = await stripe.charges.create({
  amount: 2000,
  currency: 'usd',
  source: 'tok_visa',
  description: 'My First Test Charge'
});

// Retrieve charge
const retrieved = await stripe.charges.retrieve('ch_123');

// Update charge
const updated = await stripe.charges.update('ch_123', {
  description: 'Updated charge description',
  metadata: { order_id: '12345' }
});

// List charges
const charges = await stripe.charges.list({
  limit: 10,
  customer: 'cus_123'
});

// Capture charge (for manual capture)
const captured = await stripe.charges.capture('ch_123', {
  amount: 1500
});

// Search charges
const searchResults = await stripe.charges.search({
  query: 'amount>999 AND metadata["order_id"]:"12345"'
});

Customer Management

Customers

Central resource for managing customer information and relationships:

interface Customer {
  id: string;
  object: 'customer';
  email?: string;
  name?: string;
  phone?: string;
  default_source?: string;
  invoice_prefix?: string;
  balance: number;
  created: number;
}

// Create customer
const customer = await stripe.customers.create({
  email: 'customer@example.com',
  name: 'John Doe',
  phone: '+1234567890',
  description: 'My first test customer',
  payment_method: 'pm_card_visa',
  invoice_settings: {
    default_payment_method: 'pm_card_visa'
  }
});

// Retrieve customer
const retrieved = await stripe.customers.retrieve('cus_123', {
  expand: ['default_source']
});

// Update customer
const updated = await stripe.customers.update('cus_123', {
  email: 'newemail@example.com',
  metadata: { user_id: '12345' }
});

// List customers
const customers = await stripe.customers.list({
  limit: 10,
  created: { gte: Math.floor(Date.now() / 1000) - 86400 }
});

// Delete customer
const deleted = await stripe.customers.del('cus_123');

// Search customers
const searchResults = await stripe.customers.search({
  query: 'email:"test@example.com" OR metadata["user_id"]:"12345"'
});

Customer Sub-resources

Manage customer-specific data:

// Customer balance transactions
const balanceTransaction = await stripe.customers.createBalanceTransaction(
  'cus_123',
  {
    amount: -1000,
    currency: 'usd',
    description: 'Store credit refund'
  }
);

const balanceTransactions = await stripe.customers.listBalanceTransactions('cus_123');

// Customer cash balance
const cashBalance = await stripe.customers.retrieveCashBalance('cus_123');

const updatedCashBalance = await stripe.customers.updateCashBalance('cus_123', {
  settings: {
    reconciliation_mode: 'automatic'
  }
});

// Customer payment methods
const paymentMethods = await stripe.customers.listPaymentMethods('cus_123', {
  type: 'card'
});

const paymentMethod = await stripe.customers.retrievePaymentMethod(
  'cus_123',
  'pm_123'
);

// Customer sources (legacy)
const source = await stripe.customers.createSource('cus_123', {
  source: 'tok_visa'
});

const sources = await stripe.customers.listSources('cus_123', {
  object: 'card'
});

// Customer tax IDs
const taxId = await stripe.customers.createTaxId('cus_123', {
  type: 'us_ein',
  value: '12-3456789'
});

const taxIds = await stripe.customers.listTaxIds('cus_123');

// Funding instructions
const fundingInstructions = await stripe.customers.createFundingInstructions(
  'cus_123',
  {
    bank_transfer: {
      requested_address_types: ['aba'],
      type: 'us_bank_transfer'
    },
    currency: 'usd',
    funding_type: 'bank_transfer'
  }
);

Product and Pricing

Products

Represents goods or services sold:

interface Product {
  id: string;
  object: 'product';
  name: string;
  description?: string;
  type: 'good' | 'service';
  active: boolean;
  default_price?: string;
}

// Create product
const product = await stripe.products.create({
  name: 'Gold Special',
  description: 'Premium gold membership',
  type: 'service',
  default_price_data: {
    currency: 'usd',
    unit_amount: 2000,
    recurring: {
      interval: 'month'
    }
  }
});

// Retrieve product
const retrieved = await stripe.products.retrieve('prod_123');

// Update product
const updated = await stripe.products.update('prod_123', {
  name: 'Platinum Special',
  description: 'Updated premium membership'
});

// List products
const products = await stripe.products.list({
  limit: 10,
  active: true
});

// Delete product
const deleted = await stripe.products.del('prod_123');

// Search products
const searchResults = await stripe.products.search({
  query: 'name:"gold" AND active:"true"'
});

Prices

Defines pricing information for products:

interface Price {
  id: string;
  object: 'price';
  product: string;
  unit_amount?: number;
  currency: string;
  type: 'one_time' | 'recurring';
  recurring?: {
    interval: 'day' | 'week' | 'month' | 'year';
    interval_count: number;
  };
}

// Create price
const price = await stripe.prices.create({
  product: 'prod_123',
  unit_amount: 2000,
  currency: 'usd',
  recurring: {
    interval: 'month'
  }
});

// Create tiered pricing
const tieredPrice = await stripe.prices.create({
  product: 'prod_123',
  currency: 'usd',
  billing_scheme: 'tiered',
  tiers_mode: 'volume',
  tiers: [
    { up_to: 10, unit_amount: 1000 },
    { up_to: 'inf', unit_amount: 800 }
  ],
  recurring: {
    interval: 'month'
  }
});

// Retrieve price
const retrieved = await stripe.prices.retrieve('price_123');

// Update price
const updated = await stripe.prices.update('price_123', {
  nickname: 'Monthly Gold Plan',
  metadata: { plan_type: 'premium' }
});

// List prices
const prices = await stripe.prices.list({
  limit: 10,
  product: 'prod_123',
  active: true
});

// Search prices
const searchResults = await stripe.prices.search({
  query: 'currency:"usd" AND type:"recurring"'
});

Account Management

Accounts

Manage Connect accounts:

interface Account {
  id: string;
  object: 'account';
  type: 'standard' | 'express' | 'custom';
  country: string;
  email?: string;
  default_currency: string;
  charges_enabled: boolean;
  payouts_enabled: boolean;
}

// Create account
const account = await stripe.accounts.create({
  type: 'express',
  country: 'US',
  email: 'merchant@example.com',
  capabilities: {
    card_payments: { requested: true },
    transfers: { requested: true }
  }
});

// Retrieve account (omit ID for own account)
const retrieved = await stripe.accounts.retrieve('acct_123');
const ownAccount = await stripe.accounts.retrieve();

// Update account
const updated = await stripe.accounts.update('acct_123', {
  business_profile: {
    name: 'Updated Business Name',
    url: 'https://example.com'
  }
});

// List accounts
const accounts = await stripe.accounts.list({
  limit: 10
});

// Delete account
const deleted = await stripe.accounts.del('acct_123');

// Reject account
const rejected = await stripe.accounts.reject('acct_123', {
  reason: 'fraud'
});

Account Sub-resources

// External accounts (bank accounts/cards for payouts)
const externalAccount = await stripe.accounts.createExternalAccount(
  'acct_123',
  {
    external_account: 'btok_123'
  }
);

const externalAccounts = await stripe.accounts.listExternalAccounts('acct_123');

// Persons (for custom accounts)
const person = await stripe.accounts.createPerson('acct_123', {
  first_name: 'John',
  last_name: 'Doe',
  email: 'john.doe@example.com',
  relationship: {
    representative: true,
    owner: true,
    percent_ownership: 100
  }
});

const persons = await stripe.accounts.listPersons('acct_123');

// Capabilities
const capabilities = await stripe.accounts.listCapabilities('acct_123');

const capability = await stripe.accounts.updateCapability(
  'acct_123',
  'card_payments',
  { requested: true }
);

// Login links (for Express accounts)
const loginLink = await stripe.accounts.createLoginLink('acct_123', {
  redirect_url: 'https://example.com/dashboard'
});

File Management

Files

Handle file uploads for identity verification and disputes:

interface File {
  id: string;
  object: 'file';
  filename?: string;
  purpose: 'account_requirement' | 'additional_verification' | 'business_icon' | 'business_logo' | 'customer_signature' | 'dispute_evidence' | 'document_provider_identity_document' | 'finance_report_run' | 'identity_document' | 'pci_document' | 'sigma_scheduled_query' | 'tax_document_user_upload';
  size: number;
  type?: string;
  url?: string;
}

// Upload file
const file = await stripe.files.create({
  file: {
    data: fs.readFileSync('path/to/file.pdf'),
    name: 'file.pdf',
    type: 'application/pdf'
  },
  purpose: 'dispute_evidence'
});

// Retrieve file
const retrieved = await stripe.files.retrieve('file_123');

// List files
const files = await stripe.files.list({
  limit: 10,
  purpose: 'dispute_evidence'
});

FileLinks

Create temporary links to files:

interface FileLink {
  id: string;
  object: 'file_link';
  file: string;
  url: string;
  expires_at?: number;
}

// Create file link
const fileLink = await stripe.fileLinks.create({
  file: 'file_123',
  expires_at: Math.floor(Date.now() / 1000) + 3600 // 1 hour
});

// Retrieve file link
const retrieved = await stripe.fileLinks.retrieve('link_123');

// Update file link
const updated = await stripe.fileLinks.update('link_123', {
  metadata: { purpose: 'customer_download' }
});

// List file links
const fileLinks = await stripe.fileLinks.list({
  limit: 10
});

Balance and Transactions

Balance

Check account balance:

interface Balance {
  object: 'balance';
  available: Array<{
    amount: number;
    currency: string;
    source_types?: {
      [key: string]: number;
    };
  }>;
  pending: Array<{
    amount: number;
    currency: string;
    source_types?: {
      [key: string]: number;
    };
  }>;
}

// Retrieve balance
const balance = await stripe.balance.retrieve();

BalanceTransactions

History of balance changes:

interface BalanceTransaction {
  id: string;
  object: 'balance_transaction';
  amount: number;
  currency: string;
  description?: string;
  fee: number;
  fee_details: Array<{
    amount: number;
    currency: string;
    description: string;
    type: string;
  }>;
  net: number;
  status: 'available' | 'pending';
  type: string;
}

// Retrieve balance transaction
const transaction = await stripe.balanceTransactions.retrieve('txn_123');

// List balance transactions
const transactions = await stripe.balanceTransactions.list({
  limit: 10,
  type: 'charge'
});

Disputes and Refunds

Disputes

Handle payment disputes:

interface Dispute {
  id: string;
  object: 'dispute';
  amount: number;
  currency: string;
  charge: string;
  status: 'warning_needs_response' | 'warning_under_review' | 'warning_closed' | 'needs_response' | 'under_review' | 'charge_refunded' | 'won' | 'lost';
  reason: string;
}

// Retrieve dispute
const dispute = await stripe.disputes.retrieve('dp_123');

// Update dispute
const updated = await stripe.disputes.update('dp_123', {
  evidence: {
    customer_communication: 'file_123',
    receipt: 'file_456'
  }
});

// List disputes
const disputes = await stripe.disputes.list({
  limit: 10,
  charge: 'ch_123'
});

// Close dispute
const closed = await stripe.disputes.close('dp_123');

Refunds

Process refunds:

interface Refund {
  id: string;
  object: 'refund';
  amount: number;
  currency: string;
  charge?: string;
  payment_intent?: string;
  status: 'pending' | 'succeeded' | 'failed' | 'canceled';
  reason?: 'duplicate' | 'fraudulent' | 'requested_by_customer';
}

// Create refund
const refund = await stripe.refunds.create({
  charge: 'ch_123',
  amount: 1000,
  reason: 'requested_by_customer'
});

// Retrieve refund
const retrieved = await stripe.refunds.retrieve('re_123');

// Update refund
const updated = await stripe.refunds.update('re_123', {
  metadata: { reason: 'defective_product' }
});

// List refunds
const refunds = await stripe.refunds.list({
  limit: 10,
  charge: 'ch_123'
});

// Cancel refund
const canceled = await stripe.refunds.cancel('re_123');

Transfers

Move money between accounts:

interface Transfer {
  id: string;
  object: 'transfer';
  amount: number;
  currency: string;
  destination: string;
  source_type: string;
  status: string;
}

// Create transfer
const transfer = await stripe.transfers.create({
  amount: 1000,
  currency: 'usd',
  destination: 'acct_123'
});

// Retrieve transfer
const retrieved = await stripe.transfers.retrieve('tr_123');

// Update transfer
const updated = await stripe.transfers.update('tr_123', {
  metadata: { order_id: '12345' }
});

// List transfers
const transfers = await stripe.transfers.list({
  limit: 10,
  destination: 'acct_123'
});

// Create transfer reversal
const reversal = await stripe.transfers.createReversal('tr_123', {
  amount: 500
});

// List transfer reversals
const reversals = await stripe.transfers.listReversals('tr_123');

SetupIntents

Handles setting up payment methods for future use without immediate payment:

interface SetupIntent {
  id: string;
  object: 'setup_intent';
  client_secret: string;
  customer?: string;
  payment_method?: string;
  status: 'requires_payment_method' | 'requires_confirmation' | 'requires_action' | 'processing' | 'canceled' | 'succeeded';
  usage: 'off_session' | 'on_session';
  payment_method_types: Array<string>;
  next_action?: {
    type: string;
    use_stripe_sdk?: Record<string, any>;
  };
}

// Create setup intent
const setupIntent = await stripe.setupIntents.create({
  customer: 'cus_123',
  payment_method_types: ['card'],
  usage: 'off_session'
});

// Create with automatic payment methods
const autoSetupIntent = await stripe.setupIntents.create({
  customer: 'cus_123',
  automatic_payment_methods: {
    enabled: true
  },
  usage: 'off_session'
});

// Retrieve setup intent
const retrieved = await stripe.setupIntents.retrieve('seti_123', {
  expand: ['payment_method']
});

// Update setup intent
const updated = await stripe.setupIntents.update('seti_123', {
  metadata: { order_id: '12345' }
});

// Confirm setup intent
const confirmed = await stripe.setupIntents.confirm('seti_123', {
  payment_method: 'pm_card_visa',
  return_url: 'https://your-website.com/return'
});

// List setup intents
const setupIntents = await stripe.setupIntents.list({
  customer: 'cus_123',
  limit: 10
});

// Cancel setup intent
const canceled = await stripe.setupIntents.cancel('seti_123');

PaymentLinks

Create shareable payment links for no-code payments:

interface PaymentLink {
  id: string;
  object: 'payment_link';
  url: string;
  active: boolean;
  line_items: {
    data: Array<{
      id: string;
      price: string;
      quantity: number;
    }>;
  };
  payment_method_types: Array<string>;
  shipping_address_collection?: {
    allowed_countries: Array<string>;
  };
}

// Create payment link
const paymentLink = await stripe.paymentLinks.create({
  line_items: [
    {
      price: 'price_123',
      quantity: 1
    }
  ],
  payment_method_types: ['card']
});

// Create with shipping
const shippingLink = await stripe.paymentLinks.create({
  line_items: [
    {
      price: 'price_123',
      quantity: 1
    }
  ],
  shipping_address_collection: {
    allowed_countries: ['US', 'CA']
  }
});

// Retrieve payment link
const retrieved = await stripe.paymentLinks.retrieve('plink_123');

// Update payment link
const updated = await stripe.paymentLinks.update('plink_123', {
  active: false,
  metadata: { campaign: 'summer_sale' }
});

// List payment links
const paymentLinks = await stripe.paymentLinks.list({
  active: true,
  limit: 10
});

// List line items
const lineItems = await stripe.paymentLinks.listLineItems('plink_123');

Quotes

Create and manage quotes for B2B workflows:

interface Quote {
  id: string;
  object: 'quote';
  status: 'draft' | 'open' | 'accepted' | 'canceled';
  customer: string;
  line_items: {
    data: Array<{
      id: string;
      price: string;
      quantity: number;
    }>;
  };
  amount_total: number;
  currency: string;
  expires_at: number;
}

// Create quote
const quote = await stripe.quotes.create({
  customer: 'cus_123',
  line_items: [
    {
      price: 'price_123',
      quantity: 2
    }
  ],
  collection_method: 'send_invoice'
});

// Create with subscription
const subscriptionQuote = await stripe.quotes.create({
  customer: 'cus_123',
  line_items: [
    {
      price: 'price_123',
      quantity: 1
    }
  ],
  subscription_data: {
    trial_period_days: 14
  }
});

// Retrieve quote
const retrieved = await stripe.quotes.retrieve('qt_123');

// Update quote
const updated = await stripe.quotes.update('qt_123', {
  metadata: { department: 'sales' }
});

// Finalize quote
const finalized = await stripe.quotes.finalizeQuote('qt_123');

// Accept quote
const accepted = await stripe.quotes.accept('qt_123');

// Cancel quote
const canceled = await stripe.quotes.cancel('qt_123');

// List quotes
const quotes = await stripe.quotes.list({
  customer: 'cus_123',
  status: 'open'
});

// List line items
const lineItems = await stripe.quotes.listLineItems('qt_123');

// List computed upfront line items
const upfrontItems = await stripe.quotes.listComputedUpfrontLineItems('qt_123');

These core resources provide the foundation for all Stripe integrations, handling the essential payment processing, customer management, and business operations that most applications require.

Install with Tessl CLI

npx tessl i tessl/npm-stripe

docs

billing.md

checkout.md

configuration.md

core-resources.md

identity.md

index.md

issuing.md

radar.md

subscriptions.md

tax.md

terminal.md

treasury.md

webhooks.md

tile.json