Skip to main content
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

MethodDescription
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

TypeProvidersDescription
BridgeBankAccountBridgeUS bank account with routing/account numbers
OakBankAccountOakBank account with SWIFT code
StripeBankAccountStripeBank account via Stripe
MercadoPagoCardMercadoPagoCard via token
PagarMeCardPagarMeCard via token with billing address
StripeCardStripeCard via Stripe
OakCustomerWalletOakEVM wallet address
BridgeLiquidationAddressBridgeCrypto liquidation address
OakPixOakPIX payment method
BridgePlaidBridgePlaid-linked bank account
BridgeVirtualAccountBridgeVirtual account for on/off ramp
TradingWalletOakTrading wallet
PlaidResponseDataBridgePlaid 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');
}