> ## 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.

# Get invoice transactions

> Retrieve invoice-backed payin transactions for an account.

This endpoint only returns invoice payments. General wallet topups and other non-invoice deposits do not appear here, even though they still appear in `/accounts/balance` transactions.




## OpenAPI

````yaml /openapi/connect.yaml get /accounts/invoices
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

    <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 (alternative):**

    ```jsx

    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):**

    ```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:
  /accounts/invoices:
    get:
      tags:
        - Accounts
      summary: Get invoice transactions
      description: >
        Retrieve invoice-backed payin transactions for an account.


        This endpoint only returns invoice payments. General wallet topups and
        other non-invoice deposits do not appear here, even though they still
        appear in `/accounts/balance` transactions.
      operationId: getAccountInvoices
      parameters:
        - name: sideshiftAccountId
          in: query
          required: true
          schema:
            type: string
          description: Account to query
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: download
          in: query
          schema:
            type: boolean
            default: false
          description: When true, invoice and receipt URLs force download
      responses:
        '200':
          description: Invoice transactions
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      sideshiftAccountId:
                        type: string
                      platformName:
                        type: string
                      invoices:
                        type: array
                        items:
                          type: object
                          properties:
                            transactionId:
                              type: string
                            invoiceId:
                              type: string
                            platformName:
                              type: string
                            invoiceNumber:
                              type: string
                              nullable: true
                            status:
                              type: string
                              nullable: true
                            amountCents:
                              type: integer
                            currency:
                              type: string
                            customerEmail:
                              type: string
                              nullable: true
                            customerName:
                              type: string
                              nullable: true
                            paidAt:
                              type: string
                              format: date-time
                              nullable: true
                            createdAt:
                              type: string
                              format: date-time
                              nullable: true
                            invoiceUrl:
                              type: string
                            receiptUrl:
                              type: string
                              nullable: true
                      pagination:
                        $ref: '#/components/schemas/Pagination'
              example:
                success: true
                data:
                  sideshiftAccountId: acct_a1b2c3d4e5f6
                  platformName: ClipStake
                  invoices:
                    - transactionId: invoice_inv_123
                      invoiceId: inv_123
                      platformName: ClipStake
                      invoiceNumber: INV-123
                      status: paid
                      amountCents: 1000
                      currency: usd
                      customerEmail: jane@example.com
                      customerName: Jane Creator
                      paidAt: '2026-03-13T12:30:00.000Z'
                      createdAt: '2026-03-13T12:00:00.000Z'
                      invoiceUrl: >-
                        https://app.sideshift.app/api/invoices/inv_123/pdf?download=false
                      receiptUrl: >-
                        https://app.sideshift.app/api/invoices/inv_123/receipt?download=false
                  pagination:
                    total: 1
                    limit: 10
                    offset: 0
                    hasMore: false
        '400':
          description: Missing account ID
        '404':
          description: Account not found or not owned by this integration
components:
  schemas:
    Pagination:
      type: object
      properties:
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
        hasMore:
          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.

````