SETSimple Easy Transactions
SET DocsAPI reference and complianceUpdated 2026-11-09
Browse: SET Merchant API

SET Merchant API · White-label onboarding

Start a white-label onboarding

POST/v1/onboarding_sessions

Key scope: write · Success: 201

A page you frame in your own app where one customer completes KYB or KYC: SET's verification form in your colours. The customer's details and documents go from the page to SET and on to the provider in the same request; you never see them and SET stores none.

Merchant key A merchant key verifies only its own business: type must be "business" and externalId is left out or "self" (409 merchant_single_customer).

Headers

Idempotency-Key string
Optional. The same key and body run once; a replay answers with Idempotent-Replayed: true. Kept 24 hours.

Body

externalId stringrequired
Your id for the customer (1–64 of A-Z a-z 0-9 _ . : -). A new id opens the customer; an existing one reuses it.
type "business" | "individual"required
KYB or KYC.
expiresInHours integer
1–168. Default 24.

Notes

  • url is shown once. A new session for the same customer replaces any open link.
  • The page has three steps: the terms (opened in a new tab), the form (one optional document for a business, up to 4 MB), and the status, from which a business can send further documents.
  • Event onboarding_session.submitted (session, customer and status, never the details). Verification then moves the customer as usual (customer.updated).
  • A person's identity document is not taken on the page; requirementsDue on the customer lists what is still needed.

Errors

  • 400 body_invalid
  • 400 type_invalid
  • 400 external_id_invalid
  • 400 expires_invalid
  • 409 customer_type_conflict
  • 409 customer_already_created
  • 409 customer_on_hosted_link
  • 401 api_key_required
  • 401 api_key_invalid
  • 401 api_key_wrong_mode
  • 403 scope_missing
  • 429 rate_limited

All codes: Errors.