SDKs & Libraries
Start with the REST API. The TypeScript SDK is an optional wrapper over the same public API-key surface.
REST
REST API
The REST API is the canonical integration path and is the fastest way to verify your platform flow.
Create a Participant
curl -X POST https://api.soledgic.com/v1/participants \
-H "x-api-key: slk_test_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"participant_id": "creator_456",
"display_name": "Jane Creator",
"email": "jane@example.com",
"default_split_percent": 80
}'Create a Checkout Session
curl -X POST https://api.soledgic.com/v1/checkout-sessions \
-H "x-api-key: slk_test_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"participant_id": "creator_456",
"amount": 2999,
"currency": "USD",
"product_name": "Premium asset pack",
"success_url": "https://example.com/success",
"cancel_url": "https://example.com/cancel",
"idempotency_key": "checkout_order_1001"
}'Node.js fetch
Payout creation should be attempted only after payout eligibility returns true.
const response = await fetch('https://api.soledgic.com/v1/payouts', {
method: 'POST',
headers: {
'x-api-key': 'slk_test_your_api_key',
'Content-Type': 'application/json',
},
body: JSON.stringify({
participant_id: 'creator_456',
reference_id: 'payout_2026_03_12_001',
amount: 1500,
payout_method: 'bank',
}),
});
const result = await response.json();TS
TypeScript / JavaScript
Install the SDK when you want typed request and response helpers over the public REST API.
The SDK targets the public API-key contract only; dashboard/session routes for shared identity, ecosystems, and internal tooling are intentionally excluded.
New integrations should use the namespaced SDK contract below. Existing SDK installs keep working through compatibility shims while teams migrate.
Installation
npm install @soledgic/sdk@0.5.2
Usage
import SoledgicClient from '@soledgic/sdk';
const soledgic = new SoledgicClient({
apiKey: 'slk_test_your_api_key',
baseUrl: 'https://api.soledgic.com',
apiVersion: '2026-03-01',
});
const userWallet = await soledgic.users.upsertWallet({
externalUserId: 'user_123',
name: 'User 123 wallet',
});
const creator = await soledgic.creators.upsert({
externalCreatorId: 'creator_456',
userId: '9f9b62d2-2f32-4b20-bc24-1f86b16cb9eb',
displayName: 'Jane Creator',
email: 'jane@example.com',
defaultSplitPercent: 80,
});
const checkout = await soledgic.orders.createCheckout({
creatorId: creator.participant.id,
externalUserId: 'user_123',
externalProductId: 'chapter_001',
externalOrderId: 'order_1001',
amount: 999,
currency: 'USD',
productName: 'Chapter 1',
successUrl: 'https://example.com/success',
cancelUrl: 'https://example.com/cancel',
});
const activity = await soledgic.activity.listWallet(userWallet.wallet.id, { limit: 10 });
console.log({
checkoutUrl: checkout.checkoutSession.checkoutUrl,
walletBalance: userWallet.wallet.availableBalance,
activityItems: activity.entries.length,
});Creator responses include linked-user fields when the public creator record is connected to a shared identity record. That linkage is visible through the public creator resource, but the user profile and ecosystem management routes stay internal.
await soledgic.kyc.submitBusiness({
businessType: 'llc',
legalName: 'Sole Society LLC',
taxIdType: 'ein',
taxIdLast4: '6789',
primaryContact: {
name: 'Alex Founder',
email: 'alex@solesociety.example',
},
businessAddress: {
line1: '100 Market St',
city: 'New York',
state: 'NY',
postalCode: '10001',
country: 'US',
},
documentEvidence: [{
documentType: 'ein_letter',
providerDocumentId: 'provider_doc_123',
}],
});
await soledgic.kyc.submitCreator({
participantId: 'creator_456',
legalName: 'Jane Creator',
email: 'jane@example.com',
dateOfBirth: '1990-01-01',
taxIdType: 'ssn',
taxIdLast4: '1234',
address: {
line1: '123 Main St',
city: 'New York',
state: 'NY',
postalCode: '10001',
country: 'US',
},
documentEvidence: [{
documentType: 'government_id',
providerDocumentId: 'provider_id_456',
}],
certifyTaxInfo: true,
});Version Pinning
The SDK can pin the request header you want to ship against.
const soledgic = new SoledgicClient({
apiKey: 'slk_test_your_api_key',
baseUrl: 'https://api.soledgic.com',
apiVersion: '2026-03-01',
});Treasury Helpers
const wallets = await soledgic.wallets.list({
ownerId: 'creator_456',
walletType: 'creator_earnings',
});
const holds = await soledgic.holds.list({ participantId: 'creator_456' });
const eligibility = await soledgic.payouts.getEligibility('creator_456');
const payout = await soledgic.payouts.request({
participantId: 'creator_456',
referenceId: 'payout_2026_03_12_001',
amount: 1500,
payoutMethod: 'bank',
});
const refundRequest = await soledgic.refundRequests.create({
saleReference: 'sale_123',
customerId: 'user_123',
reason: 'Customer requested refund',
idempotencyKey: 'refund_request_sale_123',
});
const approvedRefund = await soledgic.refundRequests.approve({
refundRequestId: refundRequest.refundRequest.id,
reviewedByActor: 'support',
});
const receipt = await soledgic.receipts.generate({
checkoutId: checkout.checkoutSession.id,
externalOrderId: 'order_1001',
});Buyer-facing apps create refund requests first. Platform support or admin tooling can approve, reject, or cancel the request; approval executes the Soledgic-routed refund. Existing server integrations can still call refunds.request() directly after their own approval workflow.
Sandbox Helpers
const completed = await soledgic.sandbox.completeCheckout({
checkoutSessionId: checkout.checkoutSession.id,
idempotencyKey: 'sandbox_complete_order_1001',
});
await soledgic.sandbox.sendScenario({
scenario: 'payout.failed',
idempotencyKey: 'sandbox_payout_failed_order_1001',
source: 'bridge_smoke',
runId: 'run_2026_05_13_001',
checkoutId: checkout.checkoutSession.id,
orderId: 'order_1001',
paymentId: 'pay_test_123',
amountCents: 2999,
reason: 'bank_account_closed',
});
const sandboxEvents = await soledgic.sandbox.listEvents({ limit: 10 });const cleanupPreview = await soledgic.sandbox.cleanup({
scope: 'run',
source: 'bridge_smoke',
runId: 'run_2026_05_13_001',
});
const runCleanup = await soledgic.sandbox.cleanup({
scope: 'run',
source: 'bridge_smoke',
runId: 'run_2026_05_13_001',
confirm: true,
});
const sandboxReset = await soledgic.sandbox.cleanup({
scope: 'sandbox_ledger',
confirm: true,
});Sandbox helpers require test API keys, never touch live ledgers, and do not call a payment processor. Sandbox payouts use the normal payout request helper with a test key and can emitpayout.created orpayout.failed events. Run-scoped cleanup removes one source/run; full sandbox ledger cleanup preserves webhook endpoint configuration.
Webhook Helpers
The TypeScript SDK includes webhook helpers for signature verification and payload parsing.
import SoledgicClient, {
assertSandboxCheckoutCompleted,
buildSandboxScenarioPayload,
buildTestWebhook,
} from '@soledgic/sdk';
const soledgic = new SoledgicClient({
apiKey: 'slk_test_your_api_key',
baseUrl: 'https://api.soledgic.com',
apiVersion: '2026-03-01',
});
const rawBody = await request.text();
const signature = request.headers.get('x-soledgic-signature') || '';
const webhookSecret = process.env.SOLEDGIC_WEBHOOK_SECRET!;
const isValid = await soledgic.webhooks.verifySignature(
rawBody,
signature,
webhookSecret,
);
const event = soledgic.webhooks.parseEvent(rawBody);
if (event.type === 'payout.executed') {
console.log('Payout completed:', event.data.payout_id);
}
const testWebhook = await buildTestWebhook({
secret: webhookSecret,
eventType: 'checkout.completed',
data: {
checkout_session_id: 'chk_test_123',
payment_id: 'pay_test_123',
amount_cents: 2999,
currency: 'USD',
sandbox_idempotency_key: 'sandbox_complete_order_1001',
metadata: { source: 'bridge_smoke', run_id: 'run_2026_05_13_001' },
},
});
const completed = assertSandboxCheckoutCompleted(testWebhook.rawBody);const payoutFailure = buildSandboxScenarioPayload({
scenario: 'payout.failed',
source: 'bridge_smoke',
runId: 'run_2026_05_13_001',
paymentId: 'pay_test_123',
participantId: 'creator_456',
amountCents: 2999,
reason: 'bank_account_closed',
});
const endpoints = await soledgic.webhooks.listEndpoints();
const deliveries = await soledgic.webhooks.listDeliveries({
eventType: 'checkout.completed',
checkoutId: checkout.checkoutSession.id,
orderId: 'order_1001',
paymentId: 'pay_test_123',
limit: 25,
});
const replayed = await soledgic.webhooks.replayDelivery(deliveries.data[0].id);
const queued = await soledgic.webhooks.retryDelivery(deliveries.data[0].id);
const rotated = await soledgic.webhooks.rotateSecret(endpoints.data[0].id);