Fetch a Settlement

Overview

Retrieve the details of a specific Settlement by its unique ID. View the settlement status, amounts, time window, and links to associated entries and funding transfers.

Resource Access

User Permissions: Admin users only
Endpoint: GET /settlements/\{settlement_id}

Arguments

Parameter	Type	Required	Description
settlement_id	string	Yes	The unique ID of the Settlement

Example Request

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

Example Response (Approved Settlement)

{
  "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"
    },
    "application": {
      "href": "https://api.ahrvo.network/payments/na/applications/APapplicationExample456"
    },
    "entries": {
      "href": "https://api.ahrvo.network/payments/na/settlements/STsettlementExample123/entries"
    },
    "funding_transfers": {
      "href": "https://api.ahrvo.network/payments/na/settlements/STsettlementExample123/funding_transfers"
    }
  }
}

Example Response (Pending Settlement)

{
  "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": false,
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/settlements/STsettlementExample789"
    },
    "merchant": {
      "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchantExample222"
    },
    "entries": {
      "href": "https://api.ahrvo.network/payments/na/settlements/STsettlementExample789/entries"
    }
  }
}

Additional Information

Use this endpoint to: Get complete settlement details for reconciliation, customer support, or audit purposes
Settlement Status Meanings:
- PENDING: Settlement is currently open and accruing transactions
  - Still collecting transfers released from settlement queue
  - window_end_time is null (no end time set yet)
  - Amounts may change as new transactions are added
  - Can be manually closed via PUT /settlements/{id} endpoint
- AWAITING_APPROVAL: Settlement window closed, pending approval
  - No longer accepting new transactions
  - window_end_time is set (settlement window completed)
  - Amounts are final
  - Waiting for automatic or manual approval
- APPROVED: Settlement approved and funds being disbursed
  - Funding transfers have been created (see _links.funding_transfers)
  - ACH/wire transfer initiated to merchant bank account
  - Merchant will receive net_amount according to payout profile
  - Final successful state
Settlement Amounts Explained:
- total_amount: Total merchant revenue (in cents)
  - Sum of all DEBIT transfers (customer payments)
  - Does not include refunds (those reduce the total)
  - Example: $100.00 = 10000 cents
- total_fee: Total fees deducted (in cents)
  - Platform fees + transaction fees + processing fees
  - Example: $5.50 = 550 cents
- net_amount: Actual payout to merchant (in cents)
  - Formula: total_amount - total_fee
  - This is what merchant receives in their bank account
  - Example: $94.50 = 9450 cents
- NET vs GROSS settlements:
  - NET: Single transfer of net_amount to merchant
  - GROSS: Separate transfers for total_amount (credit) and total_fee (debit)
Settlement Window: Time period covered
- window_start_time: Beginning of settlement period
- window_end_time: End of settlement period
  - Null for PENDING settlements (still open)
  - Set when settlement closes (AWAITING_APPROVAL, APPROVED)
- Typical daily settlement: 00:00:00 to 23:59:59 of same day
- Window determined by merchant's payout profile frequency
Exception Settlements:
- is_exception: true means settlement created outside normal schedule
- Reasons for exception settlements:
  - Manual settlement creation
  - Error correction or adjustment
  - Instant payout request
  - Special merchant arrangement
- Review these carefully during reconciliation
Processor Information:
- processor: Payment processor handling settlement
- Examples: LITLE_V1, VANTIV_V1, MASTERCARD_V1
- Affects settlement timing and available payout options
- Different processors may have different schedules
Currency: All amounts in cents of this currency
- Typically USD for US merchants
- Settlement only includes transactions in same currency
- Multi-currency merchants have separate settlements per currency
Timestamps:
- created_at: When settlement was first created (PENDING state)
- updated_at: Last modification time
  - Changes when transactions added, status changes, etc.
  - Use to track when settlement was approved
Related Resources via _links:
- entries: View all transactions included in settlement
  - GET /settlements/{id}/entries
  - Shows individual transfers, fees, reversals
- funding_transfers: View ACH/wire transfers (APPROVED settlements only)
  - GET /settlements/{id}/funding_transfers
  - Shows actual bank transfers sending funds
- merchant: View merchant details
- application: View application context
Use Cases:
- Merchant Support - "Where's my money?":
  1. Fetch settlement by ID
  2. Check status:
    - PENDING: "Still collecting transactions for today"
    - AWAITING_APPROVAL: "Settlement processing, funds coming soon"
    - APPROVED: "Funds sent, check funding_transfers for details"
  3. Provide net_amount and expected arrival time
- Reconciliation:
  1. Fetch settlement details
  2. Verify total_amount matches transaction records
  3. Verify total_fee matches fee calculations
  4. Check window times match expected period
  5. Match to bank transfers
- Dispute Investigation:
  1. Merchant disputes settlement amount
  2. Fetch settlement details
  3. Review entries via _links.entries
  4. Identify specific transactions causing issue
  5. Explain fees and calculations
Settlement Lifecycle:
- PENDING → AWAITING_APPROVAL: Settlement window closes
- AWAITING_APPROVAL → APPROVED: Automatic or manual approval
- APPROVED: Final state, funds disbursed
Calculating Fee Percentage:
- Fee % = (total_fee / total_amount) × 100
- Example: (550 / 10000) × 100 = 5.5% effective fee rate
Verifying Settlement:
- Check net_amount matches what merchant expects
- Verify window_start_time and window_end_time match schedule
- Confirm status is APPROVED for completed settlements
- Review entries to see transaction breakdown
- Check funding_transfers to see actual bank transfer
When to Manually Close: If settlement is PENDING and you need to force closure
- Use PUT /settlements/{id} with action: STOP_ACCRUAL
- Useful for end-of-day processing or special circumstances
Common Issues:
- Missing transactions: Check if they were released from settlement queue
- Unexpected fees: Review entries to see fee breakdown
- Wrong amount: Verify transaction totals and fee calculations
- Delayed funding: Check status and funding_transfers
Best Practices:
- Fetch settlement before making modifications
- Use entries endpoint to see full transaction list
- Check status before taking actions (can't modify APPROVED settlements)
- Document exception settlements (is_exception: true)
- Match settlements to bank transfers for reconciliation
- Monitor updated_at to track processing timeline

Overview​

Resource Access​

Arguments​

Example Request​

Example Response (Approved Settlement)​

Example Response (Pending Settlement)​

Additional Information​

Overview

Resource Access

Arguments

Example Request

Example Response (Approved Settlement)

Example Response (Pending Settlement)

Additional Information