# Sequence flow (Payment API 2.0)


```mermaid
sequenceDiagram
    autonumber

    participant C as Customer
    participant FE as Merchant Frontend
    participant BE as Merchant Backend
    participant AUTH as Ratepay Auth API
    participant RP as Ratepay Payment API

    C->>FE: Open checkout
    FE->>C: Render checkout and Ratepay payment options

    C->>FE: Select Ratepay payment method
    C->>FE: Device fingerprinting
    note right of FE: Required for risk and fraud scoring

    C->>FE: Customer consent for terms and risk check
    C->>FE: Click Buy now

    FE-->>BE: Buyer basket payment and device data

    BE-->>AUTH: OAuth2 token request
    AUTH-->>BE: Bearer token

    BE->>RP: POST /transactions authorize
    note right of BE: All write operations are idempotent (authorize, capture, cancel, refund)
    opt OTP requested by Ratepay
        RP-->>BE: Authorization pending – OTP required
        BE-->>FE: Request one-time passcode
        FE->>C: Display OTP input
        C->>FE: Enter OTP code
        FE-->>BE: OTP code
        BE->>RP: POST /verify confirm (OTP)
        RP-->>BE: OTP verification result
    end
    RP-->>BE: Approved or declined

    alt Authorization approved
        BE-->>FE: Proceed with order
    else Authorization declined
        alt Hard risk decline
            BE-->>FE: Show fallback payment methods
        else Soft decline
            loop Retry authorization max 3 attempts
                FE-->>BE: Adjust data
                BE->>RP: POST /transactions authorize
                RP-->>BE: Approved or declined
            end
            BE-->>FE: Final decline after retries
        end
    end

    note over FE,BE: Time passes - order processing and shipment

    BE->>RP: POST /captures after shipment
    RP-->>BE: Capture confirmed

    note right of RP: Invoice creation and customer communication

    BE->>RP: Shipping information optional

    BE->>RP: POST /cancellation optional
    RP-->>BE: Cancellation confirmation

    note right of RP: Supports partial captures and partial refunds

    BE->>RP: POST /refunds optional
    RP-->>BE: Refund confirmation
```