List All Settlements

Overview

Retrieve a list of all Settlements across your platform or application. Settlements batch financial activities (Transfers, Fees, Reversals) for merchants, calculate net payouts, and manage the funding process.

Resource Access

User Permissions: Admin users only
Endpoint: GET /settlements

Arguments

Parameter	Type	Required	Description
limit	integer	No	Maximum number of records to return (default: 10)
status	string	No	Filter by status: APPROVED, AWAITING_APPROVAL, or PENDING
merchant_id	string	No	Filter by Merchant ID
total_amount.gte	integer	No	Filter by minimum total amount (in cents)

Example Request (All Settlements)

curl -X GET \
  'https://api.ahrvo.network/payments/na/settlements?limit=20' \
  -u username:password \
  -H 'Content-Type: application/json'

Example Request (Filter by Merchant and Status)

curl -X GET \
  'https://api.ahrvo.network/payments/na/settlements?merchant_id=MUmerchantExample123&status=APPROVED' \
  -u username:password \
  -H 'Content-Type: application/json'

Example Response

{
  "_embedded": {
    "settlements": [
      {
        "id": "STsettlementExample123",
        "created_at": "2023-12-10T10:00:00Z",
        "updated_at": "2023-12-10T11:30:00Z",
        "application": "APapplicationExample456",
        "merchant_id": "MUmerchantExample789",
        "processor": "LITLE_V1",
        "currency": "USD",
        "status": "APPROVED",
        "net_amount": 9450,
        "total_amount": 10000,
        "total_fee": 550,
        "type": "MERCHANT_REVENUE",
        "window_start_time": "2023-12-09T00:00:00Z",
        "window_end_time": "2023-12-10T00:00:00Z",
        "is_exception": false,
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/settlements/STsettlementExample123"
          },
          "merchant": {
            "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchantExample789"
          },
          "entries": {
            "href": "https://api.ahrvo.network/payments/na/settlements/STsettlementExample123/entries"
          },
          "funding_transfers": {
            "href": "https://api.ahrvo.network/payments/na/settlements/STsettlementExample123/funding_transfers"
          }
        }
      },
      {
        "id": "STsettlementExample456",
        "created_at": "2023-12-10T09:00:00Z",
        "updated_at": "2023-12-10T09:00:00Z",
        "application": "APapplicationExample456",
        "merchant_id": "MUmerchantExample111",
        "processor": "VANTIV_V1",
        "currency": "USD",
        "status": "AWAITING_APPROVAL",
        "net_amount": 24750,
        "total_amount": 25000,
        "total_fee": 250,
        "type": "MERCHANT_REVENUE",
        "window_start_time": "2023-12-09T00:00:00Z",
        "window_end_time": "2023-12-10T00:00:00Z",
        "is_exception": false,
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/settlements/STsettlementExample456"
          },
          "merchant": {
            "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchantExample111"
          }
        }
      },
      {
        "id": "STsettlementExample789",
        "created_at": "2023-12-10T08:00:00Z",
        "updated_at": "2023-12-10T14:20:00Z",
        "application": "APapplicationExample456",
        "merchant_id": "MUmerchantExample222",
        "processor": "LITLE_V1",
        "currency": "USD",
        "status": "PENDING",
        "net_amount": 15200,
        "total_amount": 16000,
        "total_fee": 800,
        "type": "MERCHANT_REVENUE",
        "window_start_time": "2023-12-10T00:00:00Z",
        "window_end_time": null,
        "is_exception": true,
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/settlements/STsettlementExample789"
          },
          "merchant": {
            "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchantExample222"
          }
        }
      }
    ]
  },
  "page": {
    "offset": 0,
    "limit": 20,
    "count": 3
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/settlements?limit=20"
    }
  }
}

Additional Information

Settlement Overview: Settlements are batch payouts to merchants
- Groups transactions from a time window (typically 1 day)
- Calculates total revenue, fees, and net payout amount
- Initiates funds transfer to merchant's bank account
- Critical for merchant cash flow and reconciliation
Settlement Statuses:
- PENDING: Settlement is still open and accruing transactions
  - Actively collecting transfers, fees, and reversals
  - window_end_time is null (settlement still open)
  - Can be manually closed via PUT endpoint
  - Transactions continue to be added automatically
- AWAITING_APPROVAL: Settlement is closed and waiting for approval
  - No longer accruing new transactions
  - window_end_time is set (settlement window closed)
  - Pending review or automatic approval processing
  - Next step: Transition to APPROVED
- APPROVED: Settlement has been approved and funds are being disbursed
  - Funding transfers have been created
  - ACH, wire, or other payment rail initiated
  - Merchant will receive funds according to payout profile
  - Final state for successful settlements
Settlement Amounts:
- total_amount: Sum of all DEBIT transfers (merchant revenue) in cents
  - Customer payments captured by merchant
  - Positive amount (funds coming to merchant)
- total_fee: Sum of all fees deducted in cents
  - Platform fees, transaction fees, processing fees
  - Reduces the net payout
- net_amount: Amount actually paid to merchant (total_amount - total_fee)
  - For NET settlements: This is the single transfer amount
  - For GROSS settlements: Separate transfers for revenue and fees
  - Amount in cents
Settlement Types:
- MERCHANT_REVENUE: Standard merchant payout (most common)
  - Settles merchant's transaction revenue
  - Includes debits (sales), credits (refunds), and fees
- Other types may exist for platform-level settlements
Settlement Windows: Time period covered by the settlement
- window_start_time: Beginning of settlement period
- window_end_time: End of settlement period (null if still open)
- Typical windows:
  - Daily: 00:00:00 to 23:59:59 of a single day
  - Weekly: Monday 00:00:00 to Sunday 23:59:59
  - Custom: Based on merchant's payout profile
Exception Settlements:
- is_exception: true indicates an out-of-band settlement
- Created outside normal settlement schedule
- Reasons:
  - Manual settlement requested
  - Error correction
  - Special merchant arrangement
  - Instant payout
- Review these carefully for reconciliation
Processor: Payment processor handling the settlement
- Examples: LITLE_V1, VANTIV_V1, MASTERCARD_V1, DUMMY_V1
- Determines settlement timing and rails
- May affect available payout options
Currency: Three-letter ISO currency code
- Typically USD for US merchants
- All amounts in the settlement use this currency
- Multi-currency settlements are separate
Use Cases:
- Daily Reconciliation: List all APPROVED settlements for accounting
- Operations Dashboard: Monitor AWAITING_APPROVAL settlements
- Merchant Support: Look up settlements for "Where's my money?" inquiries
- Reporting: Generate settlement reports by merchant or date range
- Audit Trail: Review all settlements for compliance
- Cash Flow Forecasting: Check PENDING and AWAITING_APPROVAL for upcoming payouts
Filtering Best Practices:
- Filter by merchant_id for merchant-specific inquiries
- Filter by status=AWAITING_APPROVAL for pending approvals
- Filter by status=APPROVED for processed settlements
- Use total_amount.gte to find large settlements
- Combine filters for targeted queries
Pagination:
- Default limit is 10 settlements
- Increase for dashboards and reports
- Use cursor-based pagination for large result sets
Settlement Lifecycle:
1. Creation: Settlement created in PENDING status
2. Accrual: Transactions added to settlement as they're released from queue
3. Closure: Settlement window ends (automatic or manual)
  - Status → AWAITING_APPROVAL
  - window_end_time is set
4. Approval: Settlement is approved (automatic or manual)
  - Status → APPROVED
  - Funding transfers created
5. Funding: ACH/wire transfer initiated to merchant bank account
6. Completion: Funds arrive in merchant's account
Relationship to Other Resources:
- Settlement Entries: Individual transactions in the settlement
  - Use GET /settlements/{id}/entries to list
- Funding Transfers: ACH/wire transfers sending funds
  - Use GET /settlements/{id}/funding_transfers to list
- Settlement Queue Entries: Transactions waiting to be included
  - Released entries are added to settlements
Common Workflows:
1. Check Settlement Status:
  - Merchant: "When will I get paid?"
  - Query settlements for merchant: ?merchant_id=MU...
  - Check status and net_amount
  - Provide expected arrival date based on status and payout profile
2. Daily Settlement Review:
  - Query: ?status=AWAITING_APPROVAL
  - Review settlements pending approval
  - Approve or investigate flagged settlements
  - Monitor for errors or holds
3. Reconciliation:
  - Query approved settlements for date range
  - Match to bank transfers
  - Verify amounts and fees
  - Identify discrepancies
Performance Considerations:
- Large platforms may have thousands of settlements
- Always use filters to narrow results
- Index by merchant_id and status for fast queries
- Cache settlement lists for dashboards
- Use pagination for large result sets
Related Endpoints:
- GET /settlements/{id}: Fetch specific settlement details
- PUT /settlements/{id}: Close an open settlement (stop accrual)
- GET /settlements/{id}/entries: List all transactions in settlement
- GET /settlements/{id}/funding_transfers: List payout transfers
- DELETE /settlements/{id}/entries: Remove transactions before funding
Best Practices:
- Monitor AWAITING_APPROVAL settlements daily
- Investigate exception settlements (is_exception: true)
- Track settlement timing for merchant expectations
- Reconcile approved settlements with bank transfers
- Use merchant_id filter for support inquiries
- Set up alerts for failed or delayed settlements
- Maintain audit trail for all settlement changes
- Communicate settlement status to merchants

Overview​

Resource Access​

Arguments​

Example Request (All Settlements)​

Example Request (Filter by Merchant and Status)​

Example Response​

Additional Information​