> ## 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.
# Opt the brand into or out of multi-currency
> Accepts only a boolean enabled. Company and environment come from the API key.
Live and sandbox preferences are separate. Repeating a PATCH is safe.
An enabled preference does not override rollout availability or payout permissions.
Opt-out blocks new estimates, quotes, and conversions while preserving access to funded
foreign balances and recovery of pending conversions. No automatic currency conversion occurs.
## OpenAPI
````yaml /openapi/connect.yaml patch /settings/currencies
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:
/settings/currencies:
patch:
tags:
- Configuration
summary: Opt the brand into or out of multi-currency
description: >
Accepts only a boolean enabled. Company and environment come from the
API key.
Live and sandbox preferences are separate. Repeating a PATCH is safe.
An enabled preference does not override rollout availability or payout
permissions.
Opt-out blocks new estimates, quotes, and conversions while preserving
access to funded
foreign balances and recovery of pending conversions. No automatic
currency conversion occurs.
operationId: updateConnectCurrencySettings
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- enabled
properties:
enabled:
type: boolean
examples:
optIn:
value:
enabled: true
optOut:
value:
enabled: false
responses:
'200':
description: Saved preference and effective availability; inspect data.enabled
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
const: true
data:
$ref: '#/components/schemas/ConnectCurrencySettings'
'400':
description: Invalid body, unknown fields, or a non-boolean enabled value
'401':
description: Invalid or missing Connect API key
'403':
description: Connect access denied
components:
schemas:
ConnectCurrencySettings:
type: object
required:
- environment
- multiCurrencyEnabled
- rolloutAvailable
- enabled
properties:
environment:
type: string
enum:
- live
- sandbox
multiCurrencyEnabled:
type: boolean
default: false
description: Saved brand preference for this API key environment
rolloutAvailable:
type: boolean
description: Platform rollout availability; cannot be set by the brand
enabled:
type: boolean
description: Preference AND rollout availability AND existing payout permission
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.
````