Connect

Embed payment infrastructure directly into your platform.

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.

Base URL is https://app.sideshift.app/api/embed.

Setup guide

1. Generate an API key

   Go to Settings → Connect 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.

   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": "[e-mail]", "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.

   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)

   <iframe
     src="WIDGET_URL"
     width="100%" height="500"
     frameborder="0"
     allow="payment; camera; microphone"
     style="border:0; border-radius:12px"
   ></iframe>
   

   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

   import { SideShiftPayout } from '@sideshiftapp/connect/react';
   
   <SideShiftPayout
     token={token}
     theme={{ theme: 'light', primaryColor: '#3D8CFA', borderRadius: 12 }}
     onWithdrawCompleted={(data) => 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)

   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.

   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.

   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.

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.

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.

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 and withdrawal UI work normally.

To verify sandbox transfers are working, use the balance API — this is the source of truth:

GET /accounts/balance?sideshiftAccountId=ACCOUNT_ID

The balanceCents and transactions in the response accurately reflect all sandbox transfers.

Testing checklist

1. Generate a test key

   Create an sk_test_* key and store it securely.
2. Create accounts

   Create at least two sandbox accounts.
3. Test every direction

   Company→user, user→company, and user→user.
4. Verify balances

   Check the balance API after each transfer.
5. Replay a transfer

   Reuse the same idempotencyKey and confirm no duplicate.
6. Check webhooks

   Confirm delivery and that signature verification passes.
7. Trigger errors

   Insufficient balance, invalid account — verify your handling.
8. Embed a widget

   Test 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 your 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 (for example a $0.50 transfer) before full volume

Reference

This page is ported from the Connect specification’s own introduction, so it stays in sync with what app.sideshift.app/docs/connect shows today.

Area	What it does
Accounts	Create and manage user accounts. Each gets a sideshiftAccountId and a wallet
Verifications	Read identity verification status and required actions for an account
Transfers	Move funds company→user, user→company, and user→user
Tokens	Generate short-lived tokens that authenticate embedded widget sessions
Checkout	Create public hosted checkout links that settle into your SideShift wallet
Webhooks	Real-time notifications when transfers, deposits, and withdrawals complete or fail

API reference

All 17 operations across the six areas above.

Webhook events

Eight events are available:

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, or to withdrawal.updated for the full lifecycle:

requested → awaiting_payment → in_transit → completed | failed | canceled | denied

Every delivery carries x-sideshift-signature and x-sideshift-timestamp headers. Non-2xx responses are retried with exponential backoff, up to five attempts. Webhooks fire in both sandbox and production.