> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zopay.cash/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Transaction

> Single transaction by id.

Single transaction by id.

Cross-tenant access collapses to 404. A partner trying to fetch
another partner's transaction id (whether by guessing or by
accident) sees the same response as a non-existent id, so the
existence of rows under other tenants is not leakable.


## OpenAPI

````yaml GET /transactions/{transaction_id}
openapi: 3.1.0
info:
  title: ZoPay Connect API
  description: >-
    B2B partner API for crypto custody, deposits, and payouts. Authenticate
    every request with a Bearer token (``sk_live_…`` for production,
    ``sk_test_…`` for sandbox).
  version: v1
servers:
  - url: https://api.zopay.cash/connect/v1
    description: Production
  - url: https://dev.api.zopay.cash/connect/v1
    description: Development
security:
  - BearerAuth: []
tags:
  - name: capabilities
    description: >-
      Static product catalog: which assets, networks, and fiat valuations this
      tenant can use. Poll on app startup to drive every UI surface (network
      pickers, fee warnings, fiat selection).
  - name: addresses
    description: >-
      Per-user deposit addresses. Mint with ``external_ref`` to attribute to one
      of your users; omit for a tenant-treasury (pooled) address.
  - name: payment-intents
    description: >-
      Single-use payment requests. Mint an intent for a specific amount +
      currency set; we expand it to per-network deposit addresses. Pass
      ``external_ref`` to attribute the intent to one of your users for
      downstream webhook reconciliation.
  - name: balances
    description: >-
      Per-user or tenant-wide balance snapshot with multi-fiat valuation (USD,
      PEN, EUR, MXN, ARS, COP, DOP).
  - name: transactions
    description: >-
      Unified ledger covering deposits, payouts, internal transfers, and (after
      Phase 4) conversions and ramps.
  - name: payouts
    description: >-
      Outbound money movement: get a signed quote, then execute it. Quote IDs
      are single-use and expire in 60s.
  - name: conversions
    description: '[Coming soon] Crypto-to-crypto conversions.'
  - name: ramps
    description: '[Coming soon] Fiat <-> crypto hosted-checkout sessions.'
  - name: webhooks
    description: '[Coming soon] Subscribe to event streams + replay past events.'
  - name: health
    description: >-
      Auth + connectivity probe. Use to validate your API key works before
      depending on a priced endpoint.
  - name: test-helpers
    description: >-
      Sandbox-only simulators. Let you exercise webhook handlers and downstream
      state transitions without real testnet activity. Routes return 404 to
      ``sk_live_…`` keys.
paths:
  /transactions/{transaction_id}:
    get:
      tags:
        - transactions
      summary: Get Transaction
      description: |-
        Single transaction by id.

        Cross-tenant access collapses to 404. A partner trying to fetch
        another partner's transaction id (whether by guessing or by
        accident) sees the same response as a non-existent id, so the
        existence of rows under other tenants is not leakable.
      operationId: get_transaction_transactions__transaction_id__get
      parameters:
        - name: transaction_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Transaction Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectTransactionLine'
        '400':
          description: >-
            Invalid request. The body or query parameters failed validation.
            ``error.code`` names the specific failure (e.g. ``invalid_request``,
            ``catalog_invalid``, ``min_usdt_amount_requires_solana``);
            ``error.param`` names the offending field when applicable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectErrorEnvelope'
        '401':
          description: >-
            Authentication failed. ``error.code`` distinguishes
            ``authentication_required`` (missing / malformed / unknown key) from
            ``expired_credential`` (key matched but past its ``expires_at``).
            Rotate the key in the admin panel for the latter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectErrorEnvelope'
        '403':
          description: >-
            The key is valid but lacks permission for this endpoint.
            ``error.code`` is ``forbidden_scope`` when the key is missing a
            scope; ``account_pending_approval`` when the org is not yet active
            for Connect.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectErrorEnvelope'
        '404':
          description: >-
            Resource not found in this tenant. Same envelope shape is returned
            for genuinely-missing IDs and for cross-tenant accesses -- existence
            under other tenants is not leakable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectErrorEnvelope'
        '409':
          description: >-
            Conflict. Most commonly ``idempotency_conflict`` -- the same
            ``Idempotency-Key`` was reused with a different body. Generate a
            fresh key or replay the original body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectErrorEnvelope'
        '422':
          description: >-
            Validation failed. Runtime translates FastAPI / Pydantic validation
            errors into the same Connect envelope you see on 400s; this status
            is emitted when the request shape is structurally wrong (missing
            required field, wrong type).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectErrorEnvelope'
        '429':
          description: >-
            Rate limited. Back off and retry. ``error.code`` is
            ``rate_limited``; per-key throughput is documented via
            ``rate_limit_rps`` on the API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectErrorEnvelope'
        '500':
          description: >-
            Internal server error. ``error.code`` is ``internal_error``. The
            request can usually be safely retried with the same
            ``Idempotency-Key``.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectErrorEnvelope'
        '501':
          description: >-
            Endpoint is declared in the router but its implementation has not
            shipped yet (``error.code = not_yet_available``). Pinned in the
            schema so SDK generators emit the endpoint with a typed error rather
            than skipping it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectErrorEnvelope'
      security:
        - BearerAuth: []
components:
  schemas:
    ConnectTransactionLine:
      properties:
        id:
          type: string
          title: Id
          description: Transaction id (UUID).
        type:
          type: string
          enum:
            - deposit
            - payout
            - transfer
            - conversion
            - ramp
          title: Type
          description: >-
            Derived from the internal row's direction and is_external flag; see
            schema docstring for the mapping.
        status:
          type: string
          enum:
            - pending
            - confirmed
            - failed
          title: Status
          description: >-
            Partner-facing status. The full internal state machine
            (pending/processing/completed/failed/rejected/canceled) is collapsed
            into three buckets matching the spec.
        external_ref:
          anyOf:
            - type: string
            - type: 'null'
          title: External Ref
          description: >-
            The partner's user id, echoed back. Set for both deposit (recipient
            is the partner's user) and payout (sender is the partner's user).
            For internal transfers, the ref of whichever side is the partner's
            user; None if neither side is mapped (shouldn't happen in a
            tenant-scoped query, defensive against schema drift).
        asset:
          type: string
          title: Asset
          description: Asset code, uppercase (USDT, XAUT).
        network:
          anyOf:
            - type: string
            - type: 'null'
          title: Network
          description: >-
            Network code (lowercase). NULL on internal-only ledger transfers
            (``is_external=false``) where no chain was touched.
        amount:
          type: string
          title: Amount
          description: Asset amount as a decimal string.
        from_address:
          anyOf:
            - type: string
            - type: 'null'
          title: From Address
          description: >-
            On-chain sender address. NULL on internal transfers and on outgoing
            rows where we have no on-chain metadata yet.
        to_address:
          anyOf:
            - type: string
            - type: 'null'
          title: To Address
          description: On-chain destination address. NULL on internal transfers.
        tx_hash:
          anyOf:
            - type: string
            - type: 'null'
          title: Tx Hash
          description: >-
            Blockchain transaction hash. NULL until broadcast (pending state)
            and on internal transfers.
        created_at:
          type: string
          format: date-time
          title: Created At
        completed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Completed At
          description: >-
            When the transaction reached a terminal state (confirmed or failed).
            NULL while pending.
      type: object
      required:
        - id
        - type
        - status
        - asset
        - amount
        - created_at
      title: ConnectTransactionLine
      description: |-
        A single transaction row in the partner-facing shape.

        All amounts are decimal strings (JS Number boundary defense).
        Optional fields are omitted from the JSON when None — we use
        Pydantic's exclusion-on-None pattern for that, configured at
        serialization time in the handler.
    ConnectErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/ConnectErrorBody'
          description: >-
            Error details. Always present on a non-2xx response from
            /connect/v1.
      type: object
      required:
        - error
      title: ConnectErrorEnvelope
      description: |-
        Top-level wrapper for every /connect/v1 failure response.

        Wire shape::

            {"error": {"type": ..., "code": ..., "message": ..., ...}}

        The wrapper is intentional: it keeps error bodies syntactically
        distinct from success bodies, so polymorphic partner code paths
        that read the same JSON for both states can branch on the
        presence of the ``error`` key.
    ConnectErrorBody:
      properties:
        type:
          type: string
          title: Type
          description: >-
            Stripe-style error category. One of: ``invalid_request_error``,
            ``authentication_error``, ``not_found_error``, ``rate_limit_error``,
            ``idempotency_error``, ``api_error``. Stable across minor versions;
            branch on this for top-level error routing.
          examples:
            - invalid_request_error
        code:
          type: string
          title: Code
          description: >-
            Machine-stable identifier for the specific failure. More specific
            than ``type``. Examples: ``invalid_request``,
            ``authentication_required``, ``expired_credential``,
            ``forbidden_scope``, ``account_pending_approval``,
            ``resource_not_found``, ``idempotency_conflict``, ``rate_limited``,
            ``internal_error``, ``not_yet_available``. Match on ``code`` in your
            client's error handler -- never parse ``message``.
          examples:
            - authentication_required
        message:
          type: string
          title: Message
          description: >-
            Human-readable explanation. Safe to surface in your own UI but may
            be reworded between releases -- never branch on the string.
          examples:
            - >-
              Missing or malformed Authorization header. Send: Authorization:
              Bearer sk_live_... or sk_test_...
        doc_url:
          type: string
          title: Doc Url
          description: >-
            Link to docs explaining this ``code``. Constructed as
            ``https://docs.zopay.cash/errors/<code>``. Surface this in support
            tickets so we can investigate without a round-trip.
          examples:
            - https://docs.zopay.cash/errors/authentication_required
        param:
          anyOf:
            - type: string
            - type: 'null'
          title: Param
          description: >-
            Names the offending input field when the error is
            input-shape-related (mostly ``invalid_request_error`` from 400 and
            422). Absent on auth, scope, rate-limit, and internal errors.
          examples:
            - currencies
      type: object
      required:
        - type
        - code
        - message
        - doc_url
      title: ConnectErrorBody
      description: |-
        The ``error`` object inside every /connect/v1 failure response.

        Mirrors ``ConnectError.to_envelope()`` in
        ``app/api/connect/errors.py``. Field set is locked -- adding a
        new field is a partner-visible contract change and requires a
        coordinated docs + schema update.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Connect API key (sk_live_… or sk_test_…)
      description: >-
        Paste your Connect API key (sk_live_… for production, sk_test_… for
        sandbox) without the ``Bearer `` prefix. Mint and rotate keys from the
        admin panel.

````