Close a Settlement (Stop Accrual)

Overview

Manually close an open Settlement, stopping it from accruing additional transactions and immediately submitting it for approval. Use this to force settlement closure before the scheduled window end time.

Resource Access

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

Arguments

Parameter	Type	Required	Description
settlement_id	string	Yes (path)	The unique ID of the Settlement to close
action	string	Yes	Must be "STOP_ACCRUAL" to close the settlement

Example Request

curl -X PUT \
  'https://api.ahrvo.network/payments/na/settlements/STsettlementExample123' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "STOP_ACCRUAL"
  }'

Example Response

{
  "id": "STsettlementExample123",
  "created_at": "2023-12-10T08:00:00Z",
  "updated_at": "2023-12-10T15:30:00Z",
  "application": "APapplicationExample456",
  "merchant_id": "MUmerchantExample789",
  "processor": "LITLE_V1",
  "currency": "USD",
  "status": "AWAITING_APPROVAL",
  "net_amount": 15200,
  "total_amount": 16000,
  "total_fee": 800,
  "type": "MERCHANT_REVENUE",
  "window_start_time": "2023-12-10T00:00:00Z",
  "window_end_time": "2023-12-10T15:30: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"
    },
    "entries": {
      "href": "https://api.ahrvo.network/payments/na/settlements/STsettlementExample123/entries"
    }
  }
}

Additional Information

HTTP 201 Response: Successfully closed settlement returns 201 Created
- Settlement status changes from PENDING → AWAITING_APPROVAL
- window_end_time is set to current timestamp
- updated_at timestamp updated
- Settlement amounts (total_amount, total_fee, net_amount) are finalized
What "Stop Accrual" Means:
- Settlement stops accepting new transactions
- No more entries will be added from settlement queue
- Settlement window is considered closed
- Amounts are locked and final
- Settlement moves to approval workflow
When to Use This Endpoint:
- Early Close for Emergency Payout:
  - Merchant needs urgent funds
  - Don't want to wait for scheduled settlement time
  - Close current settlement and process immediately
- End-of-Day Processing:
  - Force close settlements at specific time
  - Maintain consistent cutoff times
  - Streamline batch processing
- Special Circumstances:
  - Merchant account closure
  - Emergency cash flow needs
  - Testing settlement workflows
  - Correcting settlement timing issues
- Manual Settlement Control:
  - Override automatic settlement schedule
  - Create custom settlement windows
  - Handle exceptions or edge cases
Settlement Must Be PENDING: Can only close PENDING settlements
- AWAITING_APPROVAL: Already closed, can't close again
- APPROVED: Already approved and funded, can't modify
- Error if attempting to close non-PENDING settlement
Effect on Transactions:
- Transactions already in settlement: Remain in settlement
- Transactions waiting in queue: Will go to next settlement
- New transactions after closure: Go to new settlement
- Settlement queue entries with ready_to_settle_after > window_end_time: Not included
Automatic vs Manual Closure:
- Automatic (default behavior):
  - Settlement closes at scheduled time (e.g., end of day)
  - Based on merchant's payout profile frequency
  - No manual intervention needed
  - Most common scenario
- Manual (this endpoint):
  - Explicitly close settlement before scheduled time
  - Override automatic schedule
  - Take immediate control
  - Creates is_exception: false settlement (not truly exceptional)
After Closure - What Happens Next:
1. Settlement status → AWAITING_APPROVAL
2. window_end_time set to closure time
3. Amounts finalized (no more changes)
4. Settlement enters approval workflow
5. Automatic approval (typically immediate)
6. Status → APPROVED
7. Funding transfers created
8. Funds disbursed to merchant
Timing Considerations:
- Closed settlement processes in next funding batch
- Actual fund arrival depends on:
  - Approval processing time
  - Settlement batch schedule
  - Payment rail (NEXT_DAY_ACH, SAME_DAY_ACH)
  - Bank processing times
- Example timeline:
  - Close at 3:00 PM
  - Approved by 3:15 PM
  - Funding transfer created 3:30 PM
  - ACH initiated 4:00 PM
  - Funds arrive next business day
Use Cases:
- Emergency Merchant Payout:
  1. Merchant has cash flow crisis
  2. Close current PENDING settlement early
  3. Process immediately instead of waiting for EOD
  4. Merchant receives funds faster
- Custom Settlement Schedule:
  1. Merchant wants weekly settlements (not daily)
  2. Let settlement stay PENDING all week
  3. On Friday, manually close with STOP_ACCRUAL
  4. Process weekly batch
- Settlement Testing:
  1. Test settlement workflow in staging
  2. Create test transactions
  3. Manually close settlement
  4. Verify approval and funding process
- Account Closure:
  1. Merchant closing account
  2. Close any open settlements immediately
  3. Process final payout
  4. Complete merchant offboarding
Best Practices:
- Verify Before Closing:
  - Fetch settlement first (GET /settlements/{id})
  - Confirm status is PENDING
  - Review amounts and transactions
  - Ensure expected transactions are included
- Document the Reason:
  - Log why manual closure was needed
  - Add notes to merchant record
  - Track for audit purposes
  - Communicate with merchant if needed
- Monitor After Closure:
  - Check status transition to AWAITING_APPROVAL
  - Verify automatic approval occurs
  - Monitor for approval delays or errors
  - Confirm funding transfers created
- Communicate with Merchant:
  - Notify merchant settlement is processing
  - Provide expected fund arrival time
  - Explain any schedule changes
Warnings and Cautions:
- Irreversible: Once closed, can't reopen
  - Can't add more transactions after closure
  - Ensure all expected transactions are included
  - Double-check amounts before closing
- Queue Timing: Transactions not yet released won't be included
  - Check settlement queue entries
  - Verify ready_to_settle_after timestamps
  - May need to wait or manually release queue entries first
- Multiple Settlements: Closing creates new settlement for future transactions
  - Next transaction starts new PENDING settlement
  - May result in multiple small settlements
  - Consider impact on merchant experience
Error Handling:
- Invalid settlement_id: 404 Not Found
- Settlement not PENDING: 400 Bad Request or 409 Conflict
- Invalid action value: 400 Bad Request
- Permissions error: 403 Forbidden
- System error: 500 Internal Server Error

Integration Patterns:

Dashboard "Close Settlement" Button:

User clicks "Close Settlement"
→ Confirm dialog
→ PUT /settlements/\{id} with action: STOP_ACCRUAL
→ Show success message
→ Refresh settlement details
→ Monitor status change

Scheduled Batch Close:

Cron job at 11:59 PM daily
→ Query all PENDING settlements
→ For each: PUT /settlements/\{id} STOP_ACCRUAL
→ Log results
→ Alert on failures

API-Driven Settlement Control:

Merchant requests early payout via API
→ Validate merchant and settlement
→ Close settlement via this endpoint
→ Monitor approval
→ Notify merchant of completion

Alternatives to Manual Closure:
- Wait for automatic closure (default)
- Adjust merchant's payout profile frequency
- Use instant payout (funding transfer attempts)
- Configure settlement_queue_mode for more control
Related Endpoints:
- GET /settlements/{id}: Check current status before closing
- GET /settlements/{id}/entries: Review what will be included
- GET /settlements: List settlements to find PENDING ones
- GET /settlement_queue_entries: Check pending transactions
Compliance and Audit:
- Log all manual closures with user attribution
- Document business reason for early closure
- Track frequency of manual closures
- Review patterns for process improvements
- Maintain audit trail for regulators

Overview​

Resource Access​

Arguments​

Example Request​

Example Response​

Additional Information​