Quickstart
Get a platform treasury flow running in a few requests.
First successful integration
A working sandbox integration should complete this path before moving to live mode:
- Create a business account and sandbox API key.
- Create a participant for the creator, seller, or contractor.
- Create a hosted checkout session and redirect a buyer to the returned checkout URL.
- Receive a checkout webhook and store the delivery id for deduplication.
- Generate a Soledgic receipt and store the receipt id or hosted URL.
- Inspect creator wallets and holds after the sale is booked.
- Check payout eligibility before creating any payout request.
- Create a buyer refund request and approve, reject, or cancel it through your support workflow.
Create an Account
Sign up for Soledgic and start in sandbox. Sandbox and live ledgers are isolated from each other; sandbox wallet funding uses simulated cards while live wallet funding uses hosted checkout.
Hosted Soledgic sandbox forms accept 4242 4242 4242 4242 for success and 4000 0000 0000 0002 for decline testing.
Get Your API Key
Grab your key from Developers → API Keys. Use slk_test_* while you are integrating.
The examples below use REST. If you prefer typed helpers after the first REST pass, install the public SDK:
npm install @soledgic/sdk@0.5.2
Create a Participant
Participants are the treasury identities that receive balances, holds, transfers, and payouts.
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
}'{
"success": true,
"participant": {
"id": "creator_456",
"account_id": "0e8e3fd8-7b7c-4f41-8b62-4a95a9fd6a30",
"display_name": "Jane Creator",
"email": "jane@example.com",
"default_split_percent": 80
}
}Create a Checkout Session
Checkouts book the commercial flow while the ledger records the downstream treasury state. Store your own order id in metadata so webhooks can be matched back to your platform.
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",
"metadata": {
"order_id": "order_1001"
}
}'{
"success": true,
"checkout_session": {
"id": "f86b98b8-23d0-42f3-a161-6b33f0d363de",
"mode": "session",
"checkout_url": "https://checkout.example/session/f86b98b8-23d0-42f3-a161-6b33f0d363de",
"status": "pending",
"amount": 2999,
"currency": "USD"
}
}Checkout sessions are USD-native today. Use USD for live ledger and wallet settlement.
In sandbox, you can finish the checkout without a real payment processor call. This records the test sale and queues the same webhook shape your app should handle in live mode.
curl -X POST https://api.soledgic.com/v1/sandbox/checkouts/f86b98b8-23d0-42f3-a161-6b33f0d363de/complete \
-H "x-api-key: slk_test_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"idempotency_key": "sandbox_complete_order_1001"
}'After completion, ask Soledgic to generate the financial receipt and store the returned receipt id or hosted URL.
curl -X POST https://api.soledgic.com/v1/receipts/generate \
-H "x-api-key: slk_test_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"checkout_id": "f86b98b8-23d0-42f3-a161-6b33f0d363de",
"external_order_id": "order_1001"
}'Inspect Wallet and Holds
Once payment settles, inspect the wallet objects for that owner and any active hold state separately.
curl -X GET "https://api.soledgic.com/v1/wallets?owner_id=creator_456&wallet_type=creator_earnings" \ -H "x-api-key: slk_test_YOUR_API_KEY"
curl -X GET "https://api.soledgic.com/v1/holds?participant_id=creator_456" \ -H "x-api-key: slk_test_YOUR_API_KEY"
Check Eligibility and Create a Payout
Payout creation is separate from hold release and balance inspection, which keeps the treasury flow explicit. Live payouts require active creator access, approved identity/KYC review, certified tax profile, bank payout setup, and sufficient available balance. Sandbox payouts use test keys, never call a bank rail, and emit the same payout webhook shape immediately so your app can prove the flow end to end.
curl -X GET "https://api.soledgic.com/v1/participants/creator_456/payout-eligibility" \ -H "x-api-key: slk_test_YOUR_API_KEY"
curl -X POST https://api.soledgic.com/v1/payouts \
-H "x-api-key: slk_test_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"participant_id": "creator_456",
"reference_id": "payout_2026_03_12_001",
"amount": 1500,
"payout_method": "bank"
}'Use a unique reference_id for payouts and transfers. Today that is the replay-safe key for those treasury writes. Live payout responses include the processor transfer id/status when the bank rail accepts the payout. To test a failed payout handler without changing ledger balances, send a sandbox payout.failed webhook from the sandbox webhook test endpoint.
Create and Review a Refund Request
Buyers should create refund requests, not execute refunds directly. Your platform can approve, reject, or cancel the request after support review. Approval executes the Soledgic-routed refund and emits the refund request lifecycle webhooks.
curl -X POST https://api.soledgic.com/v1/refund-requests \
-H "x-api-key: slk_test_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sale_reference": "checkout_order_1001",
"customer_id": "buyer_123",
"reason": "Buyer requested refund",
"idempotency_key": "refund_request_order_1001"
}'curl -X POST https://api.soledgic.com/v1/refund-requests/REFUND_REQUEST_ID/approve \
-H "x-api-key: slk_test_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"reviewed_by_actor": "support"
}'