Skip to main content
A customer represents an end user or business entity in your platform. Every payment, payment method, and provider registration is tied to a customer. Create a customer first, then attach payment methods and initiate payments on their behalf. 
import { createOakClient, createCustomerService } from '@oaknetwork/payments-sdk';

const client = createOakClient({ ... });
const customers = createCustomerService(client);

​
Methods

MethodDescription
create(customer)Create a new customer
get(id)Get a customer by ID
list(params?)List customers with optional filters
update(id, customer)Update an existing customer
sync(id, sync)Sync customer data to a provider
balance(customerId, filter)Get a customer’s balance for a provider
uploadFiles(customerId, files)Upload files for a customer
getFiles(customerId)Get files associated with a customer
populatePlatform(customerId)Populate platform data for a customer

​
Create a customer

const result = await customers.create({
  email: 'alice@example.com',
  first_name: 'Alice',
  last_name: 'Smith',
  country_code: 'US',
});

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

​
Get a customer

const result = await customers.get('cus_abc123');

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

​
List customers

const result = await customers.list({
  limit: 10,
  offset: 0,
  email: 'alice@example.com',
});

if (result.ok) {
  console.log(`Total: ${result.value.data.count}`);
  for (const c of result.value.data.customer_list) {
    console.log(`  ${c.id} — ${c.email}`);
  }
}

​
Query parameters

ParameterTypeDescription
limitnumberMaximum number of results
offsetnumberNumber of results to skip
emailstringFilter by email address
country_codestringFilter by country code
document_typestringFilter by document type
providerstringFilter by provider
provider_registration_statusstringFilter by provider registration status
target_rolestringFilter by target role

​
Update a customer

const result = await customers.update('cus_abc123', {
  first_name: 'Alice',
  last_name: 'Johnson',
  phone_country_code: '1',
  phone_area_code: '415',
  phone_number: '5551234',
});

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

​
Sync customer data

Push customer fields to a specific provider. This is useful when you update customer data locally and need the provider’s records to stay in sync. 
const result = await customers.sync('cus_abc123', {
  providers: ['stripe'],
  fields: ['email', 'first_name', 'last_name'],
});

if (result.ok) {
  console.log('Synced successfully');
}
FieldTypeDescription
providers[Provider]Provider to sync with (exactly one): "stripe", "bridge", "pagar_me", "brla", "avenia", "mercado_pago"
fieldsSyncField[]Fields to sync: "shipping", "email", "first_name", "last_name"

​
Get customer balance

Retrieve a customer’s balance for a specific provider and role. 
const result = await customers.balance('cus_abc123', {
  provider: 'stripe',
  role: 'connected_account',
});

if (result.ok) {
  for (const b of result.value.data.balances) {
    console.log(`Account: ${b.account_id} — Provider: ${b.provider}`);
    for (const t of b.totals) {
      console.log(`  ${t.currency}: ${t.amount} (pending: ${t.pending})`);
    }
  }
}
FieldTypeDescription
providerstringProvider to check balance for
rolestringCustomer role (e.g., "connected_account", "customer")

​
Request fields

All fields except email are optional on create. On update, all fields are optional.
FieldTypeDescription
emailstringCustomer email address
first_namestringFirst name
last_namestringLast name
document_numberstringTax ID or document number
document_type"personal_tax_id" | "company_tax_id"Document type
dobstringDate of birth
phone_country_codestringPhone country code
phone_area_codestringPhone area code
phone_numberstringPhone number
country_codestringCountry code
company_namestringCompany name

​
Upload files

Upload files for a customer (e.g., identity documents, proof of address): 
const result = await customers.uploadFiles('cus_abc123', formData);

if (result.ok) {
  console.log('Files uploaded:', result.value.data);
}
This method uses multipart form data upload internally via postMultipart().

​
Get files

Retrieve files associated with a customer: 
const result = await customers.getFiles('cus_abc123');

if (result.ok) {
  for (const file of result.value.data) {
    console.log(`File: ${file.id} — ${file.name}`);
  }
}

​
Populate platform

Populate platform-specific data for a customer: 
const result = await customers.populatePlatform('cus_abc123');

if (result.ok) {
  console.log('Platform data populated');
}

​
Customer status values

Customers have one of 12 possible status values throughout their lifecycle.

​
Response data

The response data object includes all request fields plus additional system fields like id, customer_id, customer_wallet, trading_wallet, account_type, additional_info, synced, synced_at, and address fields.