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

> Retrieve one settlement batch by token, including downloadable batch artifacts and the batch-level charge snapshot when available.

Per-merchant settlement snapshot rows are exposed through the dedicated snapshots list endpoint, not embedded on this response.




## OpenAPI

````yaml get /v1/aggregators/{raast-aggregator-id}/settlements/batches/{settlement-batch-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/batches/{settlement-batch-id}:
    parameters:
      - $ref: '#/components/parameters/AggregatorIdParam'
      - $ref: '#/components/parameters/SettlementBatchIdParam'
    get:
      tags:
        - Settlement Operations
      summary: Read Settlement Batch
      description: >
        Retrieve one settlement batch by token, including downloadable batch
        artifacts and the batch-level charge snapshot when available.


        Per-merchant settlement snapshot rows are exposed through the dedicated
        snapshots list endpoint, not embedded on this response.
      responses:
        '200':
          $ref: '#/components/responses/ReadSettlementBatchResponse'
        '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
    SettlementBatchIdParam:
      name: settlement-batch-id
      in: path
      required: true
      description: >-
        Settlement batch token. Must start with `sb_` and be exactly 39
        characters.
      schema:
        type: string
        example: sb_1328a110-2cf5-4e13-993e-55792ec6b76c
  responses:
    ReadSettlementBatchResponse:
      description: Settlement batch details including artifacts and charge snapshot.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/StandardResponse'
              - type: object
                properties:
                  data:
                    type: object
                    properties:
                      settlement_batch:
                        $ref: '#/components/schemas/SettlementBatch'
          examples:
            SettlementBatchRead:
              value:
                api_version: v1
                data:
                  settlement_batch:
                    id: '200'
                    token: sb_1328a110-2cf5-4e13-993e-55792ec6b76c
                    file_name: ''
                    date: '1970-01-01T00:00:00Z'
                    status: BATCH_COMPLETED
                    version: 1
                    created_by_job_id: job_76b08225-5372-46db-9acb-086ac9c2f7d6
                    partner_id: partner_37e414c3-c0cc-4541-9bea-ab5a22964bd8
                    artifacts:
                      - id: '21'
                        batch_id: sb_1328a110-2cf5-4e13-993e-55792ec6b76c
                        artifact_type: BATCH_ARTIFACT_TYPE_SETTLEMENT_FILE
                        file_name: >-
                          CEP Safepay 20260723113002
                          sb_1328a110-2cf5-4e13-993e-55792ec6b76c.xls
                        s3_key: >-
                          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: >-
                          https://example-bucket.s3.amazonaws.com/settlement-batches/...
                        created_at: '2026-07-23T11:30:06Z'
                    charge_snapshot:
                      id: '8'
                      batch_id: sb_1328a110-2cf5-4e13-993e-55792ec6b76c
                      gross_amount: '8100'
                      net_amount: '7814'
                      fee_amount: '39'
                      sales_tax_on_fee_amount: '4'
                      sales_tax_withholding_amount: '162'
                      income_tax_withholding_amount: '81'
                      digital_tax_amount: '0'
                      created_at: '2026-07-23T11:30:06Z'
                    created_at: '2026-04-13T11:30:02Z'
    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
    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'
    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'
    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

````