> ## 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. # List Settlement Transactions > List settlement payout transactions for the aggregator by default. Set `only_transactions=true` to list underlying payment/refund ledger transactions instead. When listing settlement transactions, populate `settlement_transactions`; when listing general transactions, populate `transactions`. ## OpenAPI ````yaml get /v1/aggregators/{raast-aggregator-id}/settlements/transactions 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: parameters: - $ref: '#/components/parameters/AggregatorIdParam' get: tags: - Settlement Operations summary: List Settlement Transactions description: > List settlement payout transactions for the aggregator by default. Set `only_transactions=true` to list underlying payment/refund ledger transactions instead. When listing settlement transactions, populate `settlement_transactions`; when listing general transactions, populate `transactions`. parameters: - $ref: '#/components/parameters/SettlementOpsCursorParam' - $ref: '#/components/parameters/SettlementOpsLimitParam' - $ref: '#/components/parameters/SettlementOpsDirectionParam' - name: only_transactions in: query required: false description: >- When true, return general payment/refund transactions in `transactions` instead of settlement payouts in `settlement_transactions`. schema: type: boolean example: false - name: settlement_batch_id in: query required: false description: Filter by settlement batch token (`sb_…`). schema: type: string example: sb_1328a110-2cf5-4e13-993e-55792ec6b76c - name: settlement_txn_id in: query required: false description: >- Filter by settlement transaction token (`stxn_…`, exactly 41 characters). schema: type: string example: stxn_75549797-f2c6-421d-8dd7-ce39995534b8 - name: settlement_txn_status in: query required: false description: >- Filter settlement transactions by status integer enum (`1=SETTLEMENT_TXN_ACK_PENDING`, `2=SETTLEMENT_TXN_POSTED`, `3=SETTLEMENT_TXN_FAILED`, `4=SETTLEMENT_TXN_REJECTED`). Response `status` is the string enum name. schema: type: integer format: int32 enum: - 1 - 2 - 3 - 4 example: 2 - name: txn_id in: query required: false description: >- Filter general transactions by token (`txn_…`, exactly 40 characters). Used with `only_transactions=true`. schema: type: string example: txn_8ffa984c-f0cb-4835-8eee-89c9ca673dad - name: txn_status in: query required: false description: >- Filter general transactions by status integer enum (`1=TXN_LEDGER_POSTED`, `2=TXN_SETTLEMENT_SCHEDULED`, `3=TXN_SETTLEMENT_DISPATCHED`, `4=TXN_SETTLEMENT_CONFIRMED`, `5=TXN_SETTLEMENT_REVERSED`). Response `status` is the string enum name. schema: type: integer format: int32 enum: - 1 - 2 - 3 - 4 - 5 example: 4 responses: '200': $ref: '#/components/responses/ListSettlementTransactionsResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' 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 SettlementOpsCursorParam: name: cursor in: query required: false description: >- Cursor for pagination. Pass the previous response `next_cursor`, or omit/`0` for the first page. schema: type: integer format: int64 example: 0 SettlementOpsLimitParam: name: limit in: query required: false description: Page size. Default `30`. Maximum `100`. `0` is treated as the default. schema: type: integer format: int32 example: 30 SettlementOpsDirectionParam: name: direction in: query required: false description: >- Sort direction on the underlying numeric id. Must be uppercase `ASC` or `DESC`. Invalid or empty values default to `DESC`. schema: type: string enum: - ASC - DESC example: DESC responses: ListSettlementTransactionsResponse: description: Paginated list of settlement payouts or general transactions. content: application/json: schema: allOf: - $ref: '#/components/schemas/StandardResponse' - type: object properties: data: type: object properties: settlement_transactions: type: array items: $ref: '#/components/schemas/SettlementTransaction' transactions: type: array items: $ref: '#/components/schemas/SettlementOpsTransaction' next_cursor: type: string example: '49' count: $ref: '#/components/schemas/SettlementListCount' examples: SettlementTransactionsListed: value: api_version: v1 data: settlement_transactions: - id: '49' token: stxn_75549797-f2c6-421d-8dd7-ce39995534b8 settlement_batch_id: sb_1328a110-2cf5-4e13-993e-55792ec6b76c 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: '300' fee_amount: '0' net_amount: '294' sales_tax_on_fee_amount: '0' sales_tax_withholding_amount: '4' income_tax_withholding_amount: '2' 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-04-13T11:30:02Z' updated_at: '2026-04-13T11:30:04Z' transactions: [] next_cursor: '49' count: filtered_count: '1' total_count: '1' 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 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 SettlementListCount: type: object description: Count metadata for settlement list responses. properties: filtered_count: type: string description: Number of records matching the current filters. example: '1' total_count: type: string description: Total records in the same scope before optional filters. example: '5' 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 ````