curl --request POST \
  --url https://app.sideshift.app/api/embed/accounts/transfer \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "toAccountId": "acct_a1b2c3d4e5f6",
  "amountCents": 5000,
  "idempotencyKey": "payout-order-12345",
  "metadata": {
    "obligationType": "campaign",
    "obligationReference": "contract-123",
    "description": "Approved payout for completed launch video",
    "approvalReference": "approval-456",
    "programId": "campaign-789"
  }
}
'

{
  "success": true,
  "data": {
    "transferId": "txfr_abc123def456",
    "fromAccountId": "company",
    "toAccountId": "acct_a1b2c3d4e5f6",
    "amountCents": 5000,
    "amountUsd": 50,
    "status": "completed",
    "direction": "company_to_user",
    "destinationBalance": "withdrawal",
    "idempotencyKey": "payout-order-12345",
    "createdAt": "2026-03-13T12:00:00.000Z",
    "completedAt": "2026-03-13T12:00:01.000Z"
  }
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance to complete transfer"
  }
}

Create transfer

Move funds between accounts. Three directions are supported:

Direction	`fromAccountId`	`toAccountId`
Company → User	(omit)	User account
User → Company	User account	(omit)
User → User	Source account	Destination account

Funding behavior: Transfers use the source SideShift wallet first. If a source user is short in SideShift wallet but has enough withdrawal-ready balance, SideShift automatically moves the needed funds through the supported child-to-platform path first, then completes the transfer.

Settlement behavior: Company→User and User→User transfers settle into the destination withdrawal-ready balance by default. Pass destinationBalance: wallet to settle those transfers into the destination SideShift wallet instead. User→Company transfers always settle into your company SideShift wallet.

Idempotency: An idempotencyKey is required. A replay returns the original successful transfer result.

Commercial evidence: New live integrations require string metadata for obligationType, obligationReference, description, and approvalReference. Campaign transfers also require programId or contractId. Allowed obligation types are campaign, creator_agreement, subscription, refund, wallet_reconciliation, platform_correction, and other_approved. Existing authorizations created before this requirement remain backward-compatible during migration; new authorizations enforce it automatically. This metadata is optional in sandbox.

Sandbox: Company→User transfers are simulated — no real payout is executed but the internal ledger is updated normally.

POST

accounts

transfer

curl --request POST \
  --url https://app.sideshift.app/api/embed/accounts/transfer \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "toAccountId": "acct_a1b2c3d4e5f6",
  "amountCents": 5000,
  "idempotencyKey": "payout-order-12345",
  "metadata": {
    "obligationType": "campaign",
    "obligationReference": "contract-123",
    "description": "Approved payout for completed launch video",
    "approvalReference": "approval-456",
    "programId": "campaign-789"
  }
}
'

{
  "success": true,
  "data": {
    "transferId": "txfr_abc123def456",
    "fromAccountId": "company",
    "toAccountId": "acct_a1b2c3d4e5f6",
    "amountCents": 5000,
    "amountUsd": 50,
    "status": "completed",
    "direction": "company_to_user",
    "destinationBalance": "withdrawal",
    "idempotencyKey": "payout-order-12345",
    "createdAt": "2026-03-13T12:00:00.000Z",
    "completedAt": "2026-03-13T12:00:01.000Z"
  }
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance to complete transfer"
  }
}

Authorizations

x-api-key

string

header

required

Your SideShift Connect API key (sk_live_* or sk_test_*). Generate from Settings → Connect.

Body

application/json

amountCents

integer

required

Amount in cents

Required range: x >= 1

Example:

5000

idempotencyKey

string

required

Unique key for safe retries

Example:

"payout-order-12345"

fromAccountId

string

Source account (omit for company→user)

toAccountId

string

Destination account (omit for user→company)

destinationBalance

enum<string>

default:withdrawal

Settlement target for company→user and user→user transfers. Use wallet to keep funds in the destination SideShift wallet.

Available options:

withdrawal,

wallet

metadata

object

Required for newly created live integrations. Include obligationType, obligationReference, description, and approvalReference; campaign transfers also need programId or contractId. Existing integrations remain compatible during migration.

Show child attributes

Response

Transfer completed

success

boolean

data

object

Show child attributes

⌘I