Skip to main content
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.
ServiceFactoryWhat it does
CustomerServicecreateCustomerService(client)Create, get, list, update, sync, check balances, upload/get files, populate platform
PaymentServicecreatePaymentService(client)Create, confirm, cancel, capture payments; sandbox test helpers
PaymentMethodServicecreatePaymentMethodService(client)Add, list, get, update, delete payment methods
WebhookServicecreateWebhookService(client)Register, manage, and monitor webhooks
TransactionServicecreateTransactionService(client)List, get, and settle transactions
TransferServicecreateTransferService(client)Create provider transfers and send webhooks
PlanServicecreatePlanService(client)CRUD subscription plans with active/expired filters
RefundServicecreateRefundService(client)Refund a payment
BuyServicecreateBuyService(client)Crypto on-ramp via Bridge or BRLA
SellServicecreateSellService(client)Crypto off-ramp via Avenia
SubscriptionServicecreateSubscriptionService(client)Subscribe, cancel, list, get, and pay subscriptions
DisputeServicecreateDisputeService(client)List, update evidence, submit, and close disputes
PayoutServicecreatePayoutService(client)Create payouts
FileServicecreateFileService(client)Upload, list, get, and delete files
TaxServicecreateTaxService(client)Calculate taxes
ProviderServicecreateProviderService(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