Fetch a Settlement Queue Entry

Overview

Retrieve the details of a specific Settlement Queue Entry by its unique ID. Use this endpoint to check the status and timing of when a specific transaction, fee, or reversal will be settled.

Resource Access

User Permissions: Admin users only
Endpoint: GET /settlement_queue_entries/\{settlement_queue_entry_id}

Arguments

Parameter	Type	Required	Description
settlement_queue_entry_id	string	Yes	The unique ID of the Settlement Queue Entry

Example Request

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

Example Response (Pending Entry)

{
  "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"
    },
    "platform": {
      "href": "https://api.ahrvo.network/payments/na/platforms/PLplatformExample111"
    }
  }
}

Example Response (Released Entry)

{
  "id": "SQsettlementQueue456",
  "created_at": "2023-12-09T15:20:00Z",
  "updated_at": "2023-12-10T09:00:00Z",
  "application_id": "APapplicationExample456",
  "entity_id": "TRtransferExample789",
  "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/TRtransferExample789"
    },
    "merchant": {
      "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchantExample789"
    }
  }
}

Example Response (Settled Entry)

{
  "id": "SQsettlementQueue789",
  "created_at": "2023-12-08T10:00:00Z",
  "updated_at": "2023-12-09T11:30:00Z",
  "application_id": "APapplicationExample456",
  "entity_id": "TRtransferExample999",
  "entity_type": "TRANSFER",
  "merchant_id": "MUmerchantExample789",
  "platform_id": "PLplatformExample111",
  "ready_to_settle_after": "2023-12-09T10:00:00Z",
  "state": "SETTLED",
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/settlement_queue_entries/SQsettlementQueue789"
    },
    "transfer": {
      "href": "https://api.ahrvo.network/payments/na/transfers/TRtransferExample999"
    },
    "merchant": {
      "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchantExample789"
    },
    "settlement": {
      "href": "https://api.ahrvo.network/payments/na/settlements/STsettlementExample555"
    }
  }
}

Additional Information

State Lifecycle: Understanding the settlement queue progression
- PENDING → RELEASED → SETTLED: Normal flow
- PENDING → FAILED: Settlement processing error
- RELEASED → FAILED: Settlement batch failed
- State transitions are typically automated but can be influenced by manual actions
State Details:
- PENDING: Entry is queued, awaiting release
  - For AUTOMATIC mode merchants:
    - Entry will auto-release when current time reaches ready_to_settle_after
    - No manual action needed
    - Check ready_to_settle_after to predict release time
  - For MANUAL mode merchants:
    - Entry remains PENDING until explicitly released
    - Platform must call PUT /settlement_queue_entries to release
    - Used for fraud review, compliance checks, or custom approval workflows
  - Merchant has not received funds yet
  - Action: Wait for auto-release or manually release
- RELEASED: Entry has been released and will be in next settlement batch
  - Entry is queued for settlement processing
  - Typically settles within hours (depends on settlement schedule)
  - Merchant will receive funds soon
  - Action: Monitor for state change to SETTLED
- SETTLED: Entry has been processed in a settlement
  - Funds have been disbursed to merchant's bank account
  - Settlement is complete and successful
  - Link to Settlement resource available in _links.settlement
  - Action: None - process complete
- FAILED: Settlement processing failed
  - Common reasons:
    - Insufficient funds in reserve
    - Closed or invalid merchant bank account
    - Settlement batch error
    - Bank rejected transfer
    - Technical system error
  - Merchant has not received funds
  - Action: Investigate failure reason, resolve issue, retry settlement
Ready to Settle After: Critical timestamp for settlement timing
- Earliest time the entry can be released for settlement
- Calculated based on:
  - Transaction timestamp
  - Merchant's payout profile submission_delay_days
  - Business rules (e.g., new merchant holds)
  - Risk flags or manual holds
- Examples:
  - Transaction at 10:00 AM on Dec 10 + 1 day delay = ready_to_settle_after: 10:00 AM Dec 11
  - Transaction at 2:00 PM on Dec 10 + 2 day delay = ready_to_settle_after: 2:00 PM Dec 12
- Entry won't release before this time, even in AUTOMATIC mode
- Use this to answer "When will I get paid?" questions
Entity Types and Their Implications:
- TRANSFER: Payment transaction from customer to merchant
  - Most common type in queue
  - Positive settlement amount (merchant receives funds)
  - Examples: Card payment, ACH debit
- FEE: Platform or processing fee
  - Negative settlement amount (merchant pays fees)
  - May be settled separately or netted against transfers
  - Examples: Transaction fees, monthly fees, chargeback fees
- REVERSAL: Refund or chargeback
  - Negative settlement amount (merchant returns funds)
  - Examples: Customer refund, dispute reversal, ACH return
Timestamps:
- created_at: When entry was added to queue (typically when transaction completed)
- updated_at: When state or other fields were last modified
  - Changes when state transitions (PENDING → RELEASED → SETTLED)
  - Use to track when release or settlement occurred
- ready_to_settle_after: Earliest settlement eligibility time
Associated Resources:
- application_id: The Application this entry belongs to
- merchant_id: The Merchant who will receive/pay funds
- platform_id: The Platform managing the settlement
- entity_id: The specific Transfer, Fee, or Reversal being settled
Use Cases:
- Settlement Status Check:
  - Merchant asks "When will I receive payment for transaction X?"
  - Fetch queue entry by ID or lookup by entity_id
  - Check state and ready_to_settle_after
  - Provide specific timeline to merchant
- Troubleshooting Delayed Settlements:
  - Merchant reports missing payout
  - Fetch queue entry for the transaction
  - Check current state:
    - PENDING: Explain delay, check ready_to_settle_after
    - RELEASED: Settlement imminent, check settlement processing
    - SETTLED: Investigate why funds not received (bank issue?)
    - FAILED: Investigate failure, provide resolution steps
- Manual Release Decision:
  - For MANUAL mode merchants
  - Fetch PENDING entries
  - Review transaction details (fraud check, compliance)
  - Decide whether to release via PUT endpoint
- Settlement Reconciliation:
  - Match transactions to settlements
  - Verify all expected entries are SETTLED
  - Identify any FAILED or stuck PENDING entries
- Cash Flow Forecasting:
  - Check ready_to_settle_after for pending entries
  - Predict when merchant will receive funds
  - Plan for merchant liquidity
Manual Release Workflow (for MANUAL mode):
1. Fetch PENDING settlement queue entries
2. Review associated transaction (GET /transfers/{entity_id})
3. Perform fraud/compliance checks
4. If approved: Release via PUT /settlement_queue_entries
5. Monitor state change from PENDING → RELEASED → SETTLED
6. If rejected: Document reason, may need to reverse transaction
Related Resources: Use _links to navigate
- transfer: View the original transaction details (for TRANSFER type)
- fee: View fee details (for FEE type)
- reversal: View reversal details (for REVERSAL type)
- merchant: View merchant information
- application: View application context
- settlement: View settlement batch (only for SETTLED entries)
Settlement Timing Examples:
- Scenario 1: AUTOMATIC mode, 1-day delay
  - Transaction: Dec 10 at 10:00 AM
  - ready_to_settle_after: Dec 11 at 10:00 AM
  - State: PENDING until Dec 11 10:00 AM
  - State: RELEASED after Dec 11 10:00 AM
  - State: SETTLED within hours (same business day)
  - Merchant receives funds: Dec 11 or Dec 12 (depending on settlement batch and rail)
- Scenario 2: MANUAL mode, 2-day delay
  - Transaction: Dec 10 at 2:00 PM
  - ready_to_settle_after: Dec 12 at 2:00 PM
  - State: PENDING until manually released (stays PENDING even after Dec 12)
  - Manual action: Platform releases entry via PUT endpoint
  - State: RELEASED after manual release
  - State: SETTLED within hours
  - Merchant receives funds: Depends on when manually released
Failed Settlement Handling:
- When state is FAILED:
  1. Investigate root cause (check settlement, merchant bank account)
  2. Resolve issue (update bank account, add funds to reserve, etc.)
  3. System may automatically retry, or manual retry may be needed
  4. New queue entry may be created for retry
- Common failure reasons:
  - Bank account closed or invalid
  - Insufficient reserve balance
  - Bank rejected ACH transfer
  - Settlement batch processing error
Merchant Communication:
- PENDING: "Your payment is queued and will settle on [ready_to_settle_after date]"
- RELEASED: "Your payment has been released and will arrive within [X] business days"
- SETTLED: "Your payment was included in settlement [ID] on [date]"
- FAILED: "Settlement failed due to [reason]. We're working to resolve this."
Performance and Caching:
- Queue entry details are relatively stable
- Can cache SETTLED entries (state won't change)
- Poll PENDING/RELEASED entries periodically for state updates
- Use webhooks (if available) for real-time state change notifications
Security Considerations:
- Restrict access to admin/operations users
- Contains sensitive merchant settlement information
- Log all access for audit purposes
- Don't expose queue entry IDs to merchants (use Transfer IDs instead)

Overview​

Resource Access​

Arguments​

Example Request​

Example Response (Pending Entry)​

Example Response (Released Entry)​

Example Response (Settled Entry)​

Additional Information​

Overview

Resource Access

Arguments

Example Request

Example Response (Pending Entry)

Example Response (Released Entry)

Example Response (Settled Entry)

Additional Information