Transaction Flow Walkthrough

Payment Lifecycle

Every Inflow payment moves through a series of statuses. Here is the complete flow:

stateDiagram-v2
    [*] --> INITIATION : Payment created
    INITIATION --> CHECKOUT_PENDING : Preparing payment
    CHECKOUT_PENDING --> CHECKOUT_SUCCESS : Customer pays
    CHECKOUT_SUCCESS --> PAYMENT_RECEIVED : Funds received by provider
    PAYMENT_RECEIVED --> PAYMENT_SUCCESS : Funds in user account
    CHECKOUT_SUCCESS --> PAYMENT_FAILED : Post-auth failure
    PAYMENT_SUCCESS --> REFUND_PENDING : Refund requested
    REFUND_PENDING --> FULLY_REFUNDED : Refund complete
    PAYMENT_SUCCESS --> PARTIAL_REFUNDED : Partial refund
    FULLY_REFUNDED --> [*]
    PAYMENT_FAILED --> [*]

Status Definitions

Status	Description
`INITIATION`	Payment created, waiting for payer action
`CHECKOUT_PENDING`	Payer is preparing the payment
`CHECKOUT_SUCCESS`	Payer has successfully paid
`PAYMENT_RECEIVED`	Funds received by the banking provider
`PAYMENT_SUCCESS`	Funds received in the user's account
`PAYMENT_FAILED`	Payment failed (card declined, insufficient funds, etc.)

Hosted Checkout Flow

The most common integration. You create a payment and redirect the customer.

sequenceDiagram
    participant Backend as Your Backend
    participant API as Inflow API
    participant Customer
    participant Checkout as Inflow Checkout

    Backend->>API: POST /api/checkout/payment
    API-->>Backend: { paymentId, purchaseUrl }
    Backend-->>Customer: Redirect to purchaseUrl
    Customer->>Checkout: Opens checkout page
    Customer->>Checkout: Selects payment method
    alt Open Banking
        Checkout->>Customer: Bank authentication
    else Card Payment
        Checkout->>Customer: Enter card details
        opt 3DS required
            Checkout->>Customer: 3DS verification
        end
    end
    Checkout->>API: Process payment
    API-->>Checkout: CHECKOUT_SUCCESS → PAYMENT_SUCCESS
    Checkout-->>Customer: Redirect to successUrl
    API->>Backend: Webhook: payment_status_updated

Step by Step

1. Create the payment (your backend):

curl -X POST https://api.inflowpay.xyz/api/checkout/payment \
  -H "X-Inflow-Api-Key: inflow_priv_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [{ "name": "Premium Plan", "price": 4999, "quantity": 1 }],
    "currency": "EUR",
    "customerEmail": "[email protected]",
    "successUrl": "https://yoursite.com/success",
    "cancelUrl": "https://yoursite.com/cancel"
  }'

2. Customer completes checkout — visits purchaseUrl, pays via Open Banking or Card.

3. Payment settles — funds are added to your Inflow balance. Status: PAYMENT_SUCCESS.

4. You receive a webhook — payment_status_updated event with the full payment object.

SDK Card Payment Flow

For embedded card payments on your own site.

sequenceDiagram
    participant Backend as Your Backend
    participant API as Inflow API
    participant Frontend as Your Frontend
    participant SDK as Inflow SDK (iframe)

    Backend->>API: POST /api/server/payment
    API-->>Backend: { payment.id }
    Backend-->>Frontend: paymentId
    Frontend->>SDK: InflowPayProvider + CardElement
    SDK-->>Frontend: Card form rendered
    Note over SDK: Customer enters card details
    SDK->>API: Tokenize + confirm
    opt 3DS required
        SDK-->>Frontend: 3DS modal opens
        Frontend-->>SDK: Customer completes 3DS
    end
    API-->>SDK: Payment result
    SDK-->>Frontend: onComplete(result)
    API->>Backend: Webhook: payment_status_updated

Server-to-Server Flow

Full control — you handle card data collection (requires PCI compliance).

sequenceDiagram
    participant Backend as Your Backend
    participant API as Inflow Card API

    Backend->>API: POST /api/server/payment (card details)
    API-->>Backend: { payment, threeDsSessionUrl? }
    alt 3DS required
        Note over Backend: Redirect customer to threeDsSessionUrl
        API-->>Backend: Customer returns to success/failure URL
        Backend->>API: POST /api/server/payment/{id}/confirm
    else No 3DS (autoConfirm: true)
        Note over Backend: Payment confirmed automatically
    end
    API-->>Backend: Payment settled
    API->>Backend: Webhook: payment_status_updated

Payment Timeline

Every payment includes a timeline array showing each status transition:

{
  "timeline": [
    { "status": "INITIATION", "timestamp": "2025-01-15T10:30:00.000Z" },
    { "status": "CHECKOUT_SUCCESS", "timestamp": "2025-01-15T10:31:15.000Z" },
    { "status": "PAYMENT_SUCCESS", "timestamp": "2025-01-15T10:31:20.000Z" }
  ]
}

Expected Timing Between Statuses

Transition	Expected Delay
`INITIATION` → `CHECKOUT_PENDING`	Immediate (customer opens checkout)
`CHECKOUT_PENDING` → `CHECKOUT_SUCCESS`	Customer-dependent (completes payment)
`CHECKOUT_SUCCESS` → `PAYMENT_RECEIVED`	3–5 business days (depends on currency and banking provider)
`PAYMENT_RECEIVED` → `PAYMENT_SUCCESS`	~1 hour (can be faster or slower)
`PAYMENT_SUCCESS` → `REFUND_PENDING`	Immediate (when you request a refund)

Note: PAYMENT_FAILED is rare for one-time payments. It currently occurs mainly when a recurring subscription invoice charge fails. If an issue arises during the payment flow, your team will be notified.

Open Banking vs Card Payment

Aspect	Open Banking	Card Payment
Authorization	Instant bank transfer	Card charge (may require 3DS)
Settlement	Usually instant	Typically within minutes
Refund	Varies by bank	5–10 business days
3DS	Not applicable	Automatic if required
Chargebacks	Not applicable	Possible (handled by Inflow)

Subscription Payment Flow

For subscription payments, the flow is similar but:

The first payment may include a trial period (no charge) or entry fee (different amount).
Subsequent payments are charged automatically on each billing cycle.
If a recurring payment fails, the subscription enters PAST_DUE.
The subscriptionId field links the payment to its subscription.