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

# Read Settlement Transaction

> Retrieve one transaction by token. The ID prefix selects the response shape:

- `stxn_…` returns `data.settlement_transaction` (settlement payout)
- `txn_…` returns `data.transactions` (underlying payment/refund ledger transaction)

Invalid prefixes return `400 Bad Request`.




## OpenAPI

````yaml get /v1/aggregators/{raast-aggregator-id}/settlements/transactions/{transaction-id}
openapi: 3.1.0
info:
  title: Raast Wire
  version: 1.0.0
  description: ''
servers:
  - url: https://api.getsafepay.com/raastwire
security: []
tags:
  - name: Aggregators
  - name: Access Keys
  - name: Merchants
  - name: Raast Merchants
  - name: Payments
  - name: Refunds
  - name: QRs
  - name: Utilities
  - name: Aliases
  - name: Ledgers
  - name: Webhooks
  - name: Settlement Operations
  - name: Settlement Reports
paths:
  /v1/aggregators/{raast-aggregator-id}/settlements/transactions/{transaction-id}:
    parameters:
      - $ref: '#/components/parameters/AggregatorIdParam'
      - $ref: '#/components/parameters/SettlementOpsTransactionIdParam'
    get:
      tags:
        - Settlement Operations
      summary: Read Settlement Transaction
      description: >
        Retrieve one transaction by token. The ID prefix selects the response
        shape:


        - `stxn_…` returns `data.settlement_transaction` (settlement payout)

        - `txn_…` returns `data.transactions` (underlying payment/refund ledger
        transaction)


        Invalid prefixes return `400 Bad Request`.
      responses:
        '200':
          $ref: '#/components/responses/ReadSettlementOpsTransactionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - apiKey: []
components:
  parameters:
    AggregatorIdParam:
      name: raast-aggregator-id
      in: path
      required: true
      schema:
        type: string
        example: agg_2288490a-2176-4de5-b373-0ffb6f8e2e6e
      description: The unique identifier for the aggregator
    SettlementOpsTransactionIdParam:
      name: transaction-id
      in: path
      required: true
      description: >
        Transaction token. Use a settlement transaction id (`stxn_…`, 41
        characters) or a general transaction id (`txn_…`, 40 characters).
      schema:
        type: string
        example: stxn_d646b075-f62b-49f7-ab0f-7df161a6fc0b
  responses:
    ReadSettlementOpsTransactionResponse:
      description: >-
        Settlement payout or general transaction details depending on the id
        prefix.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/StandardResponse'
              - type: object
                properties:
                  data:
                    type: object
                    properties:
                      settlement_transaction:
                        $ref: '#/components/schemas/SettlementTransaction'
                      transactions:
                        $ref: '#/components/schemas/SettlementOpsTransaction'
          examples:
            SettlementTransactionRead:
              summary: Settlement transaction (`stxn_`)
              value:
                api_version: v1
                data:
                  settlement_transaction:
                    id: '13'
                    token: stxn_d646b075-f62b-49f7-ab0f-7df161a6fc0b
                    settlement_batch_id: sb_8ea56b1e-dc96-4751-9ca6-3bcc47e9a5c2
                    aggregator_id: agg_8fd114c0-1364-4953-8773-62551397ffe1
                    aggregator_merchant_id: am_7c9594a6-962d-49c7-94e9-64d9cf285969
                    raast_merchant_id: mer_e1a38d10-0064-4d7b-a700-f4ba483efb05
                    status: SETTLEMENT_TXN_POSTED
                    attempt: 1
                    gross_amount: '2000'
                    fee_amount: '10'
                    net_amount: '1929'
                    sales_tax_on_fee_amount: '1'
                    sales_tax_withholding_amount: '40'
                    income_tax_withholding_amount: '20'
                    digital_tax_amount: '0'
                    debitor_account_id: acct_f72d1825-31cc-43a2-a7f6-4463443a1c46
                    creditor_account_id: acct_7f073fa9-e248-4f96-8e7c-99ddcd282124
                    failure_reason: ''
                    created_at: '2026-02-06T16:30:02Z'
                    updated_at: '2026-02-06T16:30:04Z'
            GeneralTransactionRead:
              summary: General transaction (`txn_`)
              value:
                api_version: v1
                data:
                  transactions:
                    id: '160'
                    token: txn_8ffa984c-f0cb-4835-8eee-89c9ca673dad
                    payment_id: pm_e950c9fc-9532-4f4b-aa4c-d39b8f2619c6
                    refund_id: null
                    transaction_type: TT_PAYMENT
                    payment_type: DYNAMIC_QR
                    status: TXN_SETTLEMENT_CONFIRMED
                    aggregator_id: agg_8fd114c0-1364-4953-8773-62551397ffe1
                    aggregator_name: Safepay Aggregator
                    aggregator_merchant_id: am_7c9594a6-962d-49c7-94e9-64d9cf285969
                    aggregator_merchant_name: Safepay Merchant
                    raast_merchant_id: mer_e1a38d10-0064-4d7b-a700-f4ba483efb05
                    raast_merchant_name: Safepay Merchant
                    raast_merchant_ntn: '4669740'
                    raast_merchant_province: Sindh
                    gross_amount: '100'
                    currency: PKR
                    fee_amount: '0'
                    net_amount: '97'
                    sales_tax_on_fee_amount: '0'
                    sales_tax_withholding_amount: '2'
                    income_tax_withholding_amount: '1'
                    digital_tax_amount: '0'
                    latest_batch_id: sb_1328a110-2cf5-4e13-993e-55792ec6b76c
                    partner_id: partner_37e414c3-c0cc-4541-9bea-ab5a22964bd8
                    created_at: '2026-04-13T06:33:35Z'
                    updated_at: '2026-04-13T11:30:04Z'
    BadRequest:
      description: Bad request
      headers:
        Content-Length:
          $ref: '#/components/headers/ContentLengthHeader'
        Date:
          $ref: '#/components/headers/DateHeader'
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ErrorResponse'
              - type: object
                properties:
                  code:
                    example: error.bad_request
                  message:
                    example: Invalid request parameters
    Unauthorized:
      description: Unauthorized
      headers:
        Content-Length:
          $ref: '#/components/headers/ContentLengthHeader'
        Date:
          $ref: '#/components/headers/DateHeader'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
          examples:
            Unauthorized:
              value:
                api_version: v1
                error:
                  code: error.unauthorized_access
                  message: partner access key is required in request header
    NotFound:
      description: Resource not found
      headers:
        Content-Length:
          $ref: '#/components/headers/ContentLengthHeader'
        Date:
          $ref: '#/components/headers/DateHeader'
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ErrorResponse'
              - type: object
                properties:
                  code:
                    example: error.not_found
                  message:
                    example: Requested resource not found
  schemas:
    StandardResponse:
      type: object
      description: Standard response structure for successful operations
      properties:
        api_version:
          type: string
          example: v1
          description: The current version of the API spec
        data:
          type: object
          description: Contains the response data
    SettlementTransaction:
      type: object
      description: Settlement payout transaction dispatched as part of a batch.
      properties:
        id:
          type: string
          example: '49'
        token:
          type: string
          example: stxn_75549797-f2c6-421d-8dd7-ce39995534b8
        settlement_batch_id:
          type: string
          example: sb_1328a110-2cf5-4e13-993e-55792ec6b76c
        aggregator_id:
          type: string
          example: agg_8fd114c0-1364-4953-8773-62551397ffe1
        aggregator_merchant_id:
          type: string
          example: am_7c9594a6-962d-49c7-94e9-64d9cf285969
        raast_merchant_id:
          type: string
          example: mer_e1a38d10-0064-4d7b-a700-f4ba483efb05
        status:
          type: string
          enum:
            - SETTLEMENT_TXN_ACK_PENDING
            - SETTLEMENT_TXN_POSTED
            - SETTLEMENT_TXN_FAILED
            - SETTLEMENT_TXN_REJECTED
          example: SETTLEMENT_TXN_POSTED
        attempt:
          type: integer
          example: 1
        gross_amount:
          type: string
          example: '300'
        fee_amount:
          type: string
          example: '0'
        net_amount:
          type: string
          example: '294'
        sales_tax_on_fee_amount:
          type: string
          example: '0'
        sales_tax_withholding_amount:
          type: string
          example: '4'
        income_tax_withholding_amount:
          type: string
          example: '2'
        digital_tax_amount:
          type: string
          example: '0'
        debitor_account_id:
          type: string
          example: acct_f72d1825-31cc-43a2-a7f6-4463443a1c46
        creditor_account_id:
          type: string
          example: acct_7f073fa9-e248-4f96-8e7c-99ddcd282124
        failure_reason:
          type: string
          example: ''
        created_at:
          $ref: '#/components/schemas/Timestamp'
        updated_at:
          $ref: '#/components/schemas/Timestamp'
        debitor_account:
          allOf:
            - $ref: '#/components/schemas/LedgerAccount'
          nullable: true
        creditor_account:
          allOf:
            - $ref: '#/components/schemas/LedgerAccount'
          nullable: true
        settlement_batch:
          allOf:
            - $ref: '#/components/schemas/SettlementBatch'
          nullable: true
    SettlementOpsTransaction:
      type: object
      description: Underlying payment or refund ledger transaction included in settlement.
      properties:
        id:
          type: string
          example: '160'
        token:
          type: string
          example: txn_8ffa984c-f0cb-4835-8eee-89c9ca673dad
        payment_id:
          type: string
          nullable: true
          example: pm_e950c9fc-9532-4f4b-aa4c-d39b8f2619c6
        refund_id:
          type: string
          nullable: true
          example: null
        transaction_type:
          type: string
          example: TT_PAYMENT
        payment_type:
          type: string
          example: DYNAMIC_QR
        status:
          type: string
          enum:
            - TXN_LEDGER_POSTED
            - TXN_SETTLEMENT_SCHEDULED
            - TXN_SETTLEMENT_DISPATCHED
            - TXN_SETTLEMENT_CONFIRMED
            - TXN_SETTLEMENT_REVERSED
          example: TXN_SETTLEMENT_CONFIRMED
        aggregator_id:
          type: string
          example: agg_8fd114c0-1364-4953-8773-62551397ffe1
        aggregator_name:
          type: string
          example: Safepay Aggregator
        aggregator_merchant_id:
          type: string
          example: am_7c9594a6-962d-49c7-94e9-64d9cf285969
        aggregator_merchant_name:
          type: string
          example: Safepay Merchant
        raast_merchant_id:
          type: string
          example: mer_e1a38d10-0064-4d7b-a700-f4ba483efb05
        raast_merchant_name:
          type: string
          example: Safepay Merchant
        raast_merchant_ntn:
          type: string
          example: '4669740'
        raast_merchant_province:
          type: string
          example: Sindh
        gross_amount:
          type: string
          example: '100'
        currency:
          type: string
          example: PKR
        fee_amount:
          type: string
          example: '0'
        net_amount:
          type: string
          example: '97'
        sales_tax_on_fee_amount:
          type: string
          example: '0'
        sales_tax_withholding_amount:
          type: string
          example: '2'
        income_tax_withholding_amount:
          type: string
          example: '1'
        digital_tax_amount:
          type: string
          example: '0'
        debitor_account_id:
          type: string
          nullable: true
        creditor_account_id:
          type: string
          nullable: true
          example: acct_7f073fa9-e248-4f96-8e7c-99ddcd282124
        latest_batch_id:
          type: string
          example: sb_1328a110-2cf5-4e13-993e-55792ec6b76c
        partner_id:
          type: string
          example: partner_37e414c3-c0cc-4541-9bea-ab5a22964bd8
        created_at:
          $ref: '#/components/schemas/Timestamp'
        updated_at:
          $ref: '#/components/schemas/Timestamp'
        debitor_account:
          allOf:
            - $ref: '#/components/schemas/LedgerAccount'
          nullable: true
        creditor_account:
          allOf:
            - $ref: '#/components/schemas/LedgerAccount'
          nullable: true
        latest_batch:
          allOf:
            - $ref: '#/components/schemas/SettlementBatch'
          nullable: true
    ErrorResponse:
      type: object
      description: Standard error response structure
      properties:
        code:
          type: string
          description: Error code identifying the type of error
        message:
          type: string
          description: Human-readable error message
    ApiErrorEnvelope:
      type: object
      description: Error wrapper that includes the API version and error metadata
      properties:
        api_version:
          type: string
          description: Indicates the API version associated with the response
          example: v1
        error:
          description: Structured error details describing why the request failed
          allOf:
            - $ref: '#/components/schemas/ErrorResponse'
          example:
            code: error.unauthorized_access
            message: partner access key is required in request header
    Timestamp:
      type: string
      format: date-time
      description: ISO 8601 timestamp in UTC
      example: '2025-03-13T09:12:34.000Z'
    LedgerAccount:
      type: object
      description: ledger account record
      properties:
        id:
          type: string
        token:
          type: string
        account_type:
          type: string
        account_name:
          type: string
        normal_balance:
          type: string
        balance:
          type: string
        currency:
          type: string
        running_balance:
          type: string
        vault_token:
          type: string
        bank_acct_id:
          type: string
        external_partner_id:
          type: string
        external_aggregator_id:
          type: string
        external_merchant_id:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    SettlementBatch:
      type: object
      description: Settlement batch metadata for aggregator settlement operations.
      properties:
        id:
          type: string
          example: '200'
        token:
          type: string
          example: sb_1328a110-2cf5-4e13-993e-55792ec6b76c
        file_name:
          type: string
          example: ''
        date:
          $ref: '#/components/schemas/Timestamp'
        status:
          type: string
          enum:
            - BATCH_CREATED
            - BATCH_PROCESSING
            - BATCH_COMPLETED
            - BATCH_FAILED
          example: BATCH_COMPLETED
        version:
          type: integer
          example: 1
        created_by_job_id:
          type: string
          example: job_76b08225-5372-46db-9acb-086ac9c2f7d6
        partner_id:
          type: string
          example: partner_37e414c3-c0cc-4541-9bea-ab5a22964bd8
        artifacts:
          type: array
          items:
            $ref: '#/components/schemas/SettlementBatchArtifact'
        settlement_snapshots:
          type: array
          description: >-
            Usually empty on read; use the snapshots list endpoint for per-row
            data.
          items:
            $ref: '#/components/schemas/SettlementSnapshot'
        charge_snapshot:
          allOf:
            - $ref: '#/components/schemas/SettlementBatchChargeSnapshot'
          nullable: true
        created_at:
          $ref: '#/components/schemas/Timestamp'
    SettlementBatchArtifact:
      type: object
      description: Downloadable file artifact attached to a settlement batch.
      properties:
        id:
          type: string
          example: '21'
        batch_id:
          type: string
          example: sb_1328a110-2cf5-4e13-993e-55792ec6b76c
        artifact_type:
          type: string
          description: Artifact type enum name.
          enum:
            - BATCH_ARTIFACT_TYPE_UNSPECIFIED
            - BATCH_ARTIFACT_TYPE_SETTLEMENT_FILE
            - BATCH_ARTIFACT_TYPE_CHARGES_SUMMARY_FILE
          example: BATCH_ARTIFACT_TYPE_SETTLEMENT_FILE
        file_name:
          type: string
          example: >-
            CEP Safepay 20260723113002
            sb_1328a110-2cf5-4e13-993e-55792ec6b76c.xls
        s3_key:
          type: string
          example: >-
            settlement-batches/partner_37e414c3-c0cc-4541-9bea-ab5a22964bd8/sb_1328a110-2cf5-4e13-993e-55792ec6b76c/CEP
            Safepay 20260723113002 sb_1328a110-2cf5-4e13-993e-55792ec6b76c.xls
        presigned_url:
          type: string
          description: Temporary signed URL used to download the artifact.
          example: https://example-bucket.s3.amazonaws.com/settlement-batches/...
        created_at:
          $ref: '#/components/schemas/Timestamp'
    SettlementSnapshot:
      type: object
      description: Per-merchant settlement snapshot captured for a batch.
      properties:
        id:
          type: string
          example: '44'
        batch_id:
          type: string
          example: sb_1328a110-2cf5-4e13-993e-55792ec6b76c
        settlement_transaction_id:
          type: string
          example: stxn_9d5bd7bd-863a-487f-944c-f15d30d9bbc5
        merchant_id:
          type: string
          example: mer_ce6df98c-cdde-48bf-bc32-464cecac2ee3
        aggregator_id:
          type: string
          example: agg_b49985f2-e099-412e-8eb2-98756059cc0d
        iban:
          type: string
          example: PK36SCBL0000001123456702
        account_title:
          type: string
          example: OPTIVOLVE DIGITAL
        gross_amount:
          type: string
          example: '7900'
        net_amount:
          type: string
          example: '7620'
        fee_amount:
          type: string
          example: '39'
        sales_tax_on_fee_amount:
          type: string
          example: '4'
        sales_tax_withholding_amount:
          type: string
          example: '158'
        income_tax_withholding_amount:
          type: string
          example: '79'
        digital_tax_amount:
          type: string
          example: '0'
        currency:
          type: string
          example: PKR
        created_at:
          $ref: '#/components/schemas/Timestamp'
    SettlementBatchChargeSnapshot:
      type: object
      description: >-
        Batch-level charges summary totals. Amounts are in the lowest currency
        denomination.
      properties:
        id:
          type: string
          example: '8'
        batch_id:
          type: string
          example: sb_1328a110-2cf5-4e13-993e-55792ec6b76c
        gross_amount:
          type: string
          example: '8100'
        net_amount:
          type: string
          example: '7814'
        fee_amount:
          type: string
          example: '39'
        sales_tax_on_fee_amount:
          type: string
          example: '4'
        sales_tax_withholding_amount:
          type: string
          example: '162'
        income_tax_withholding_amount:
          type: string
          example: '81'
        digital_tax_amount:
          type: string
          example: '0'
        created_at:
          $ref: '#/components/schemas/Timestamp'
  headers:
    ContentLengthHeader:
      schema:
        type: string
        example: '256'
    DateHeader:
      schema:
        type: string
        example: Sat, 12 Aug 2023 08:55:04 GMT
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-SFPY-AGGREGATOR-SECRET-KEY
      in: header

````