Customers

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

Method	Description
`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

Parameter	Type	Description
`limit`	`number`	Maximum number of results
`offset`	`number`	Number of results to skip
`email`	`string`	Filter by email address
`country_code`	`string`	Filter by country code
`document_type`	`string`	Filter by document type
`provider`	`string`	Filter by provider
`provider_registration_status`	`string`	Filter by provider registration status
`target_role`	`string`	Filter 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');
}

Field	Type	Description
`providers`	`[Provider]`	Provider to sync with (exactly one): `"stripe"`, `"bridge"`, `"pagar_me"`, `"brla"`, `"avenia"`, `"mercado_pago"`
`fields`	`SyncField[]`	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})`);
    }
  }
}

Field	Type	Description
`provider`	`string`	Provider to check balance for
`role`	`string`	Customer role (e.g., `"connected_account"`, `"customer"`)

Request fields

All fields except email are optional on create. On update, all fields are optional.

Field	Type	Description
`email`	`string`	Customer email address
`first_name`	`string`	First name
`last_name`	`string`	Last name
`document_number`	`string`	Tax ID or document number
`document_type`	`"personal_tax_id" \| "company_tax_id"`	Document type
`dob`	`string`	Date of birth
`phone_country_code`	`string`	Phone country code
`phone_area_code`	`string`	Phone area code
`phone_number`	`string`	Phone number
`country_code`	`string`	Country code
`company_name`	`string`	Company 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.

Getting Started

Services

Reference

Methods

Create a customer

Get a customer

List customers

Query parameters

Update a customer

Sync customer data

Get customer balance

Request fields

Upload files

Get files

Populate platform

Customer status values

Response data

​Methods

​Create a customer

​Get a customer

​List customers

​Query parameters

​Update a customer

​Sync customer data

​Get customer balance

​Request fields

​Upload files

​Get files

​Populate platform

​Customer status values

​Response data

Methods

Create a customer

Get a customer

List customers

Query parameters

Update a customer

Sync customer data

Get customer balance

Request fields

Upload files

Get files

Populate platform

Customer status values

Response data