---
title: "Simulate sandbox service-provider payout states"
method: POST
path: "/sandbox/service-provider-payouts/simulate"
tags: ["Service provider payments"]
---

# Simulate sandbox service-provider payout states

`POST /sandbox/service-provider-payouts/simulate`

## Request

- Base URL: `https://platform-api.homejourney.sg/v1`
- URL: `https://platform-api.homejourney.sg/v1/sandbox/service-provider-payouts/simulate`
- Auth: HTTP bearer

Returns deterministic sandbox-only payout lifecycle fixtures when the authenticated automation client has `services.payouts.manage`. External URL: `/v1/sandbox/service-provider-payouts/simulate`. Current Next.js implementation path: `/api/platform/v1/sandbox/service-provider-payouts/simulate`. This mutating route requires `Idempotency-Key`; SDK, CLI, and MCP sandbox simulations may call this route after explicit confirmation, while the route records only standard platform request/idempotency evidence and never creates real Stripe charges, transfers, payouts, bank movements, Xero journals, payout jobs, settlement rows, or fixture mutations.

## Headers

- `X-Correlation-Id` string
- `Idempotency-Key` string, required

## Request body

- SandboxServiceProviderPayoutSimulationRequest: Sandbox-only payout simulation scenario selector. The route returns deterministic fixtures and does not create payout jobs, provider mutations, Stripe/Xero calls, or bank movements.
  - `scenario` 'draft' | 'approved' | 'processing' | 'reconciled' | 'partial_refund_after_payout' | 'manual_adjustment_increase' | 'manual_adjustment_decrease' | 'provider_onboarding_missing', required

## Response `200`

Sandbox payout simulation result.

- SandboxServiceProviderPayoutSimulationResponse
  - `simulation` object, required
    - `scenario` Scenario, required (unresolved $ref)
    - `description` string, required
    - `payout` object, required
      - `id` string, required
      - `provider_id` string, required
      - `provider_name` string, required
      - `period` object, required
        - `start_date` string, date, required
        - `end_date` string, date, required
        - `timezone` 'Asia/Singapore', required
      - `currency` 'SGD', required
      - `status` 'draft' | 'pending_approval' | 'approved' | 'processing' | 'reconciled', required
      - `gross_booking_amount_cents` integer, required
      - `platform_fee_cents` integer, required
      - `net_payout_cents` integer, required
      - `adjustment_cents` integer, required
      - `refund_reversal_cents` integer, required
      - `payout_line_item_count` integer, required
      - `paid_at` string, date-time, nullable, required
      - `settlement_eta` string, date, nullable, required
      - `failure_reason` string, nullable, required
      - `next_action` 'awaiting_admin_approval' | 'provider_onboarding_required' | 'operator_review_required' | 'null', nullable, required
      - `accounting_reference` string, required
    - `line_items` object[], required
      - `id` string, required
      - `payout_id` string, required
      - `source_type` 'booking_payable' | 'refund_reversal' | 'manual_adjustment', required
      - `source_booking_reference` string, nullable, required
      - `description` string, required
      - `gross_booking_amount_cents` integer, required
      - `platform_fee_cents` integer, required
      - `net_amount_cents` integer, required
      - `adjustment_cents` integer, required
      - `refund_reversal_cents` integer, required
      - `ledger_account_code` 'PROVIDER_ACCRUAL' | 'PROVIDER_OFFSET', required
      - `accounting_reference` string, required
    - `provider_setup` object, required
      - `connect_account_status` 'verified' | 'missing' | 'requirements_due', required
      - `bank_status` 'verified' | 'missing' | 'unverified', required
      - `payouts_enabled` boolean, required
      - `next_action` 'none' | 'complete_hosted_onboarding' | 'resolve_connect_requirements', required
  - `ledger_sources` object, required
    - `payouts_table` 'services_payouts', required
    - `transactions_table` 'services_transactions', required
    - `refunds_table` 'services_booking_refunds', required
    - `payout_batch_source` 'services_payouts.id', required
    - `payout_line_item_source` 'services_transactions.payout_id', required
    - `simulation_source` 'deterministic_sandbox_fixture', required
    - `client_side_calculation_used` false, required
    - `fee_schedule_id` 'fee_schedule_transaction_only_2026_06', required
    - `pricing_model` 'transaction_only', required
    - `platform_access_fee_basis_points` 0, required
    - `transaction_fee_rates` object, required
      - `domestic_card` object, required
        - `basis_points` 430, required
        - `fixed_fee_cents` 70, required
      - `paynow` object, required
        - `basis_points` 170, required
        - `fixed_fee_cents` 10, required
    - `marketplace_commission_basis_points` 0, required
    - `standard_payout_fee_cents` 0, required
    - `standard_payout_timing` 'T+30_calendar_days_after_payable_accrual', required
    - `redaction_version` 'service_provider_payout_simulation.v1', required
  - `public_safety` PublicSafety, required (unresolved $ref)
  - `side_effects` object, required
    - `real_stripe_charges_created` false, required
    - `real_stripe_transfers_created` false, required
    - `real_stripe_payouts_created` false, required
    - `xero_journals_created` false, required
    - `payout_jobs_enqueued` false, required
    - `payout_records_created` false, required
    - `settlement_records_mutated` false, required
    - `fixture_state_mutated` false, required
    - `idempotency_and_request_events_only` true, required
  - `authorization` Authorization, required (unresolved $ref)
  - `principal` Principal, required (unresolved $ref)
  - `livemode` false, required
  - `request_id` string, required

## Other responses

- `400`: Request validation failed.
- `401`: Missing or invalid platform API key.
- `403`: Credential, environment, or scope is not allowed.
- `404`: Platform API feature or resource is not available.
- `409`: Idempotency key is in progress or conflicts with an earlier request body.
- `429`: Rate limit exceeded.
- `500`: Unexpected platform API failure.

---

[API](https://skmtc.dev/homejourney/apis/homejourney-platform-api.md) · [All operations](https://skmtc.dev/homejourney/apis/homejourney-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/homejourney/apis/homejourney-platform-api/revisions/a2c6fe063db1?raw)