> ## 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.
# Read the account's guardian declaration
> Returns the stated guardian relationship owned by your company and the current
stored identity and payout-method summary. A declaration is not proof of legal
guardianship or successful KYC. Current provider projections may lag updates.
The identity summary is returned only when its stored verification ID matches
the declaration's latest verification ID. Both fields are null if an accessible
account has no declaration owned by your company. Another linked company cannot
read the owner's declaration. Uses the SideShift account ID. Sandbox requests,
inaccessible accounts, and accounts without a provider account return 404.
## OpenAPI
````yaml /openapi/connect.yaml get /accounts/{id}/guardian
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/{id}/guardian:
get:
tags:
- Verifications
summary: Read the account's guardian declaration
description: >
Returns the stated guardian relationship owned by your company and the
current
stored identity and payout-method summary. A declaration is not proof of
legal
guardianship or successful KYC. Current provider projections may lag
updates.
The identity summary is returned only when its stored verification ID
matches
the declaration's latest verification ID. Both fields are null if an
accessible
account has no declaration owned by your company. Another linked company
cannot
read the owner's declaration. Uses the SideShift account ID. Sandbox
requests,
inaccessible accounts, and accounts without a provider account return
404.
operationId: getGuardianDeclaration
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Guardian record retrieved; each field is null when unavailable
content:
application/json:
schema:
type: object
required:
- success
- data
properties:
success:
type: boolean
const: true
data:
type: object
required:
- guardian
properties:
guardian:
type: object
required:
- declaration
- currentIdentityAndDestination
properties:
declaration:
type:
- object
- 'null'
properties:
id:
type: string
format: uuid
companyId:
type: string
creatorId:
type: string
sandbox:
type: boolean
provider:
type: string
providerAccountId:
type: string
providerVerificationId:
type:
- string
- 'null'
relationship:
type: string
enum:
- parent
- legal_guardian
creatorFirstName:
type: string
creatorLastName:
type: string
creatorDateOfBirth:
type: string
format: date
guardianFirstName:
type: string
guardianLastName:
type: string
attestationVersion:
type: string
attestedAt:
type: string
format: date-time
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
writtenByKind:
type: string
runId:
type:
- string
- 'null'
currentIdentityAndDestination:
type:
- object
- 'null'
properties:
firstName:
type:
- string
- 'null'
lastName:
type:
- string
- 'null'
verified:
type:
- boolean
- 'null'
verificationId:
type:
- string
- 'null'
payoutMethodId:
type:
- string
- 'null'
payoutMethodType:
type:
- string
- 'null'
payoutMethodCountry:
type:
- string
- 'null'
payoutMethodNickname:
type:
- string
- 'null'
payoutMethodPayerName:
type:
- string
- 'null'
'401':
description: Invalid API key
'404':
description: Account is unavailable or not accessible to this integration
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.
````