List Settlement Queue Entries

Overview

Retrieve a list of Settlement Queue Entry resources, which track when and how financial events (Transfers, Fees, or Reversals) are queued for settlement. This is especially important for merchants with manual settlement queuing enabled.

Resource Access

User Permissions: Admin users only
Endpoint: GET /settlement_queue_entries

Arguments

Parameter	Type	Required	Description
entity_id	string	Yes	Filter by the entity_id of the queued resource (Transfer ID, Fee ID, or Reversal ID)
entity_type	string	Yes	Filter by entity type: TRANSFER, FEE, or REVERSAL
limit	integer	No	Maximum number of records to return (default: 10)
state	string	No	Filter by state: PENDING, RELEASED, SETTLED, or FAILED

Example Request (Check Transfer Settlement Status)

curl -X GET \
  'https://api.ahrvo.network/payments/na/settlement_queue_entries?entity_id=TRtransferExample123&entity_type=TRANSFER' \
  -u username:password \
  -H 'Content-Type: application/json'

Example Request (List Pending Entries)

curl -X GET \
  'https://api.ahrvo.network/payments/na/settlement_queue_entries?entity_id=TRtransferExample123&entity_type=TRANSFER&state=PENDING' \
  -u username:password \
  -H 'Content-Type: application/json'

Example Response

{
  "_embedded": {
    "settlement_queue_entries": [
      {
        "id": "SQsettlementQueue123",
        "created_at": "2023-12-10T10:30:00Z",
        "updated_at": "2023-12-10T10:30:00Z",
        "application_id": "APapplicationExample456",
        "entity_id": "TRtransferExample123",
        "entity_type": "TRANSFER",
        "merchant_id": "MUmerchantExample789",
        "platform_id": "PLplatformExample111",
        "ready_to_settle_after": "2023-12-11T10:30:00Z",
        "state": "PENDING",
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/settlement_queue_entries/SQsettlementQueue123"
          },
          "transfer": {
            "href": "https://api.ahrvo.network/payments/na/transfers/TRtransferExample123"
          },
          "merchant": {
            "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchantExample789"
          },
          "application": {
            "href": "https://api.ahrvo.network/payments/na/applications/APapplicationExample456"
          }
        }
      },
      {
        "id": "SQsettlementQueue456",
        "created_at": "2023-12-09T15:20:00Z",
        "updated_at": "2023-12-10T09:00:00Z",
        "application_id": "APapplicationExample456",
        "entity_id": "TRtransferExample123",
        "entity_type": "TRANSFER",
        "merchant_id": "MUmerchantExample789",
        "platform_id": "PLplatformExample111",
        "ready_to_settle_after": "2023-12-10T15:20:00Z",
        "state": "RELEASED",
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/settlement_queue_entries/SQsettlementQueue456"
          },
          "transfer": {
            "href": "https://api.ahrvo.network/payments/na/transfers/TRtransferExample123"
          },
          "merchant": {
            "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchantExample789"
          }
        }
      }
    ]
  },
  "page": {
    "offset": 0,
    "limit": 10,
    "count": 2
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/settlement_queue_entries?entity_id=TRtransferExample123&entity_type=TRANSFER"
    }
  }
}

Additional Information

Settlement Queue Overview:
- The settlement queue manages when funds from transactions are disbursed to merchants
- Each transaction (Transfer), fee, or reversal creates a queue entry
- Queue entries track the lifecycle from creation through settlement
- Critical for cash flow management and reconciliation
Entity Types:
- TRANSFER: Represents a payment transaction
  - Most common type in settlement queue
  - Funds from customer payments to merchant
  - Includes card transactions, ACH debits, etc.
- FEE: Represents platform or processing fees
  - Fees collected from merchants
  - May be settled separately from transfers
  - Examples: Transaction fees, monthly fees, chargeback fees
- REVERSAL: Represents refunds or chargebacks
  - Returns funds from merchant back to customer or platform
  - Negative settlement amount
  - Examples: Refunds, disputes, reversals
Settlement Queue States:
- PENDING: Entry is in queue, waiting for release
  - Default state when entry is created
  - For AUTOMATIC mode: Will auto-release when ready_to_settle_after is reached
  - For MANUAL mode: Requires explicit release via PUT endpoint
  - Merchant won't receive funds until released
- RELEASED: Entry has been released for settlement
  - Will be included in next settlement batch
  - Transition from PENDING to RELEASED happens:
    - Automatically (AUTOMATIC mode) when ready_to_settle_after is reached
    - Manually (MANUAL mode) via PUT /settlement_queue_entries
  - Settlement is imminent
- SETTLED: Entry has been processed in a settlement
  - Funds have been disbursed to merchant
  - Final successful state
  - Associated with a Settlement resource
  - No further action needed
- FAILED: Settlement processing failed
  - May occur due to insufficient funds, closed bank account, etc.
  - Requires investigation and remediation
  - May need to retry or take corrective action
Settlement Queue Modes: Merchants can have different queue modes
- AUTOMATIC (default):
  - Entries automatically release when ready_to_settle_after is reached
  - No manual intervention required
  - Best for most merchants (predictable cash flow)
- MANUAL:
  - Entries remain PENDING until explicitly released
  - Platform must call PUT /settlement_queue_entries to release
  - Useful for:
    - Merchants under review or probation
    - High-risk merchants requiring approval
    - Custom settlement schedules
    - Fraud prevention (manual review before payout)
Ready to Settle After: Timestamp indicating earliest settlement time
- Determined by merchant's payout profile and submission delays
- Example: Transaction on Dec 10, with 1-day delay → ready_to_settle_after is Dec 11
- Accounts for:
  - Risk holds (submission_delay_days in payout profile)
  - Processing windows
  - Business rules (e.g., first settlement delay for new merchants)
- Entry won't be released before this time, even in AUTOMATIC mode
Required Filters:
- Both entity_id and entity_type are required
- This prevents accidentally fetching all queue entries
- Ensures queries are targeted and efficient
Use Cases:
- Settlement Status Tracking: Check when a specific transfer will settle
- Cash Flow Forecasting: See pending settlements and timing
- Manual Queue Management: List PENDING items for manual release
- Reconciliation: Verify which transactions have been settled
- Troubleshooting: Investigate why settlements are delayed (check state and ready_to_settle_after)
- Merchant Support: Answer "When will I get paid?" questions
- Platform Operations: Monitor settlement queue health and backlogs
Common Workflows:
1. Check Transfer Status:
  - Customer asks when funds will be available
  - Query by entity_id (Transfer ID) and entity_type=TRANSFER
  - Check state and ready_to_settle_after
  - Communicate expected settlement date
2. Manual Release (for MANUAL mode merchants):
  - Query with state=PENDING to find entries waiting
  - Review transactions (fraud check, compliance review)
  - Release approved entries via PUT endpoint
  - Monitor for state change to RELEASED → SETTLED
3. Troubleshooting Delayed Settlements:
  - Merchant reports missing payout
  - Query settlement queue entries for their recent transfers
  - Check state:
    - PENDING: Still waiting for release (check ready_to_settle_after)
    - RELEASED: Should settle soon
    - FAILED: Investigate failure reason
  - Take corrective action based on findings
Pagination:
- Default limit is 10
- Increase for bulk operations or dashboards
- Use cursor pagination for large result sets
Filtering Best Practices:
- Always specify entity_id and entity_type (required)
- Add state filter to narrow results (e.g., state=PENDING for actionable items)
- Filter by merchant_id if you need all entries for a merchant
- Use date filters (if available) for time-based queries
Timestamps:
- created_at: When entry was added to queue (typically same as transaction time)
- updated_at: When state or other fields were last modified
- ready_to_settle_after: Earliest settlement time (driven by payout profile)
Multiple Entries: A single transaction may have multiple queue entries
- Each settlement attempt creates a new entry
- Failed settlements may be retried (creating new entries)
- Check state to identify the current active entry
Relationship to Settlements:
- Queue entries are grouped into Settlement resources
- Multiple queue entries → One Settlement (batch)
- Settlement created when entries transition from RELEASED to SETTLED
- Use Settlement ID to see all entries in a batch
Performance Considerations:
- Queries are indexed by entity_id and entity_type (fast)
- Avoid broad queries without filters
- Cache results for frequently accessed data
- Use pagination for large result sets
Security and Access:
- Only admin users can access queue entries
- Merchant-level users typically can't see queue details
- Protect this data - contains settlement timing and amounts
Related Endpoints:
- GET /settlement_queue_entries/{id}: Fetch specific entry details
- PUT /settlement_queue_entries: Release entries for settlement
- GET /settlements: View settlement batches
- GET /transfers/{id}: View associated transfer
Best Practices:
- Monitor PENDING queue depth for MANUAL mode merchants
- Set up alerts for FAILED entries
- Release MANUAL entries promptly (merchant cash flow)
- Use ready_to_settle_after for accurate settlement forecasting
- Document why entries are held (for MANUAL mode)
- Review FAILED entries regularly and resolve issues
- Provide merchants visibility into settlement timing

Overview​

Resource Access​

Arguments​

Example Request (Check Transfer Settlement Status)​

Example Request (List Pending Entries)​

Example Response​

Additional Information​