Skip to main content
This guide walks you from zero to a working API call in under 5 minutes.

​
1. Install the package

pnpm add @oaknetwork/payments-sdk dotenv
pnpm add -D tsx

​
2. Set your credentials

Don’t have credentials yet?Contact support@oaknetwork.org to get your sandbox CLIENT_ID and CLIENT_SECRET.
Create a .env file in your project root: 
CLIENT_ID=your-client-id
CLIENT_SECRET=your-client-secret

​
3. Create a client

import 'dotenv/config';
import { createOakClient, createCustomerService, createPaymentService } from '@oaknetwork/payments-sdk';

const client = createOakClient({
  environment: 'sandbox',
  clientId: process.env.CLIENT_ID!,
  clientSecret: process.env.CLIENT_SECRET!,
});

const customers = createCustomerService(client);
const payments = createPaymentService(client);
createOakClient configures authentication and retry behavior. Each create*Service(client) factory returns a typed service instance — import only the services you need.

​
4. Make your first call

async function main() {
  const result = await customers.list();

  if (result.ok) {
    console.log(`Found ${result.value.data.count} customers`);
    for (const customer of result.value.data.customer_list) {
      console.log(`  - ${customer.email}`);
    }
  } else {
    console.error('Request failed:', result.error.message);
  }
}

main();
Save steps 3 and 4 together in a file (e.g. index.ts) and run it: 
npx tsx index.ts
Every SDK method returns a Result<T, OakError> — a discriminated union that is either { ok: true, value: T } or { ok: false, error: OakError }. Check result.ok before accessing the value.
This pattern replaces try/catch for API calls. The SDK never throws on HTTP errors — it wraps them in the Result type. For the full breakdown, see Error Handling.

​
5. Create a customer

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

if (customer.ok) {
  console.log('Created customer:', customer.value.data.id);
} else {
  console.error('Failed:', customer.error.message);
}

​
6. Create a payment

const payment = await payments.create({
  provider: 'stripe',
  source: {
    amount: 5000,
    currency: 'usd',
    customer: { id: 'cus_abc123' },
    payment_method: { type: 'card', id: 'pm_xyz789' },
    capture_method: 'automatic',
  },
  confirm: true,
});

if (payment.ok) {
  console.log('Payment status:', payment.value.data.status);
} else {
  console.error('Payment failed:', payment.error.message);
}
Steps 5 and 6 go inside the main() function, after the list call.

​
Adding more services

Import additional service factories as you need them: 
import {
  createOakClient,
  createCustomerService,
  createPaymentService,
  createWebhookService,
} from '@oaknetwork/payments-sdk';

const client = createOakClient({
  environment: 'sandbox',
  clientId: process.env.CLIENT_ID!,
  clientSecret: process.env.CLIENT_SECRET!,
});

const customers = createCustomerService(client);
const payments = createPaymentService(client);
const webhooks = createWebhookService(client);
All services share the same client — authentication and retry logic are handled once.
  • Authentication — how OAuth2 token management works under the hood
  • Payments — create, confirm, and cancel payments across providers
  • Webhooks — register endpoints and receive real-time event notifications
  • Error Handling — the Result<T> pattern, error types, and retry configuration