Settlement Operations
List Settlement Transactions
Changed onList 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.
get/v1/aggregators/{raast-aggregator-id}/settlements/transactions
Request
- Base URL: https://api.getsafepay.com/raastwire
- URL: https://api.getsafepay.com/raastwire/v1/aggregators/{raast-aggregator-id}/settlements/transactions
- Auth: API key in header X-SFPY-AGGREGATOR-SECRET-KEY
Query parameters
cursorinteger
Cursor for pagination. Pass the previous response next_cursor, or omit/0 for the first page.
limitinteger
Example:30
Page size. Default 30. Maximum 100. 0 is treated as the default.
direction'ASC' | 'DESC'
Example:DESC
Sort direction on the underlying numeric id. Must be uppercase ASC or DESC. Invalid or empty values default to DESC.
only_transactionsboolean
When true, return general payment/refund transactions in transactions instead of settlement payouts in settlement_transactions.
settlement_batch_idstring
Example:sb_1328a110-2cf5-4e13-993e-55792ec6b76c
Filter by settlement batch token (sb_…).
settlement_txn_idstring
Example:stxn_75549797-f2c6-421d-8dd7-ce39995534b8
Filter by settlement transaction token (stxn_…, exactly 41 characters).
settlement_txn_status1 | 2 | 3 | 4
Example:2
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.
txn_idstring
Example:txn_8ffa984c-f0cb-4835-8eee-89c9ca673dad
Filter general transactions by token (txn_…, exactly 40 characters). Used with only_transactions=true.
txn_status1 | 2 | 3 | 4 | 5
Example:4
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.
Response
Paginated list of settlement payouts or general transactions.
Example response
{
"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",
"created_at": "2025-03-13T09:12:34Z",
"updated_at": "2025-03-13T09:12:34Z",
"settlement_batch": {
"id": "200",
"token": "sb_1328a110-2cf5-4e13-993e-55792ec6b76c",
"date": "2025-03-13T09:12:34Z",
"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": "2025-03-13T09:12:34Z"
}
],
"settlement_snapshots": [
{
"id": "44",
"batch_id": "sb_1328a110-2cf5-4e13-993e-55792ec6b76c",
"settlement_transaction_id": "stxn_9d5bd7bd-863a-487f-944c-f15d30d9bbc5",
"merchant_id": "mer_ce6df98c-cdde-48bf-bc32-464cecac2ee3",
"aggregator_id": "agg_b49985f2-e099-412e-8eb2-98756059cc0d",
"iban": "PK36SCBL0000001123456702",
"account_title": "OPTIVOLVE DIGITAL",
"gross_amount": "7900",
"net_amount": "7620",
"fee_amount": "39",
"sales_tax_on_fee_amount": "4",
"sales_tax_withholding_amount": "158",
"income_tax_withholding_amount": "79",
"digital_tax_amount": "0",
"currency": "PKR",
"created_at": "2025-03-13T09:12:34Z"
}
],
"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": "2025-03-13T09:12:34Z"
},
"created_at": "2025-03-13T09:12:34Z"
}
}
],
"transactions": [
{
"id": "160",
"token": "txn_8ffa984c-f0cb-4835-8eee-89c9ca673dad",
"payment_id": "pm_e950c9fc-9532-4f4b-aa4c-d39b8f2619c6",
"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",
"creditor_account_id": "acct_7f073fa9-e248-4f96-8e7c-99ddcd282124",
"latest_batch_id": "sb_1328a110-2cf5-4e13-993e-55792ec6b76c",
"partner_id": "partner_37e414c3-c0cc-4541-9bea-ab5a22964bd8",
"created_at": "2025-03-13T09:12:34Z",
"updated_at": "2025-03-13T09:12:34Z",
"latest_batch": {
"id": "200",
"token": "sb_1328a110-2cf5-4e13-993e-55792ec6b76c",
"date": "2025-03-13T09:12:34Z",
"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": "2025-03-13T09:12:34Z"
}
],
"settlement_snapshots": [
{
"id": "44",
"batch_id": "sb_1328a110-2cf5-4e13-993e-55792ec6b76c",
"settlement_transaction_id": "stxn_9d5bd7bd-863a-487f-944c-f15d30d9bbc5",
"merchant_id": "mer_ce6df98c-cdde-48bf-bc32-464cecac2ee3",
"aggregator_id": "agg_b49985f2-e099-412e-8eb2-98756059cc0d",
"iban": "PK36SCBL0000001123456702",
"account_title": "OPTIVOLVE DIGITAL",
"gross_amount": "7900",
"net_amount": "7620",
"fee_amount": "39",
"sales_tax_on_fee_amount": "4",
"sales_tax_withholding_amount": "158",
"income_tax_withholding_amount": "79",
"digital_tax_amount": "0",
"currency": "PKR",
"created_at": "2025-03-13T09:12:34Z"
}
],
"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": "2025-03-13T09:12:34Z"
},
"created_at": "2025-03-13T09:12:34Z"
}
}
],
"next_cursor": "49",
"count": {
"filtered_count": "1",
"total_count": "5"
}
}
}Changes
- info
endpoint added
- info