API Examples

Copy-paste curl commands for the common resource-first integration path. Replace slk_test_YOUR_KEY with your API key.

First Integration

POST/v1/participants

Register a creator, seller, or contractor on your platform. This creates the treasury anchor used by checkouts, wallets, holds, and payouts.

Request

curl -X POST https://api.soledgic.com/v1/participants \
  -H "x-api-key: slk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "participant_id": "creator_001",
    "display_name": "Jane Doe",
    "email": "jane@example.com",
    "default_split_percent": 80
  }'

Response

{
  "success": true,
  "participant": {
    "id": "creator_001",
    "account_id": "0e8e3fd8-7b7c-4f41-8b62-4a95a9fd6a30",
    "display_name": "Jane Doe",
    "email": "jane@example.com",
    "default_split_percent": 80
  },
  "request_id": "req_abc123"
}

POST/v1/checkout-sessions

Create a hosted checkout session for a participant sale. Redirect the buyer to the returned checkout_url.

Request

curl -X POST https://api.soledgic.com/v1/checkout-sessions \
  -H "x-api-key: slk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "participant_id": "creator_001",
    "amount": 3500,
    "currency": "USD",
    "product_name": "Digital product",
    "success_url": "https://yoursite.com/success",
    "cancel_url": "https://yoursite.com/cancel",
    "idempotency_key": "checkout_order_1001",
    "metadata": {
      "order_id": "order_1001"
    }
  }'

Response

{
  "success": true,
  "checkout_session": {
    "id": "chk_abc123",
    "mode": "session",
    "checkout_url": "https://checkout.example/session/chk_abc123",
    "status": "pending",
    "amount": 3500,
    "currency": "USD"
  },
  "request_id": "req_def456"
}

GET/v1/participants/{id}

Retrieve a participant treasury snapshot after checkout completion or webhook processing.

Request

curl https://api.soledgic.com/v1/participants/creator_001 \
  -H "x-api-key: slk_test_YOUR_KEY"

Response

{
  "participant_id": "creator_001",
  "display_name": "Jane Doe",
  "balance": 15000,
  "held_balance": 2500,
  "available_balance": 12500,
  "currency": "USD",
  "request_id": "req_ghi789"
}

Wallets and Holds

GET/v1/wallets

List wallet objects scoped to a participant or owner. Creator earnings wallets are created through participant and checkout flows.

Request

curl "https://api.soledgic.com/v1/wallets?owner_id=creator_001&wallet_type=creator_earnings" \
  -H "x-api-key: slk_test_YOUR_KEY"

Response

{
  "wallets": [
    {
      "id": "wallet_uuid",
      "owner_id": "creator_001",
      "wallet_type": "creator_earnings",
      "balance": 15000,
      "available_balance": 12500,
      "currency": "USD",
      "is_active": true
    }
  ],
  "request_id": "req_jkl012"
}

POST/v1/wallets/{wallet_id}/topups

Top up a wallet when that wallet type supports external funding. Consumer credit wallets support this flow; creator earnings are funded by sales.

Request

curl -X POST https://api.soledgic.com/v1/wallets/wallet_uuid/topups \
  -H "x-api-key: slk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "reference_id": "dep_001",
    "description": "Wallet top-up"
  }'

Response

{
  "success": true,
  "transaction_id": "txn_uuid",
  "balance": 3000,
  "request_id": "req_mno345"
}

GET/v1/holds

Inspect held funds before release or payout decisions.

Request

curl "https://api.soledgic.com/v1/holds?participant_id=creator_001" \
  -H "x-api-key: slk_test_YOUR_KEY"

Response

{
  "holds": [
    {
      "id": "hold_uuid",
      "participant_id": "creator_001",
      "amount": 2500,
      "status": "active",
      "ready_for_release": false
    }
  ],
  "request_id": "req_pqr678"
}

POST/v1/holds/{hold_id}/release

Release a held-funds entry once your platform policy allows it.

Request

curl -X POST https://api.soledgic.com/v1/holds/hold_uuid/release \
  -H "x-api-key: slk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "execute_transfer": true
  }'

Response

{
  "success": true,
  "hold_id": "hold_uuid",
  "status": "released",
  "request_id": "req_stu901"
}

Payout Readiness

GET/v1/participants/{participant_id}/payout-eligibility

Check whether the participant can request payouts. Eligibility depends on active creator access, approved identity/KYC review, certified tax profile, bank payout setup, and available balance.

Request

curl https://api.soledgic.com/v1/participants/creator_001/payout-eligibility \
  -H "x-api-key: slk_test_YOUR_KEY"

Response

{
  "participant_id": "creator_001",
  "eligible": false,
  "blocked_reasons": [
    "kyc_under_review",
    "tax_profile_not_certified",
    "bank_payout_setup_missing"
  ],
  "request_id": "req_vwx234"
}

POST/v1/payouts

Create a payout only after eligibility is true. Reuse the same reference_id when retrying the same payout request.

Request

curl -X POST https://api.soledgic.com/v1/payouts \
  -H "x-api-key: slk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "participant_id": "creator_001",
    "reference_id": "payout_2026_05_10_001",
    "amount": 1500,
    "payout_method": "bank"
  }'

Response

{
  "success": true,
  "payout": {
    "id": "payout_uuid",
    "transaction_id": "payout_uuid",
    "gross_amount_cents": 1500,
    "net_amount_cents": 1500,
    "status": "completed",
    "simulated": true,
    "payout_rail": "sandbox"
  },
  "request_id": "req_yza567"
}

Refunds

POST/v1/refund-requests

Use this from your server when a buyer clicks Request refund. It creates review state only; it does not move money.

Request

curl -X POST https://api.soledgic.com/v1/refund-requests \
  -H "x-api-key: slk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sale_reference": "order_1001",
    "customer_id": "buyer_123",
    "reason": "Item did not match the description",
    "idempotency_key": "refund_request_order_1001_001"
  }'

Response

{
  "success": true,
  "refund_request": {
    "id": "refund_request_uuid",
    "sale_reference": "order_1001",
    "status": "pending",
    "amount_cents": 2500
  }
}

POST/v1/refunds

Use this after support approves a refund. Soledgic routes the refund and records the ledger reversal.

Request

curl -X POST https://api.soledgic.com/v1/refunds \
  -H "x-api-key: slk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "original_sale_reference": "order_1001",
    "reason": "Customer requested refund",
    "amount": 2500,
    "idempotency_key": "refund_order_1001_partial_001"
  }'

Response

{
  "success": true,
  "refund_id": "refund_uuid",
  "amount": 2500,
  "status": "completed",
  "request_id": "req_bcd890"
}

Reports

GET/v1/trial-balance

Retrieve debit/credit balances for all accounts.

Request

curl https://api.soledgic.com/v1/trial-balance \
  -H "x-api-key: slk_test_YOUR_KEY"

Response

{
  "accounts": [
    {
      "name": "Cash",
      "account_type": "asset",
      "debit_balance": 50000,
      "credit_balance": 0
    },
    {
      "name": "Creator Balance (creator_001)",
      "account_type": "liability",
      "debit_balance": 0,
      "credit_balance": 15000
    }
  ],
  "total_debits": 50000,
  "total_credits": 50000,
  "balanced": true,
  "request_id": "req_efg123"
}