Payments SDK

The @oaknetwork/payments-sdk package is a TypeScript SDK that wraps the Oak Network payment API — handling authentication, retries, and type safety so you can focus on building your integration.

Get your API credentialsTo start building with the SDK, you need a Client ID and Client Secret. Reach out to support@oaknetwork.org to get your sandbox credentials and start integrating today.

Highlights

Initialize a client for sandbox or production: createOakClient({ environment: 'sandbox', ... })
Standalone service factories — import only what you need: createCustomerService(client), createPaymentService(client), etc.
Type-safe results on every call: every method returns Result<T, OakError> — no uncaught exceptions
Built-in retry with exponential backoff, jitter, and Retry-After header support
Webhook signature verification built in: verifyWebhookSignature() and parseWebhookPayload()
Two environments out of the box: sandbox and production, plus customUrl for self-hosted setups

Quick example

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

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

const customers = createCustomerService(client);

const result = await customers.list();

if (result.ok) {
  console.log(result.value.data);
} else {
  console.error(result.error.message);
}

See the full walkthrough in the Quickstart guide.

Services

The SDK ships 16 service modules. Import the factory function for each service you need.

Service	Factory	What it does
`CustomerService`	`createCustomerService(client)`	Create, get, list, update, sync, check balances, upload/get files, populate platform
`PaymentService`	`createPaymentService(client)`	Create, confirm, cancel, capture payments; sandbox test helpers
`PaymentMethodService`	`createPaymentMethodService(client)`	Add, list, get, update, delete payment methods
`WebhookService`	`createWebhookService(client)`	Register, manage, and monitor webhooks
`TransactionService`	`createTransactionService(client)`	List, get, and settle transactions
`TransferService`	`createTransferService(client)`	Create provider transfers and send webhooks
`PlanService`	`createPlanService(client)`	CRUD subscription plans with active/expired filters
`RefundService`	`createRefundService(client)`	Refund a payment
`BuyService`	`createBuyService(client)`	Crypto on-ramp via Bridge or BRLA
`SellService`	`createSellService(client)`	Crypto off-ramp via Avenia
`SubscriptionService`	`createSubscriptionService(client)`	Subscribe, cancel, list, get, and pay subscriptions
`DisputeService`	`createDisputeService(client)`	List, update evidence, submit, and close disputes
`PayoutService`	`createPayoutService(client)`	Create payouts
`FileService`	`createFileService(client)`	Upload, list, get, and delete files
`TaxService`	`createTaxService(client)`	Calculate taxes
`ProviderService`	`createProviderService(client)`	Fetch provider schemas, submit registrations, and check registration status

Next up

Installation — install the package and configure credentials
Quickstart — your first working integration in under 5 minutes
Error Handling — understand the Result<T> pattern and error types

Getting Started

Services

Reference

Highlights

Quick example

Services

Next up

​Highlights

​Quick example

​Services

​Next up

Highlights

Quick example

Services

Next up