> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sideshift.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Check an existing account and duplicate verified identity
> Read-only check scoped to the API key's integrator and environment. Supply exactly
one selector. Accounts outside your integration are indistinguishable from absent
accounts. Email matches the stored Connect email (lowercased), not a person's identity;
use externalId or sideshiftAccountId for accounts created with fallback emails.
Flags use stored verification data and may lag provider events. A new email cannot
detect a reused identity until verification links that account to an identity profile.
This endpoint does not reserve an identity, block account creation, or move funds.
No identity profile ID, bank details, tax ID, or other KYC data is returned.
## OpenAPI
````yaml /openapi/connect.yaml post /accounts/check
openapi: 3.1.0
info:
title: SideShift Connect
version: 1.0.0
description: >
Embed payment infrastructure directly into your platform. Create accounts
for your users, transfer funds in any direction, and drop in pre-built
payout and pay-in widgets — all through a single API.
## Setup Guide
### 1. Generate an API Key
Go to [Settings → Connect](https://app.sideshift.app/settings?tab=embed) and
click **Generate API Key**.
Copy it immediately — keys are only shown once.
- `sk_live_*` — Production (real money)
- `sk_test_*` — Sandbox (isolated balances, simulated payouts)
> **Never expose your API key in client-side code.** All API calls must be
made from your backend.
### 2. Add Allowed Domains
In Settings → Connect, add the domains where you'll embed widgets:
| Pattern | Matches |
|---------|---------|
| `app.example.com` | Exact match |
| `*.example.com` | All subdomains |
| `localhost` | Any port (auto-allowed for development) |
### 3. Create User Accounts
Every user who needs access to payments needs a SideShift Connect account:
```bash
curl -X POST https://app.sideshift.app/api/embed/accounts/create \
-H "x-api-key: sk_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{ "email": "jane@example.com", "name": "Jane Creator", "externalId": "usr_123" }'
```
Store the returned `sideshiftAccountId` — you'll need it for everything
else.
### 4. Generate a Widget Token
Tokens authenticate embedded widget sessions. Generate them server-side:
```bash
curl -X POST https://app.sideshift.app/api/embed/auth/token \
-H "x-api-key: sk_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{ "sideshiftAccountId": "acct_abc123", "widgetType": "both" }'
```
The response includes `widgetUrls.payout` and `widgetUrls.payin` — use these
as iframe sources.
### 5. Embed the Widget
**iframe (recommended):**
```html
```
The iframe is the most reliable method — it works in any framework, needs no
build tooling, and avoids dependency conflicts. The `allow="payment; camera;
microphone"` attribute is required for KYC/identity verification inside the
widget.
**White-label verification and withdrawals:**
The payout widget uses custom, theme-aware identity-verification,
withdrawal, fee, payout-method, history, and account-reset interfaces. It
does not render provider UI or SideShift product artwork. The KYC title,
progress rail, and withdrawal title can be removed independently with widget
URL query parameters:
```html
```
Labels use the same camel-case names shown above and should be URL-encoded.
### 6. Transfer Funds
Move money between your company and user accounts:
```bash
curl -X POST https://app.sideshift.app/api/embed/accounts/transfer \
-H "x-api-key: sk_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"toAccountId": "acct_abc123",
"amountCents": 5000,
"idempotencyKey": "payout-001",
"metadata": {
"obligationType": "creator_agreement",
"obligationReference": "agreement-001",
"description": "Approved payment for completed creator deliverable",
"approvalReference": "approval-001"
}
}'
```
### 7. Set Up Webhooks
Configure a webhook endpoint in Settings → Connect to receive
`transfer.completed`, `deposit.*`, and `withdrawal.*` events. Always verify
the signature:
```js
const crypto = require("crypto");
function verify(payload, timestamp, signature, secret) {
const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${payload}`).digest("hex");
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}
```
---
## Authentication
Include your API key in the `x-api-key` header on every request:
```
x-api-key: sk_live_your_key_here
```
Rotate your key anytime from Settings → Connect. The old key is invalidated
immediately.
## Sandbox
Use `sk_test_*` keys to test without moving real money. Sandbox balances,
credentials, provider resources, and webhook configuration are isolated from
live.
SideShift keeps the documented API contract (validation, error envelopes,
and response
shapes) stable where a sandbox operation is supported; this does **not**
mean every
production provider capability has sandbox parity.
### Sandbox behavior
- New connected accounts are provisioned through the payment provider's
official sandbox API and receive
sandbox `biz_*` provider IDs. Existing `sim_biz_*` accounts are migrated lazily the
next time an account or widget-token flow needs the provider account; integrations
should continue using the stable `sideshiftAccountId`.
- Pay-in widgets and hosted checkout support **card payments only** in
sandbox.
Alternative payment methods are production-only.
- Company → User, User → Company, and User → User transfers remain isolated
simulations
in SideShift's sandbox ledger.
- Payout, withdrawal, and bank-link actions are blocked in sandbox because
the payment provider does not
support payouts there. A stable API contract cannot make an unsupported provider rail
executable.
- Sandbox webhook events are delivered only to the separately configured
sandbox webhook.
SideShift never falls back to the live webhook URL or secret.
- Leaderboard and notification side effects are **not** triggered
- Invoice behavior is unchanged and invoices are explicitly outside this
sandbox
certification scope.
### Payout widget in sandbox
A token generated with a `sk_test_*` key uses the payment provider's sandbox
environment. The widget may
show safe account, verification, and balance status, but withdrawal,
bank-link, payout
destination, and payout submission controls are unavailable because the
provider does
not offer sandbox payouts.
**In production** with `sk_live_*` keys, transfers call the real payments
API, funds land in the creator's real wallet, and the balance + withdrawal
UI works normally.
**To verify sandbox transfers are working**, use the balance API — this is
the source of truth:
```bash
GET /accounts/balance?sideshiftAccountId=ACCOUNT_ID
```
Use `walletBalanceCents` and `transactions` to verify SideShift
sandbox-ledger transfers.
`totalBalanceCents` combines the SideShift wallet and provider
withdrawal-ready layers;
it is not the authoritative value for sandbox transfer assertions while
provider payouts
are unsupported.
### Testing checklist
1. Generate `sk_test_*` key and store securely
2. Create at least two sandbox accounts
3. Test all three transfer directions (company→user, user→company,
user→user)
4. Verify balances via the balance API after each transfer
5. Replay a transfer with the same `idempotencyKey` — confirm no duplicate
6. Configure a sandbox webhook, then confirm delivery and signature
verification; verify
that no event falls back to the live webhook
7. Trigger error cases (insufficient balance, invalid account) and verify
your handling
8. Test widget token generation, card-only pay-in/checkout, and the blocked
payout UI
### Go-live checklist
Before switching to `sk_live_*`:
1. Store your live API key in a production secrets manager
2. Confirm production domains in Settings → Connect (remove dev wildcards)
3. Verify webhook endpoint uses HTTPS and validates signatures
4. Add retry handling with idempotency keys in your backend
5. Attach commercial evidence metadata to every transfer
6. Run a small live test (e.g. $0.50 transfer) before full volume
## Idempotency
Always include an `idempotencyKey` on transfer requests. Replaying a request
with the same key returns the original successful result instead of creating
a duplicate.
## Rate Limits
| Limit | Default | Scope |
|-------|---------|-------|
| Requests | 100 per minute | per API key mode (sandbox and live are counted
separately) |
| Widget tokens | 100 per hour | per API key mode |
| Transfers | 1,000 per UTC day | per API key mode, reserved atomically with
each transfer |
| Daily transfer amount | none unless configured | `dailyTransferLimitCents`
on your integration |
Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and
`X-RateLimit-Reset` (Unix seconds).
Exceeding a limit returns `429` with error code `RATE_LIMITED`; the message
states when to retry.
## Base URL
`https://app.sideshift.app/api/embed`
contact:
name: SideShift Support
url: https://app.sideshift.app
servers:
- url: https://app.sideshift.app/api/embed
description: Production / Sandbox (determined by API key prefix)
security:
- apiKeyAuth: []
tags:
- name: Configuration
description: Brand-owned API settings with separate live and sandbox preferences.
- name: Accounts
description: >-
Create and manage user accounts. Each user gets a `sideshiftAccountId` and
a wallet for receiving and sending funds.
- name: Verifications
description: >-
Read identity verification status and required actions for connected
accounts.
- name: Transfers
description: >-
Move funds between your company and user accounts. Supports company→user,
user→company, and user→user directions.
- name: Tokens
description: >-
Generate short-lived access tokens that authenticate embedded widget
sessions.
- name: Domains
description: Read and update the domains your embedded widgets are allowed to load on.
- name: Checkout
description: >-
Create public hosted checkout links that settle into your SideShift
wallet.
- name: Webhooks
description: >
Receive real-time event notifications when transfers, deposits, and
withdrawals complete or fail. Configure endpoints in Settings → Connect.
**Available events:** `deposit.pending`, `deposit.confirmed`,
`deposit.failed`, `transfer.completed`, `withdrawal.created`,
`withdrawal.updated`, `withdrawal.completed`, `withdrawal.failed`,
`account.risk_flagged`
`withdrawal.completed` and `withdrawal.failed` are derived aliases of
`withdrawal.updated`, filtered to `status === "completed"` and to `status`
in (`failed`, `denied`) respectively. Subscribe to the pair if you only
want the terminal outcome; subscribe to `withdrawal.updated` for the full
lifecycle (`requested → awaiting_payment → in_transit → completed | failed
| canceled | denied`).
An endpoint registered without an explicit `events` array is subscribed to
`deposit.pending`, `deposit.confirmed`, `deposit.failed`,
`withdrawal.created`, `withdrawal.completed`, `withdrawal.failed` and
`transfer.completed`. A later config save that omits `events` keeps the
subscription list you last set.
Every delivery carries `X-Sideshift-Signature` (HMAC-SHA256, hex, of
`.` using your endpoint secret),
`X-Sideshift-Timestamp` (Unix seconds) and `X-Sideshift-Event-Id` (the
same `id` as the body, for deduplication). A delivery is attempted up to
three times in one dispatch, waiting one second and then two seconds
between attempts, with a ten-second timeout per attempt; a `4xx` response
other than `429` is not retried. Anything that still failed can be re-sent
with `POST /webhooks/{eventId}/replay`, and every attempt is visible in
`GET /webhook-logs`. Sandbox keys deliver only to the sandbox endpoint and
secret; live keys only to the live ones.
paths:
/accounts/check:
post:
tags:
- Accounts
summary: Check an existing account and duplicate verified identity
description: >
Read-only check scoped to the API key's integrator and environment.
Supply exactly
one selector. Accounts outside your integration are indistinguishable
from absent
accounts. Email matches the stored Connect email (lowercased), not a
person's identity;
use externalId or sideshiftAccountId for accounts created with fallback
emails.
Flags use stored verification data and may lag provider events. A new
email cannot
detect a reused identity until verification links that account to an
identity profile.
This endpoint does not reserve an identity, block account creation, or
move funds.
No identity profile ID, bank details, tax ID, or other KYC data is
returned.
operationId: checkConnectAccount
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
sideshiftAccountId:
type: string
minLength: 1
maxLength: 200
pattern: ^[^/]+$
externalId:
type: string
minLength: 1
maxLength: 200
email:
type: string
format: email
maxLength: 254
oneOf:
- required:
- sideshiftAccountId
- required:
- externalId
- required:
- email
example:
externalId: earn_user_123
responses:
'200':
description: Stored account check; null means unknown, never an approval
headers:
Cache-Control:
schema:
type: string
const: no-store
content:
application/json:
schema:
type: object
required:
- success
- data
properties:
success:
type: boolean
const: true
data:
type: object
additionalProperties: false
required:
- exists
- isKycVerified
- hasDuplicateVerifiedIdentity
- geoRestricted
- source
properties:
exists:
type: boolean
description: >-
At least one managed account matches within your
integration and environment.
isKycVerified:
type: boolean
description: >-
At least one match has a stored verified stamp and no
reset, rejection, or non-approved current profile
status. An approved identity remains verified during
an account information request. Always false in
sandbox.
hasDuplicateVerifiedIdentity:
type:
- boolean
- 'null'
description: >-
Another account in your integration has completed
verification with the same stored identity profile.
Null for absent accounts, missing identity links,
concurrent removal, or sandbox. False is not proof of
a unique person.
geoRestricted:
type:
- boolean
- 'null'
description: >-
Stored KYC country matches the payment-region
restriction list, honoring your company's override.
Null for absent accounts, unavailable country, or
sandbox. Does not evaluate VPN or end-user IP and is
not a payout eligibility verdict.
source:
type: string
const: stored_verification
example:
success: true
data:
exists: true
isKycVerified: true
hasDuplicateVerifiedIdentity: false
geoRestricted: false
source: stored_verification
'400':
description: Invalid body or more than one selector
'401':
description: Missing or invalid API key
'403':
description: Integration or origin not authorized
'429':
description: Connect API rate limit exceeded
'500':
description: Check unavailable; do not interpret as no match
'503':
description: >-
Too many matching accounts to check safely; use a more specific
selector or contact support
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
Your SideShift Connect API key (`sk_live_*` or `sk_test_*`). Generate
from Settings → Connect.
````