> ## 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.
# Create hosted checkout session
> Create a public SideShift-hosted checkout link for your embed-enabled SideShift account.
Redirect any payer to `data.url`. The hosted page matches SideShift's invoice payment UI and renders a SideShift checkout. When payment succeeds, the net amount is credited to your SideShift wallet and `deposit.confirmed` is emitted with `metadata.source = "connect_hosted_checkout"`.
To embed checkout inside your own app, create the session from your backend with your SideShift API key, then render `data.embedUrl` (or `data.widgetUrl`) in an iframe. Do not expose your API key in browser code.
The embedded checkout posts a `sideshift.checkout.completed` message to the parent window after SideShift verifies payment.
## OpenAPI
````yaml /openapi/connect.yaml post /checkout/sessions
openapi: 3.0.4
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 or pass them to the SDK.
### 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.
**npm SDK (alternative):**
```jsx
import { SideShiftPayout } from '@sideshiftapp/connect/react';
console.log('Withdrew', data.amountCents)}
onSessionExpired={() => refreshToken()}
/>
```
The SDK is a thin wrapper around the same iframe — you get typed props,
auto-resize, and event callbacks. Also available as
`@sideshiftapp/connect/vanilla`.
**iOS (SwiftUI):**
```swift
SideShiftConnect.configure(apiKey: "sk_live_YOUR_KEY")
SideShiftPayoutView(accountId: "acct_abc123", currency: "USD")
```
The iOS SDK manages tokens internally — no server-side token generation
needed.
### 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 are
fully isolated from live. Webhooks still fire so you can validate your full
pipeline. All API endpoints behave identically (same validation, same error
codes, same response shapes).
### Sandbox behavior
- `paymentAccountId` values are prefixed with `sim_biz_*` (simulated)
- Company → User transfers are simulated — no real payout is executed, but
the internal ledger is updated normally
- User → Company and User → User transfers work identically to production
- Webhook events are delivered to your configured endpoint
- Leaderboard and notification side effects are **not** triggered
### Payout widget in sandbox
When a widget token is generated with a `sk_test_*` key, the payout widget
automatically uses SideShift's sandbox payout environment. No additional
configuration is required.
> **Important:** The payout widget shows "Pending Balance from your
platform" instead of the actual balance in sandbox mode. This is expected.
When you transfer funds with a `sk_test_*` key, the sandbox wallet is
credited correctly on the internal ledger. However, the payout widget's
withdrawal UI cannot display the real balance because the company ID is
simulated (`sim_biz_*`) and the widget relies on the real payments
infrastructure to resolve balances.
- The `passedInBalance` field (if set) appears as a display-only "Pending
Balance" label
- The withdrawal flow (bank account linking, payout initiation) is not fully
functional in sandbox
**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
```
The `balanceCents` and `transactions` in the response accurately reflect all
sandbox transfers.
### 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. Confirm webhook arrives and signature verification passes
7. Trigger error cases (insufficient balance, invalid account) and verify
your handling
8. Test widget token generation and embedding
### 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
| Endpoint | Limit |
|----------|-------|
| Account creation | 100/hour |
| Token generation | 30/min per account |
| Transfers | 60/min (configurable) |
| General | 100/min |
Exceeding limits returns `429` with a `Retry-After` header.
## 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: 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: 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`, `account.risk_flagged`
`withdrawal.completed` is a derived alias of `withdrawal.updated` filtered
to `status === "completed"`. Subscribe to it if you only want the
terminal-success event; subscribe to `withdrawal.updated` for the full
lifecycle (`requested → awaiting_payment → in_transit → completed | failed
| canceled | denied`).
All webhook deliveries include `x-sideshift-signature` and
`x-sideshift-timestamp` headers for signature verification. Non-2xx
responses are retried with exponential backoff (up to 5 attempts).
Webhooks fire in both sandbox and production modes.
paths:
/checkout/sessions:
post:
tags:
- Checkout
summary: Create hosted checkout session
description: >
Create a public SideShift-hosted checkout link for your embed-enabled
SideShift account.
Redirect any payer to `data.url`. The hosted page matches SideShift's
invoice payment UI and renders a SideShift checkout. When payment
succeeds, the net amount is credited to your SideShift wallet and
`deposit.confirmed` is emitted with `metadata.source =
"connect_hosted_checkout"`.
To embed checkout inside your own app, create the session from your
backend with your SideShift API key, then render `data.embedUrl` (or
`data.widgetUrl`) in an iframe. Do not expose your API key in browser
code.
The embedded checkout posts a `sideshift.checkout.completed` message to
the parent window after SideShift verifies payment.
operationId: createHostedCheckoutSession
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- amountCents
properties:
sideshiftAccountId:
type: string
description: >-
Optional destination override. Defaults to the API-key
company's own SideShift wallet. If supplied, the account
must belong to or be linked to your Connect integration.
example: acct_a1b2c3d4e5f6
amountCents:
type: integer
minimum: 100
description: Net amount to credit to the wallet, in cents
example: 5000
description:
type: string
description: Checkout description shown to the payer
example: Premium creator bundle
customerEmail:
type: string
format: email
description: >-
Optional payer email to prefill in checkout. The payer can
still edit it.
customerName:
type: string
description: Optional payer name for your own reconciliation
successUrl:
type: string
format: uri
description: Optional URL to redirect to after SideShift verifies payment
cancelUrl:
type: string
format: uri
description: Optional URL for the hosted page cancel link
paymentMethodType:
type: string
enum:
- card
- link
- apple_pay
- google_pay
- amazon_pay
- cashapp
- paypal
- venmo
- crypto
- coinbase
- us_bank_account
- us_bank_transfer
- eu_bank_transfer
- gb_bank_transfer
- au_bank_transfer
- pay_by_bank
- klarna
- affirm
- afterpay_clearpay
description: Payment method used for fee calculation. Defaults to `card`.
example: card
allowedPaymentMethods:
type: array
description: >-
Optional payment methods to restrict the hosted checkout to.
Omit this field to use SideShift's default checkout methods.
items:
type: string
enum:
- card
- link
- apple_pay
- google_pay
- amazon_pay
- cashapp
- paypal
- venmo
- crypto
- coinbase
- us_bank_account
- us_bank_transfer
- eu_bank_transfer
- gb_bank_transfer
- au_bank_transfer
- pay_by_bank
- klarna
- affirm
- afterpay_clearpay
example:
- card
- apple_pay
- google_pay
- paypal
metadata:
type: object
additionalProperties: true
description: Up to 50 key/value pairs returned in deposit webhooks
example:
amountCents: 5000
description: Premium creator bundle
customerEmail: buyer@example.com
successUrl: https://example.com/checkout/success
cancelUrl: https://example.com/cart
metadata:
orderId: order_123
responses:
'200':
description: Hosted checkout session created
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
$ref: '#/components/schemas/HostedCheckoutSession'
example:
success: true
data:
id: ck_abc123
status: open
sideshiftAccountId: acct_a1b2c3d4e5f6
amountCents: 5000
feeCents: 185
totalChargedCents: 5185
currency: usd
paymentMethodType: card
allowedPaymentMethods:
- card
- apple_pay
- google_pay
- paypal
url: https://app.sideshift.app/connect/checkout/ck_abc123
hostedUrl: https://app.sideshift.app/connect/checkout/ck_abc123
embedUrl: https://app.sideshift.app/connect/checkout/ck_abc123/embed
widgetUrl: https://app.sideshift.app/connect/checkout/ck_abc123/embed
checkoutConfigId: chk_abc123
sandbox: false
'400':
description: Invalid request
'401':
description: Missing or invalid API key
'404':
description: >-
Optional destination account not found or not owned by this
integration
components:
schemas:
HostedCheckoutSession:
type: object
properties:
id:
type: string
description: Hosted checkout session ID
status:
type: string
enum:
- open
- paid
- expired
- cancelled
sideshiftAccountId:
type: string
description: >-
SideShift wallet destination. Defaults to the API-key company
wallet.
amountCents:
type: integer
description: Net amount credited to the destination wallet
feeCents:
type: integer
description: Customer-facing processing fee
totalChargedCents:
type: integer
description: Total amount charged to the payer
currency:
type: string
example: usd
paymentMethodType:
type: string
enum:
- card
- link
- apple_pay
- google_pay
- amazon_pay
- cashapp
- paypal
- venmo
- crypto
- coinbase
- us_bank_account
- us_bank_transfer
- eu_bank_transfer
- gb_bank_transfer
- au_bank_transfer
- pay_by_bank
- klarna
- affirm
- afterpay_clearpay
description: Payment method used for fee calculation
allowedPaymentMethods:
type: array
description: >-
Payment methods allowed on the hosted checkout. Empty means
SideShift's default checkout methods are available.
items:
type: string
enum:
- card
- link
- apple_pay
- google_pay
- amazon_pay
- cashapp
- paypal
- venmo
- crypto
- coinbase
- us_bank_account
- us_bank_transfer
- eu_bank_transfer
- gb_bank_transfer
- au_bank_transfer
- pay_by_bank
- klarna
- affirm
- afterpay_clearpay
url:
type: string
format: uri
description: SideShift-hosted checkout URL to redirect the payer to
hostedUrl:
type: string
format: uri
description: Same as `url`; public full-page checkout URL
embedUrl:
type: string
format: uri
description: SideShift embedded checkout iframe URL
widgetUrl:
type: string
format: uri
description: Alias of `embedUrl` for iframe integrations
checkoutConfigId:
type: string
description: Internal checkout configuration ID
sandbox:
type: boolean
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.
````