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": "TRANSFER_FAILED",
    "message": "Transfer outcome is awaiting reconciliation. Retry only with the same idempotencyKey."
  }
}

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

{
  "success": false,
  "error": {
    "code": "DUPLICATE_TRANSFER",
    "message": "A transfer with this idempotencyKey already exists with different parameters",
    "details": {
      "conflictType": "idempotency"
    }
  }
}

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’s withdrawable balance at the payment provider. User→Company transfers settle into your company SideShift wallet, and are funded from the user’s withdrawable balance when their SideShift wallet is short, which is how a payout is pulled back. destinationBalance: wallet (parking the money in the destination’s internal wallet) is deprecated.

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: All transfer directions remain isolated SideShift-ledger simulations. No provider payout is attempted because the payment provider does not support payouts in sandbox.

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": "TRANSFER_FAILED",
    "message": "Transfer outcome is awaiting reconciliation. Retry only with the same idempotencyKey."
  }
}

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

{
  "success": false,
  "error": {
    "code": "DUPLICATE_TRANSFER",
    "message": "A transfer with this idempotencyKey already exists with different parameters",
    "details": {
      "conflictType": "idempotency"
    }
  }
}

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

Where a company→user or user→user transfer settles. withdrawal (the default) pays the destination's withdrawable balance at the payment provider: the balance the payout widget shows, and the balance a later user_to_company transfer can pull back from. wallet is deprecated. It parks the money in the destination's internal SideShift wallet, from which it cannot be withdrawn until moved with POST /accounts/withdrawal-balance.

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