# Payment Lifecycle

A payment represents one merchant order and contains one or more attempts. The current mock API accepts exactly one `pay_with` option, so mock responses normally contain one attempt.

## Happy Path

```mermaid
stateDiagram-v2
    [*] --> awaiting_payment
    awaiting_payment --> payment_detected: transfer observed
    payment_detected --> payment_finalized: deposit reaches 16/16
    payment_finalized --> settlement_pending
    settlement_pending --> settlement_submitted
    settlement_submitted --> completed
```

## Main Statuses

* `awaiting_payment`: invoice instructions were created and the system is waiting for funds.
* `payment_detected`: Artum observed a transfer, but funding is not finalized yet.
* `partially_paid`: some funds were detected, but the payment is not fully funded.
* `payment_finalized`: payment funding reached finality.
* `settlement_pending`: settlement is ready to be submitted.
* `settlement_submitted`: settlement transaction was submitted.
* `settlement_finalized`: settlement transaction reached finality.
* `completed`: payment and settlement completed successfully.
* `expired`: payment expired before valid funding.
* `underpaid_expired`: less than the required amount was received before expiration.
* `overpaid_review`: more than the required amount was received and needs review.
* `manual_review`: the payment requires manual review.
* `failed`: the payment cannot be completed automatically.

The exact status set may evolve with the production orchestrator. Use the OpenAPI contract as the source of truth for enum values.

For a complete table, see [Status Reference](/payments/status-reference.md).

## Attempts

Attempts expose payment instructions and funding state.

Use:

```http
GET /v1/payments/{payment_id}/attempts
```

Each attempt contains:

* `instructions`: invoice address, token, amount due, expiration, and warnings.
* `funding`: pending and finalized amount projections.
* `deposits`: detected blockchain deposits.
* `source_settlement`: settlement status when available.

## Deposit Finality

Deposit status is separate from payment status:

* `pending`: transfer was observed but has zero mock confirmations.
* `confirming`: transfer is progressing toward finality.
* `finalized`: transfer reached the required confirmation threshold.
* `rejected`: transfer was observed but cannot fund the payment.

Use these fields for UI progress:

* `deposits[].confirmations`
* `deposits[].confirmations_required`

The mock API defaults to a 16-block requirement and advances in 4-block steps, so clients can display `4/16`, `8/16`, `12/16`, and `16/16`.

The current mock timing is intentionally compressed for UI testing. It does not represent real BSC block timing.

## Polling

For mock testing, polling is enough:

```bash
curl "https://mock.artum.app/v1/payments/$PAYMENT_ID" \
  -H "Authorization: Bearer $ARTUM_MOCK_API_KEY"
```

Production integrations should use webhooks once enabled.


---

# 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/payments/payment-lifecycle.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.