Skip to main content

Release Settlement Queue Entries

Overview​

Explicitly release one or more Settlement Queue Entries, allowing them to be processed in the next Settlement batch. This endpoint is primarily used when a merchant's settlement_queue_mode is set to MANUAL, requiring explicit approval before funds are disbursed.

Resource Access​

  • User Permissions: Admin users only (typically finance/operations team)
  • Endpoint: PUT /settlement_queue_entries

Arguments​

ParameterTypeRequiredDescription
idsarrayYesArray of Settlement Queue Entry IDs to release
actionstringYesThe action to perform (must be "RELEASE")

Example Request (Release Single Entry)​

curl -X PUT \
  'https://api.ahrvo.network/payments/na/settlement_queue_entries' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "ids": ["SQsettlementQueue123"],
    "action": "RELEASE"
  }'

Example Request (Release Multiple Entries)​

curl -X PUT \
  'https://api.ahrvo.network/payments/na/settlement_queue_entries' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "ids": [
      "SQsettlementQueue123",
      "SQsettlementQueue456",
      "SQsettlementQueue789",
      "SQsettlementQueue111",
      "SQsettlementQueue222"
    ],
    "action": "RELEASE"
  }'

Example Response​

HTTP/1.1 204 No Content

Additional Information​

  • HTTP 204 Response: Successful release returns 204 No Content
    • No response body
    • HTTP 204 indicates success
    • Entries have been released for settlement
    • Check entry state via GET endpoint to confirm transition to RELEASED
  • Manual vs Automatic Settlement Modes:
    • MANUAL Mode:
      • Merchant's settlement_queue_mode is set to MANUAL
      • Entries remain in PENDING state indefinitely until explicitly released
      • This endpoint is REQUIRED to release entries
      • Use cases:
        • High-risk merchants requiring approval
        • Merchants under review or probation
        • Custom settlement workflows (e.g., weekly batch releases)
        • Fraud prevention (manual review before payout)
        • New merchants during onboarding period
    • AUTOMATIC Mode (default):
      • Entries automatically release when ready_to_settle_after timestamp is reached
      • This endpoint is NOT typically needed
      • System handles release automatically
      • Standard for most merchants
  • Release Action: What happens when entries are released
    1. Entry state changes from PENDING → RELEASED
    2. Entry becomes eligible for next settlement batch
    3. Settlement processing system picks up RELEASED entries
    4. Entries are grouped into a Settlement resource
    5. Settlement is processed (funds disbursed via ACH, wire, etc.)
    6. Entry state changes from RELEASED → SETTLED
    7. Merchant receives funds in their bank account
  • Timing Considerations:
    • Entries must have reached ready_to_settle_after time
    • Attempting to release before this time may fail or be queued
    • Settlement batches run on schedules (daily, weekly, etc.)
    • Released entries settle in the next available batch
    • Actual fund arrival depends on:
      • Settlement batch schedule
      • Payment rail (NEXT_DAY_ACH, SAME_DAY_ACH, etc.)
      • Bank processing times
      • Weekends and holidays
  • Batch Release: Releasing multiple entries at once
    • Can release up to hundreds of entries in one request
    • Useful for:
      • Daily batch approval workflow
      • Releasing all approved transactions for a merchant
      • Scheduled release of accumulated entries
    • All entries in the array are released atomically
    • If one fails, entire request may fail (check implementation)
  • Use Cases:

    • Daily Review Workflow:

      1. Query PENDING entries: GET /settlement_queue_entries?state=PENDING
      2. Review each transaction for fraud/compliance
      3. Collect approved entry IDs
      4. Release approved batch via this endpoint
      5. Rejected entries remain PENDING or are handled separately

    • Merchant Under Review:

      • New merchant in probation period (first 30 days)
      • All settlements require manual approval
      • Review team checks transactions daily
      • Release legitimate transactions
      • Hold or reject suspicious activity

    • Custom Settlement Schedule:

      • Merchant wants weekly settlements (Friday only)
      • Entries accumulate in PENDING state all week
      • On Friday, release all entries at once
      • Merchant receives one weekly payout

    • Fraud Prevention:

      • High-value transaction flagged by risk rules
      • Entry held in PENDING for manual fraud review
      • After investigation, release if legitimate
      • Cancel or reverse if fraudulent

    • Compliance Hold:

      • Merchant under AML/KYC review
      • All settlements on hold pending compliance clearance
      • After clearance, release accumulated entries
      • Merchant receives back-dated settlements
  • Pre-Release Validation: Before releasing, verify:
    • Entry is in PENDING state (can't release SETTLED or FAILED entries)
    • ready_to_settle_after timestamp has passed
    • Associated transaction is valid (not reversed or disputed)
    • Merchant bank account is valid and active
    • No fraud or compliance flags requiring hold
    • Sufficient reserve balance (if applicable)
  • Post-Release Monitoring:
    • After release, entries should transition to RELEASED
    • Monitor for state change to SETTLED
    • If entry stays in RELEASED too long, investigate settlement processing
    • If entry transitions to FAILED, investigate failure reason
    • Typical timeline: RELEASED → SETTLED within hours to 1 business day
  • Error Handling:
    • Invalid entry ID: May return 400 Bad Request or ignore invalid IDs
    • Entry already RELEASED or SETTLED: May be ignored or return error
    • Entry in FAILED state: Typically cannot release without remediation
    • Permission denied: 403 Forbidden
    • System error: 500 Internal Server Error
  • Idempotency:
    • Releasing already-released entries is typically safe (idempotent)
    • System may ignore duplicate release requests
    • Check current state before releasing to avoid errors
  • Audit Trail:
    • Release actions should be logged for compliance
    • Track who released entries and when
    • Include rationale for release decision
    • Maintain audit trail for regulatory requirements
  • Merchant Communication: After releasing entries
    • Notify merchant that settlement is processing
    • Provide expected arrival date based on:
      • Settlement batch schedule
      • Payment rail timing
      • Bank processing times
    • Example: "Your payment will arrive in 1-2 business days"
  • Related Workflows:
    • Query: GET /settlement_queue_entries?state=PENDING (find entries to release)
    • Review: GET /transfers/{entity_id} (review transaction details)
    • Release: PUT /settlement_queue_entries (this endpoint)
    • Verify: GET /settlement_queue_entries/{id} (confirm state change)
    • Track: GET /settlements (view settlement batch)
  • Integration Patterns:

    • Manual Dashboard:

      • Display PENDING entries in UI
      • Allow reviewers to select entries
      • "Approve" button calls this endpoint
      • Show confirmation and state updates

    • Automated Rules:

      • Scheduled job queries PENDING entries
      • Apply business rules (amount limits, merchant history, etc.)
      • Auto-release low-risk entries
      • Flag high-risk entries for manual review

    • Workflow System:

      • Entries enter approval queue
      • Route to appropriate reviewer based on rules
      • Reviewer approves/rejects
      • Approved entries released via this endpoint
      • Tracking and notifications throughout
  • Best Practices:
    • Review Promptly: Don't keep entries in PENDING unnecessarily (impacts merchant cash flow)
    • Document Decisions: Use tags or external systems to document why entries were released or held
    • Batch Efficiently: Release multiple entries at once when possible
    • Validate First: Check entry state and ready_to_settle_after before releasing
    • Monitor Results: Verify state transitions to SETTLED
    • Handle Errors: Retry failed releases, investigate issues
    • Communicate: Keep merchants informed of settlement timing
    • Set SLAs: Define maximum time entries can remain PENDING
    • Audit Everything: Log all release actions for compliance
    • Automate When Safe: Use rules to auto-release low-risk entries
  • Risk Management:
    • Balance fraud prevention with merchant cash flow
    • Use risk scoring to prioritize reviews
    • Auto-release low-risk, manually review high-risk
    • Set thresholds for automatic vs manual release
    • Escalate unusual patterns or large amounts
  • Performance Considerations:
    • Can release hundreds of entries in one request
    • For thousands, consider batching into multiple requests
    • Monitor response times for large batches
    • Consider asynchronous processing for very large volumes
  • Security:
    • Restrict access to authorized personnel only
    • Require strong authentication
    • Log all release actions with user attribution
    • Consider dual approval for high-value releases
    • Monitor for unusual release patterns
  • Compliance:
    • Maintain audit trail of all releases
    • Document rationale for holds and releases
    • Ensure AML/KYC checks completed before release
    • Follow regulatory requirements for fund disbursement
    • Retain records for required retention period