# Mock Scenarios

Use `X-Artum-Mock-Scenario` on `POST /v1/payments` to select a deterministic lifecycle.

```http
X-Artum-Mock-Scenario: happy_path
```

The current mock does not deliver webhooks. Test scenario behavior by polling `GET /v1/payments/{payment_id}`.

## Default Timing

| Step                      | Approximate time after creation |
| ------------------------- | ------------------------------- |
| Deposit observed          | `5s`                            |
| Confirmations `4/16`      | `7s`                            |
| Confirmations `8/16`      | `9s`                            |
| Confirmations `12/16`     | `11s`                           |
| Confirmations `16/16`     | `13s`                           |
| Settlement pending        | `25s`                           |
| Settlement submitted      | `30s`                           |
| Terminal happy-path state | `45s`                           |
| Expiry scenarios expire   | `30s`                           |

Timing is compressed for integration tests and UI demos.

## Scenario Reference

| Scenario             | Final payment status | What it simulates                                                                                               | Use it to test                                    |
| -------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `happy_path`         | `completed`          | Customer pays the full `due` amount in the correct asset, deposit finalizes, settlement completes.              | Normal order fulfillment.                         |
| `no_payment_expired` | `expired`            | No deposit is observed before expiry.                                                                           | Expired checkout and retry/new-payment flow.      |
| `underpaid_expired`  | `underpaid_expired`  | Customer sends less than `due`; funding finalizes but remains insufficient by expiry.                           | Underpayment messaging, support, refund handling. |
| `overpaid_review`    | `overpaid_review`    | Customer sends more than `due`; payment is held for review after finality.                                      | Overpayment review and support flow.              |
| `asset_mismatch`     | `manual_review`      | Customer sends a supported token that does not match the payment instructions; deposit is rejected for funding. | Wrong-asset support flow.                         |
| `late_payment`       | `manual_review`      | Payment expires first, then a deposit is observed later.                                                        | Late-payment support and manual resolution.       |
| `settlement_failed`  | `failed`             | Funding finalizes but source settlement fails.                                                                  | Failure handling after payment finality.          |
| `manual_review`      | `manual_review`      | Funding finalizes, then the payment is held for broad operational, risk, compliance, or support review.         | Manual review UX and backoffice escalation.       |

## Notes by Scenario

### `happy_path`

Expected progression:

```
awaiting_payment -> payment_detected -> payment_finalized -> settlement_pending -> settlement_submitted -> completed
```

Deposit progression:

```
pending 0/16 -> confirming 4/16 -> confirming 8/16 -> confirming 12/16 -> finalized 16/16
```

### `underpaid_expired`

The mock sends half of the required `due` amount. Before expiry, the payment can show partial funding. At expiry, it becomes `underpaid_expired`.

### `overpaid_review`

The mock sends more than `due`. Finalized funding is reflected in `funding.amount_received_finalized`, and the overpaid part is reflected in `funding.overpaid_amount`.

### `asset_mismatch`

The mock observes a transfer in another supported BSC asset. The deposit becomes `rejected` and the payment goes to `manual_review`.

### `late_payment`

The payment first becomes `expired`. A later observed deposit moves the case to `manual_review` because funds arrived outside the payment window.

### `settlement_failed`

The customer payment side succeeds. The failure happens after settlement submission, so this scenario is useful for testing post-payment failure handling.

### `manual_review`

This is intentionally broad. It represents cases that need human or backoffice handling, including risk, compliance, operational review, ambiguous funding, late payment, or support escalation.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.artum.app/mock-api/mock-scenarios.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.