Fetch Settlement Reports

Settlement reports provide detailed information about processed transactions that have been settled. These reports are essential for financial reconciliation, accounting, and auditing purposes.

Prerequisites

To fetch settlement reports, you need:

Requirement	Description
`partnerId`	Your unique partner identifier
`merchantId`	The merchant identifier for which to fetch reports
API credentials	Valid API-KEY, API-SECRET

Access Level

Settlement reports are available to merchants and partners. Partners can access reports for all their merchants, while merchants can only access their own reports.

Fetch Settlement Reports Flow

Retrieve Settlement Reports

List Reports

Fetch a list of settlement reports for a specific merchant.

$ curl -H 'Content-Type: application/json' \
>      -H 'API-KEY: YOUR_API_KEY' \
>      -H 'API-SECRET: YOUR_API_SECRET' \
>      -H 'MERCHANT-ID: YOUR_MERCHANT_ID' \
>      YOUR_API_URL/partners/:partnerId/merchants/:merchantId/reports

Query Parameters

Parameter	Type	Description
`startDate`	String	Start date for report range (YYYY-MM-DD)
`endDate`	String	End date for report range (YYYY-MM-DD)
`page`	Number	Page number for pagination
`pageSize`	Number	Number of reports per page (default: 20)

Example with Date Range

$ curl -H 'Content-Type: application/json' \
>      -H 'API-KEY: YOUR_API_KEY' \
>      -H 'API-SECRET: YOUR_API_SECRET' \
>      -H 'MERCHANT-ID: YOUR_MERCHANT_ID' \
>      "YOUR_API_URL/partners/:partnerId/merchants/:merchantId/reports?startDate=2024-01-01&endDate=2024-01-31"

Response Structure

Reports List Response

1 {
2   "reports": [
3     {
4       "reportId": "RPT-2024-001234",
5       "merchantId": "MERCH789",
6       "settlementDate": "2024-01-15",
7       "status": "COMPLETED",
8       "currency": "NOK",
9       "totalAmount": 125000.00,
10       "transactionCount": 156,
11       "fees": 2500.00,
12       "netAmount": 122500.00,
13       "createdAt": "2024-01-16T02:00:00Z"
14     },
15     {
16       "reportId": "RPT-2024-001235",
17       "merchantId": "MERCH789",
18       "settlementDate": "2024-01-16",
19       "status": "COMPLETED",
20       "currency": "NOK",
21       "totalAmount": 98500.00,
22       "transactionCount": 124,
23       "fees": 1970.00,
24       "netAmount": 96530.00,
25       "createdAt": "2024-01-17T02:00:00Z"
26     }
27   ],
28   "pagination": {
29     "currentPage": 1,
30     "pageSize": 20,
31     "totalPages": 5,
32     "totalReports": 92
33   }
34 }

Report Attributes

Attribute	Type	Description
`reportId`	String	Unique identifier for the settlement report
`merchantId`	String	Merchant identifier
`settlementDate`	String	Date of settlement (YYYY-MM-DD)
`status`	String	Report status (PENDING, COMPLETED, FAILED)
`currency`	String	Settlement currency (ISO 4217)
`totalAmount`	Number	Gross transaction amount
`transactionCount`	Number	Number of transactions in settlement
`fees`	Number	Total processing fees
`netAmount`	Number	Net amount after fees (totalAmount - fees)
`createdAt`	String	ISO 8601 timestamp when report was generated

Fetch Detailed Report

To get transaction-level details for a specific settlement report:

$ curl -H 'Content-Type: application/json' \
>      -H 'API-KEY: YOUR_API_KEY' \
>      -H 'API-SECRET: YOUR_API_SECRET' \
>      -H 'MERCHANT-ID: YOUR_MERCHANT_ID' \
>      YOUR_API_URL/reports/:reportId

Detailed Report Response

1 {
2   "reportId": "RPT-2024-001234",
3   "merchantId": "MERCH789",
4   "settlementDate": "2024-01-15",
5   "status": "COMPLETED",
6   "summary": {
7     "totalAmount": 125000.00,
8     "transactionCount": 156,
9     "fees": 2500.00,
10     "netAmount": 122500.00,
11     "currency": "NOK"
12   },
13   "breakdown": {
14     "sales": {
15       "count": 150,
16       "amount": 128000.00
17     },
18     "refunds": {
19       "count": 6,
20       "amount": -3000.00
21     }
22   },
23   "transactions": [
24     {
25       "paymentId": "550e8400-e29b-41d4-a716-446655440000",
26       "type": "SALE",
27       "amount": 850.00,
28       "fee": 17.00,
29       "netAmount": 833.00,
30       "timestamp": "2024-01-15T10:30:00Z",
31       "cardScheme": "VISA"
32     },
33     {
34       "paymentId": "550e8400-e29b-41d4-a716-446655440001",
35       "type": "REFUND",
36       "amount": -500.00,
37       "fee": 0.00,
38       "netAmount": -500.00,
39       "timestamp": "2024-01-15T11:45:00Z",
40       "cardScheme": "MASTERCARD"
41     }
42   ]
43 }

Transaction Types in Reports

Type	Description
`SALE`	Standard purchase transaction
`REFUND`	Refund transaction (negative amount)
`CHARGEBACK`	Disputed transaction
`ADJUSTMENT`	Manual adjustment
`FEE`	Processing fee deduction

Report Status Values

Status	Description
`PENDING`	Settlement in progress
`COMPLETED`	Settlement complete, funds transferred
`FAILED`	Settlement failed, requires investigation

Use Cases

1. Daily Reconciliation

1 async function dailyReconciliation(partnerId, merchantId, date) {
2   const reports = await fetch(
3     `${API_URL}/partners/${partnerId}/merchants/${merchantId}/reports?startDate=${date}&endDate=${date}`,
4     { headers: authHeaders }
5   ).then(r => r.json());
6   
7   const dailyReport = reports.reports[0];
8   
9   return {
10     date: dailyReport.settlementDate,
11     grossSales: dailyReport.totalAmount,
12     fees: dailyReport.fees,
13     netDeposit: dailyReport.netAmount,
14     transactionCount: dailyReport.transactionCount
15   };
16 }

2. Monthly Summary

1 async function monthlySummary(partnerId, merchantId, year, month) {
2   const startDate = `${year}-${month.toString().padStart(2, '0')}-01`;
3   const endDate = new Date(year, month, 0).toISOString().split('T')[0];
4   
5   const reports = await fetchAllReports(partnerId, merchantId, startDate, endDate);
6   
7   return {
8     period: `${year}-${month}`,
9     totalGross: reports.reduce((sum, r) => sum + r.totalAmount, 0),
10     totalFees: reports.reduce((sum, r) => sum + r.fees, 0),
11     totalNet: reports.reduce((sum, r) => sum + r.netAmount, 0),
12     totalTransactions: reports.reduce((sum, r) => sum + r.transactionCount, 0),
13     reportCount: reports.length
14   };
15 }

Export Formats

Settlement reports can be exported in multiple formats:

Format	Endpoint	Use Case
JSON	`/reports/:reportId`	API integration
CSV	`/reports/:reportId?format=csv`	Spreadsheet analysis
PDF	`/reports/:reportId?format=pdf`	Archival and printing

Error Handling

Report Not Found

1 {
2   "error": "REPORT_NOT_FOUND",
3   "message": "No settlement report found with the specified ID",
4   "reportId": "invalid-report-id"
5 }

Access Denied

1 {
2   "error": "ACCESS_DENIED",
3   "message": "You do not have permission to access this merchant's reports",
4   "merchantId": "MERCH789"
5 }

Invalid Date Range

1 {
2   "error": "INVALID_DATE_RANGE",
3   "message": "End date must be after start date",
4   "startDate": "2024-01-31",
5   "endDate": "2024-01-01"
6 }