Update a Review Queue Item (Set Outcome)

Overview

Manually update the outcome of a Review Queue Item to approve, reject, or escalate the review. This action directly influences whether the associated settlement processes, identity activates, or fee applies.

Resource Access

User Permissions: Admin users only (typically compliance/risk team)
Endpoint: PUT /review_queue/\{review_queue_item_id}

Arguments

Parameter	Type	Required	Description
review_queue_item_id	string	Yes (path)	The unique ID of the Review Queue Item
outcome	string	Yes	The new outcome: ACCEPTED, REJECTED, MANUAL_REVIEW, or PENDING
tags	object	No	Optional tags to update on the resource

Example Request (Accept a Settlement)

curl -X PUT \
  'https://api.ahrvo.network/payments/na/review_queue/RQreviewQueue123' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "outcome": "ACCEPTED",
    "tags": {
      "priority": "high",
      "merchant_name": "Acme Corp",
      "reviewer_notes": "Verified merchant history, approved for settlement",
      "approved_by": "John Doe"
    }
  }'

Example Request (Reject a Settlement)

curl -X PUT \
  'https://api.ahrvo.network/payments/na/review_queue/RQreviewQueue456' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "outcome": "REJECTED",
    "tags": {
      "priority": "high",
      "merchant_name": "Risky Merchant LLC",
      "rejection_reason": "Exceeded velocity limits",
      "rejection_details": "Merchant exceeded 30-day volume limit by 200%",
      "rejected_by": "Jane Smith"
    }
  }'

Example Request (Escalate for Manual Review)

curl -X PUT \
  'https://api.ahrvo.network/payments/na/review_queue/RQreviewQueue789' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "outcome": "MANUAL_REVIEW",
    "tags": {
      "priority": "critical",
      "merchant_name": "Complex Case Inc",
      "escalation_reason": "Requires legal review due to regulatory concerns",
      "assigned_to": "compliance-manager",
      "case_id": "CASE-2023-12345"
    }
  }'

Example Response (Accepted)

{
  "id": "RQreviewQueue123",
  "created_at": "2023-12-10T10:30:00Z",
  "updated_at": "2023-12-10T14:45:00Z",
  "application": "APapplicationExample456",
  "completed_at": "2023-12-10T14:45:00Z",
  "entity_id": "STsettlementExample789",
  "entity_type": "SETTLEMENT_V2",
  "outcome": "ACCEPTED",
  "outcome_reason": [],
  "processor_type": "LITLE_V1",
  "review_type": "CREATED",
  "reviewed_by": "USuserExample222",
  "tags": {
    "priority": "high",
    "merchant_name": "Acme Corp",
    "reviewer_notes": "Verified merchant history, approved for settlement",
    "approved_by": "John Doe"
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/review_queue/RQreviewQueue123"
    },
    "settlement": {
      "href": "https://api.ahrvo.network/payments/na/settlements/STsettlementExample789"
    },
    "application": {
      "href": "https://api.ahrvo.network/payments/na/applications/APapplicationExample456"
    },
    "reviewed_by_user": {
      "href": "https://api.ahrvo.network/payments/na/users/USuserExample222"
    }
  }
}

Example Response (Rejected)

{
  "id": "RQreviewQueue456",
  "created_at": "2023-12-10T11:00:00Z",
  "updated_at": "2023-12-10T15:20:00Z",
  "application": "APapplicationExample456",
  "completed_at": "2023-12-10T15:20:00Z",
  "entity_id": "STsettlementExample888",
  "entity_type": "SETTLEMENT_V2",
  "outcome": "REJECTED",
  "outcome_reason": [
    "VELOCITY_LIMIT_EXCEEDED",
    "RISK_THRESHOLD_EXCEEDED"
  ],
  "processor_type": "VANTIV_V1",
  "review_type": "CREATED",
  "reviewed_by": "USuserExample333",
  "tags": {
    "priority": "high",
    "merchant_name": "Risky Merchant LLC",
    "rejection_reason": "Exceeded velocity limits",
    "rejection_details": "Merchant exceeded 30-day volume limit by 200%",
    "rejected_by": "Jane Smith"
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/review_queue/RQreviewQueue456"
    },
    "settlement": {
      "href": "https://api.ahrvo.network/payments/na/settlements/STsettlementExample888"
    },
    "application": {
      "href": "https://api.ahrvo.network/payments/na/applications/APapplicationExample456"
    },
    "reviewed_by_user": {
      "href": "https://api.ahrvo.network/payments/na/users/USuserExample333"
    }
  }
}

Additional Information

Outcome Options and Their Effects:
- ACCEPTED: Approve the review
  - For SETTLEMENT_V2: Settlement will proceed and funds will be disbursed
  - For IDENTITY: Identity will be activated and can be used
  - For FEE: Fee transaction will be processed
  - Sets completed_at timestamp
  - Sets reviewed_by to current user
  - Entity moves forward in its lifecycle
  - Irreversible - settlement will process immediately
- REJECTED: Deny the review
  - For SETTLEMENT_V2: Settlement is cancelled, funds may be returned
  - For IDENTITY: Identity remains inactive, merchant can't onboard
  - For FEE: Fee transaction is cancelled
  - Sets completed_at timestamp
  - Sets reviewed_by to current user
  - Should include reason codes in outcome_reason
  - Merchant should be notified with clear explanation
  - May require remediation before retry
- MANUAL_REVIEW: Escalate for deeper investigation
  - Item remains in review queue
  - Signals need for specialized review (legal, compliance, senior management)
  - Does not set completed_at (review still ongoing)
  - Entity remains blocked until resolved
  - Use tags to document escalation reason and assignment
- PENDING: Reset to pending state
  - Rarely used - typically for reopening a review
  - Clears completed_at if previously set
  - Returns item to review queue
  - Use when new information requires re-review
Outcome Reasons: When rejecting, the system may automatically populate outcome_reason
- Common rejection codes:
  - INSUFFICIENT_FUNDS: Not enough balance for settlement
  - RISK_THRESHOLD_EXCEEDED: Transaction exceeds risk limits
  - VELOCITY_LIMIT_EXCEEDED: Too many transactions in timeframe
  - SUSPICIOUS_ACTIVITY: Fraud or AML concerns
  - INCOMPLETE_KYC: Missing identity documents
  - SANCTIONS_MATCH: Entity matches sanctions list
  - HIGH_RISK_MERCHANT: Business type flagged
  - CHARGEBACK_RATIO_HIGH: Excessive chargebacks
  - MANUAL_HOLD: Intentional hold
  - DOCUMENT_VERIFICATION_FAILED: Invalid KYC documents
- Use these codes to communicate rejection reasons programmatically
- Include human-readable explanation in tags for merchant communication
Tags Best Practices: Use tags to document the decision
- Approval Tags:
  - reviewer_notes: Explanation of why approved
  - approved_by: Name of reviewer
  - approval_timestamp: When decision was made
  - risk_assessment: Summary of risk analysis
  - merchant_contacted: Whether merchant was notified
- Rejection Tags:
  - rejection_reason: High-level reason
  - rejection_details: Detailed explanation
  - rejected_by: Name of reviewer
  - remediation_steps: What merchant needs to do
  - merchant_notified: Whether merchant was contacted
- Escalation Tags:
  - escalation_reason: Why escalated
  - assigned_to: Who should handle
  - case_id: Reference number
  - priority: urgency level
  - escalation_timestamp: When escalated
Automated Actions: When outcome is updated, the system may:
- ACCEPTED:
  - Trigger settlement processing
  - Activate identity for use
  - Send confirmation notification
  - Update merchant dashboard
  - Log audit event
- REJECTED:
  - Cancel settlement
  - Send rejection notification to merchant
  - Return funds if applicable
  - Log audit event
  - May trigger compliance reporting
- MANUAL_REVIEW:
  - Assign to escalation queue
  - Notify designated reviewers
  - Set higher priority
  - Log escalation event
Review Workflow Example:
1. Fetch: GET /review_queue/{id} to get full details
2. Investigate: Review linked entity (settlement, identity)
  - Check merchant history and transaction patterns
  - Verify documentation and compliance
  - Assess risk factors
3. Decide: Determine outcome
  - Low risk + complete info = ACCEPTED
  - High risk or policy violation = REJECTED
  - Unclear or complex = MANUAL_REVIEW
4. Update: PUT /review_queue/{id} with outcome
5. Document: Add detailed tags explaining decision
6. Notify: Inform merchant of outcome (especially if rejected)
Use Cases:
- Daily Review Processing: Process all PENDING items in queue
- Settlement Approval: Approve settlements for payout
- KYC Review: Accept or reject identity verifications
- Risk Management: Reject high-risk transactions
- Escalation: Flag complex cases for senior review
- Batch Processing: Bulk approve low-risk items
- Compliance Actions: Reject items due to regulatory concerns
Decision Criteria:
- Settlement Reviews - Consider:
  - Merchant transaction history and patterns
  - Settlement amount vs typical volume
  - Chargeback rate and reserves
  - Time since merchant onboarding
  - Business type and risk category
  - Velocity limits and thresholds
  - Available balance and reserves
- Identity Reviews - Consider:
  - KYC document completeness and authenticity
  - Sanctions and watchlist screening results
  - Business information verification
  - Beneficial ownership clarity
  - Regulatory compliance requirements
  - Risk indicators (high-risk countries, industries)
Timing Considerations:
- Settlements on hold prevent merchant payouts (cash flow impact)
- Process reviews promptly to maintain merchant satisfaction
- Set SLAs (e.g., 24-48 hours for standard reviews)
- Escalate items approaching SLA deadline
- Prioritize high-value or high-priority items
Audit and Compliance:
- All decisions are logged with user attribution
- reviewed_by field tracks accountability
- completed_at timestamp proves review completion
- outcome_reason provides regulatory justification
- Tags document decision rationale
- Helps demonstrate AML/KYC compliance
- Provides audit trail for regulators
Merchant Communication:
- Accepted: Send confirmation that funds will be disbursed
- Rejected:
  - Explain clear reasons for rejection
  - Provide remediation steps if applicable
  - Offer appeal process if available
  - Reference outcome_reason codes
  - Be transparent about timeline
- Manual Review:
  - Notify of additional review requirement
  - Set expectations for resolution timeline
  - Request additional information if needed
Error Handling:
- Invalid review_queue_item_id: 404 Not Found
- Invalid outcome value: 400 Bad Request
- Already completed review: May return 400 or allow override
- Insufficient permissions: 403 Forbidden
- System errors: 500 Internal Server Error
Idempotency:
- Updating outcome multiple times is allowed
- Last update wins (overwrites previous outcome)
- Can change ACCEPTED to REJECTED if needed (rare)
- Use cautiously - settlement may already be processing
Permissions and Security:
- Restrict access to compliance/risk team members
- Consider role-based permissions:
  - Junior reviewers: Can only ACCEPTED or escalate
  - Senior reviewers: Can REJECT
  - Managers: Can override decisions
- Log all outcome changes for security audit
- May require dual approval for large settlements
Integration Patterns:
- Manual Dashboard: Review UI calls this endpoint on button click
- Automation: Rules engine auto-accepts low-risk items
- Workflow: Escalation routing based on business rules
- Webhooks: Trigger notifications when outcome changes
- Analytics: Track approval/rejection rates and reasons
Best Practices:
- Always fetch item details before updating (get context)
- Document decision thoroughly in tags
- Use consistent tag naming conventions
- Include reviewer name/ID in tags
- Set appropriate outcome_reason codes for rejections
- Notify merchants of decisions (especially rejections)
- Monitor queue depth and review times
- Escalate appropriately (don't reject unclear cases)
- Maintain audit trail for compliance
- Train reviewers on consistent decision-making

Overview​

Resource Access​

Arguments​

Example Request (Accept a Settlement)​

Example Request (Reject a Settlement)​

Example Request (Escalate for Manual Review)​

Example Response (Accepted)​

Example Response (Rejected)​

Additional Information​