Getting Started

Prerequisites

Before you begin integration, ensure you have the following:

Requirement	Description
Admin invitation	An OpenSylo admin must invite your marketplace. You'll receive an email with a registration link.
Registration complete	Complete the multi-step onboarding (business info, phone verification, signatory details, documents).
OAuth credentials	After registration, your `client_id` and `client_secret` are available in the dashboard. The secret is shown only once at creation — store it securely.
Redirect URI(s)	One or more callback URLs registered with OpenSylo where authorization codes will be sent.
Webhook endpoint (optional)	An HTTPS endpoint on your server to receive loan lifecycle events from OpenSylo.
Webhook secret (optional)	An API secret configured on your marketplace for signing inbound webhooks you send to OpenSylo.

Step 1 — Accept the Invitation

You will receive an email from OpenSylo with a registration link:

https://opensylo.com/marketplace/register?token=inv_<token>

The invitation token is valid for 7 days and can only be used once. Complete the registration form to create your marketplace account and activate your credentials.

Use the dashboard login endpoint to obtain a JWT:

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "tokenType": "Bearer",
  "expiresIn": 86400,
  "marketplace": {
    "id": "uuid",
    "platformName": "yourmarketplace",
    "displayName": "Your Marketplace",
    "status": "ACTIVE"
  },
  "user": {
    "id": "uuid",
    "email": "tech@yourmarketplace.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "role": "OWNER"
  }
}

The accessToken is a JWT valid for 24 hours. Use it in the Authorization: Bearer header for all dashboard endpoints.

Step 3 — View Your OAuth Credentials

Response:

{
  "clientId": "yourmarketplace_client_a1b2c3d4",
  "clientSecretMasked": "cs_secret_***...c3d4",
  "redirectUris": ["https://yourmarketplace.com/oauth/callback"],
  "allowedScopes": [
    "data.share.sales",
    "data.share.fulfillment",
    "data.share.payouts",
    "data.share.risk",
    "data.share.profile",
    "credit.score.read",
    "repayment.report"
  ],
  "authorizationUrl": "https://api.opensylo.com/oauth/authorize",
  "tokenUrl": "https://api.opensylo.com/oauth/token",
  "dataIngestionUrl": "https://api.opensylo.com/api/marketplace/data/merchant"
}

The client secret is masked in this response. It was only shown in full when initially created (during the admin invitation) or after regeneration.

Step 4 — Regenerate Secret (If Needed)

If you lose your client secret, regenerate it:

Response:

{
  "success": true,
  "message": "Client secret regenerated successfully. Store it securely - it will not be shown again.",
  "clientSecret": "cs_secret_<new_secret_hex>",
  "regeneratedAt": "2026-01-29T12:00:00.000Z"
}

The new secret is shown only once in this response. The old secret is immediately invalidated. Existing OAuth access/refresh tokens remain valid.

Authentication Summary

Method	Used For	How to Obtain	Lifetime
Dashboard JWT	Dashboard endpoints (`/marketplace-dashboard/*`)	`POST /marketplace-dashboard/login`	24 hours
OAuth Access Token	Data and Loan API endpoints	OAuth Authorization Code + PKCE flow	1 hour
OAuth Refresh Token	Refreshing expired access tokens	Returned with initial token exchange	30 days
Webhook Signature	Inbound webhooks (`/api/v1/webhooks/marketplace/*`)	HMAC-SHA256 using your API secret	Per-request

Available Scopes

When requesting OAuth authorization, include the scopes your integration needs:

Scope	Description
`data.share.sales`	Share sales and GMV data with OpenSylo
`data.share.fulfillment`	Share order fulfillment and delivery metrics
`data.share.payouts`	Share payout and cash flow information
`data.share.risk`	Share account status and risk information
`data.share.profile`	Share merchant business profile information
`credit.score.read`	Access credit scores calculated by OpenSylo
`repayment.report`	Report loan repayments collected from merchant sales

Next Steps

Implement the OAuth 2.0 flow to obtain merchant consent and tokens

Submit merchant data via the Data Ingestion API

Set up webhook handlers for loan lifecycle events

Use the Loan API to query active loans and validate deductions

Test everything in the sandbox environment before going live

Prerequisites#

Step 1 — Accept the Invitation#

Step 2 — Login to the Dashboard#

Step 3 — View Your OAuth Credentials#

Step 4 — Regenerate Secret (If Needed)#

Authentication Summary#

Available Scopes#

Next Steps#

Prerequisites

Step 1 — Accept the Invitation

Step 2 — Login to the Dashboard

Step 3 — View Your OAuth Credentials

Step 4 — Regenerate Secret (If Needed)

Authentication Summary

Available Scopes

Next Steps