> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lab4pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Flows

> Sequence diagrams for the main Pay Connect integration scenarios

## Successful Transaction

Pay Connect client creates a transaction, the terminal processes payment, then the client retrieves the outcome via polling or webhook.

```mermaid actions={false} theme={null}
sequenceDiagram
    participant C as Pay Connect Client
    participant S as Payment Service
    participant T as Terminal

    C->>S: POST .../transactions/generate/
    activate S
    S-->>C: 200 { transaction_id }
    deactivate S

    S-->>T: WS transaction_created

    Note over T: Customer completes payment

    T->>S: PATCH status → SUCCESS
    activate S
    S-->>T: 200 OK
    deactivate S

    alt Webhook (optional)
        S-->>C: POST webhook_url { transaction.success }
    end

    C->>S: GET .../transactions/{id}/status/
    activate S
    S-->>C: 200 { status: SUCCESS }
    deactivate S

    C->>S: GET .../transactions/{id}/print-slip/
    activate S
    S-->>C: 200 { print_slip }
    deactivate S
```

## Transaction Cancel

Pay Connect client cancels a transaction. If the transaction is still `INITIATED` it is cancelled immediately. If `IN_PROGRESS`, a cancel signal is sent to the terminal.

```mermaid actions={false} theme={null}
sequenceDiagram
    participant C as Pay Connect Client
    participant S as Payment Service
    participant T as Terminal

    C->>S: POST .../transactions/generate/
    activate S
    S-->>C: 200 { transaction_id }
    deactivate S

    S-->>T: WS transaction_created

    C->>S: POST .../transactions/{id}/cancel/
    activate S
    S-->>C: 200 OK
    end
    deactivate S

    Note over T: Terminal aborts payment
```

## Transaction Success & Revert

After a successful transaction, the Pay Connect client requests a revert (void). The terminal processes the revert asynchronously. The client polls the operation status.

```mermaid actions={false} theme={null}
sequenceDiagram
    participant C as Pay Connect Client
    participant S as Payment Service
    participant T as Terminal

    Note over C,T: Transaction completed with SUCCESS

    C->>S: POST .../transaction-operations/{id}/revert/
    activate S
    S-->>C: 200 { operation_id, transaction_id }
    deactivate S

    S-->>T: WS revert_requested

    Note over T: Terminal processes revert

    T->>S: PATCH operation → SUCCESS
    activate S
    S-->>T: 200 OK
    deactivate S

    alt Webhook (optional)
        S-->>C: POST webhook_url { transaction.reverted }
    end

    C->>S: GET .../transaction-operations/{op_id}/
    activate S
    S-->>C: 200 { status: SUCCESS }
    deactivate S
```

## Transaction Success & Refund

After a successful transaction, the Pay Connect client requests a partial or full refund. A new refund transaction is created and processed by the terminal.

```mermaid actions={false} theme={null}
sequenceDiagram
    participant C as Pay Connect Client
    participant S as Payment Service
    participant T as Terminal

    Note over C,T: Transaction completed with SUCCESS

    C->>S: POST .../transactions/{id}/refund/
    activate S
    Note over S: Validate refund amount
    S-->>C: 200 { transaction_id (refund) }
    deactivate S

    S-->>T: WS refund_requested { amount }

    Note over T: Terminal processes refund

    T->>S: PATCH refund tx → SUCCESS
    activate S
    S-->>T: 200 OK
    deactivate S

    alt Webhook (optional)
        S-->>C: POST webhook_url { transaction.refunded }
    end

    C->>S: GET .../transactions/{refund_id}/status/
    activate S
    S-->>C: 200 { status: SUCCESS }
    deactivate S
```

## Terminal Config & Unpair

Pay Connect client retrieves the terminal configuration (currency, timezone, payment methods) and can unpair to remove the integration.

```mermaid actions={false} theme={null}
sequenceDiagram
    participant C as Pay Connect Client
    participant S as Payment Service
    participant T as Terminal

    C->>S: GET .../config/
    activate S
    S-->>C: 200 { currency, timezone, ... }
    deactivate S

    Note over C: Integration no longer needed

    C->>S: POST .../unpair/
    activate S
    Note over S: Delete OAuth app & record
    S-->>C: 200 OK
    deactivate S

    S-->>T: WS pay_connect_unpaired
    Note over T: Terminal updates UI
```