Payment Methods

A payment method is a stored instrument (card, bank account, crypto wallet, PIX key, or trading wallet) attached to a customer. Once added, it can be referenced by ID when creating payments or transfers — the customer does not need to re-enter their details each time.

import { createOakClient, createPaymentMethodService } from '@oaknetwork/payments-sdk';

const client = createOakClient({ ... });
const paymentMethods = createPaymentMethodService(client);

Methods

Method	Description
add(customerId, method)	Add a payment method to a customer
get(customerId, paymentId)	Get a specific payment method
list(customerId, query?)	List a customer's payment methods
update(customerId, methodId, data)	Update a payment method
delete(customerId, methodId)	Delete a payment method

Add a payment method

The request shape depends on the payment method type and provider. Here are the most common patterns.

Stripe card

const result = await paymentMethods.add('cus_abc123', {
  type: 'card',
  provider: 'stripe',
});

Bridge bank account

const result = await paymentMethods.add('cus_abc123', {
  type: 'bank',
  provider: 'bridge',
  currency: 'usd',
  bank_name: 'Chase',
  bank_account_number: '000123456789',
  bank_routing_number: '021000021',
  bank_account_type: 'checking',
  bank_account_name: 'Alice Smith',
  billing_address: {
    street_line_1: '123 Main St',
    city: 'New York',
    state: 'NY',
    postal_code: '10001',
    country: 'US',
  },
});

Crypto wallet

const result = await paymentMethods.add('cus_abc123', {
  type: 'customer_wallet',
  evm_address: '0x1234567890abcdef1234567890abcdef12345678',
  chain: 'polygon',
  currency: 'usdc',
});

PIX

const result = await paymentMethods.add('cus_abc123', {
  type: 'pix',
  pix_string: 'alice@example.com',
});

Payment method types

The type field on a payment method is one of: "bank", "card", "plaid", "virtual_account", "liquidation_address", "trading_wallet", "customer_wallet", "pix", "evm_address".

Bank account types

The bank_account_type field can be: "payment", "checking", "savings", "virtual_account".

Type reference

Type	Providers	Description
BridgeBankAccount	Bridge	US bank account with routing/account numbers
OakBankAccount	Oak	Bank account with SWIFT code
StripeBankAccount	Stripe	Bank account via Stripe
MercadoPagoCard	MercadoPago	Card via token
PagarMeCard	PagarMe	Card via token with billing address
StripeCard	Stripe	Card via Stripe
OakCustomerWallet	Oak	EVM wallet address
BridgeLiquidationAddress	Bridge	Crypto liquidation address
OakPix	Oak	PIX payment method
BridgePlaid	Bridge	Plaid-linked bank account
BridgeVirtualAccount	Bridge	Virtual account for on/off ramp
TradingWallet	Oak	Trading wallet
PlaidResponseData	Bridge	Plaid response data

List payment methods

const result = await paymentMethods.list('cus_abc123', {
  type: 'card',
});

if (result.ok) {
  for (const pm of result.value.data) {
    console.log(`${pm.id} — ${pm.type} — ${pm.status}`);
  }
}

Get a payment method

const result = await paymentMethods.get('cus_abc123', 'pm_xyz789');

if (result.ok) {
  console.log('Type:', result.value.data.type);
  console.log('Status:', result.value.data.status);
}

Update a payment method

const result = await paymentMethods.update('cus_abc123', 'pm_xyz789', {
  bank_account_name: 'Alice Johnson',
});

if (result.ok) {
  console.log('Updated:', result.value.data.id);
}

Delete a payment method

const result = await paymentMethods.delete('cus_abc123', 'pm_xyz789');

if (result.ok) {
  console.log('Deleted');
}