> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oaknetwork.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

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

## 1. Install the package

```bash theme={null}
pnpm add @oaknetwork/payments-sdk dotenv
pnpm add -D tsx
```

## 2. Set your credentials

<Tip>
  **Don't have credentials yet?**

  Contact **[support@oaknetwork.org](mailto:support@oaknetwork.org)** to get your sandbox `CLIENT_ID` and `CLIENT_SECRET`.
</Tip>

Create a `.env` file in your project root:

```bash theme={null}
CLIENT_ID=your-client-id
CLIENT_SECRET=your-client-secret
```

## 3. Create a client

```typescript theme={null}
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

```typescript theme={null}
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:

```bash theme={null}
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](/sdk/error-handling).

## 5. Create a customer

```typescript theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
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.

## What to read next

* [Authentication](/sdk/authentication) — how OAuth2 token management works under the hood
* [Payments](/sdk/payments) — create, confirm, and cancel payments across providers
* [Webhooks](/sdk/webhooks) — register endpoints and receive real-time event notifications
* [Error Handling](/sdk/error-handling) — the `Result<T>` pattern, error types, and retry configuration