Skip to main content

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​

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');
}