Marketplace & Connect

The Connect API lets a platform (marketplace, services platform, multi-vendor SaaS…) create one Sangho account per seller and automatically split every payment between the platform and that seller. Sangho stays the sole custodian of funds and the sole party responsible for KYC — the platform never collects or stores any identity document.

Attention

Connect is restricted to Apps with Platform Partner status, granted manually by Sangho after a request made from your dashboard. A valid secret key is not enough: an ordinary merchant App gets 403 PLATFORM_PARTNER_REQUIRED on every route below. See Error codes — Authorization.

1. Create a seller account

Creation is idempotent on external_id (your own seller identifier): calling create again with the same value returns the same account. A claim_token is only returned on the initial creation — send it to the seller (Sangho claim link), never store or log it. If it’s lost or expired, reissue one (the old one is invalidated).

2. Sangho-hosted KYC

Once the account is claimed by the seller, open a hosted onboarding session (kyc-session) and redirect them to its url (valid for about an hour). The account moves to active and charges_enabled/payouts_enabled once KYC is approved on Sangho’s side — no further action needed from the platform.

Status	Meaning
pending_claim	Account created, waiting for the seller to click their claim link
linked	Claimed by the seller, KYC not completed yet
active	KYC approved — can charge and withdraw
restricted	Charges/payouts cut off (Sangho review in progress)
disabled	Account disabled

3. Split a payment (the `connect` block)

Add a connect block to a regular Checkout Session creation call — there is no separate endpoint to create a Connect payment, it’s born with the session.

Field	Description
account	Beneficiary account (acct_xxx), linked and charges_enabled
mode	escrow (funds held until release) or instant (paid out on charge) — default escrow
commission	Platform's commission, withheld at release (escrow) or at charge (instant)
reserve_rate	Share (0–1) of the shipping fee held back as a guarantee reserve
external_reference	Your own order reference, searchable, returned in connect_payment

The session’s response carries connect_payment (id cpay_xxx): the shipping fee (shipping_amount) is available to the seller as soon as the charge succeeds, the rest sits in held until release (escrow mode).

4. Release, refund, freeze

Action	Effect	Idempotency Key
release	Releases held funds to the seller's available balance (withholds the commission)	Required
refund	Refunds all or part, before or after release	Required
freeze / unfreeze	Blocks/unblocks a payment during a dispute — already idempotent server-side	Optional

Note

release and refund require a stable Idempotency Key (e.g. release-{order_id}): a retry must never duplicate the financial operation.

5. Balance and payouts

balance returns the available/held/frozen/reserve buckets (amounts as decimal strings — convert with a decimal library, never parseFloat for comparisons). payouts.create triggers a withdrawal to the seller’s destination.

SDK availability

Connect is available in the Node.js, Python and PHP SDKs.

Full flow

javascript

import Sangho, { SanghoPlatformPartnerRequiredError } from '@sanghosdk/js';
const sangho = new Sangho(process.env.SANGHO_SECRET_KEY);


try {
  // 1. Create the seller account (idempotent on external_id)
  const account = await sangho.connect.accounts.create(
    { external_id: 'seller-42', email: 'ada@example.com', business_name: "Ada's Shop" },
    { idempotencyKey: 'connect-account-seller-42' }
  );
  // account.claim_token -> send to the seller by email, never store or log it


  // 2. Once claimed by the seller: hosted KYC
  const session = await sangho.connect.accounts.createKycSession(account.id, {
    return_url: 'https://myplatform.com/sellers/kyc/return',
  });
  // redirect the seller to session.url


  // 3. Split payment (inside a regular Checkout Session)
  const checkout = await sangho.checkoutSessions.create({
    line_items: [{ price: 'price_xxx', quantity: 1 }],
    connect: {
      account: account.id,
      mode: 'escrow',
      commission: 500,
      reserve_rate: 0.1,
      external_reference: 'order-1042',
    },
  });


  // 4. Once delivery is confirmed: release the funds to the seller
  await sangho.connect.payments.release(checkout.connect_payment, {
    idempotencyKey: 'release-order-1042',
  });
} catch (err) {
  if (err instanceof SanghoPlatformPartnerRequiredError) {
    // This App doesn't have Platform Partner status (yet).
  }
}