Skip to content

Concepts: payment status

Payment transactions are a central part of commercial processing in the tebio platform. Every payment transaction (whether by credit card, PayPal or SEPA) goes through a defined status model.

Since payments often go through redirects (redirects to payment providers) and asynchronous confirmations (like 3D-Secure), understanding this model is important for integration, support and accounting.

As soon as a new payment (startPayment) is triggered in the platform, it is in a transitional state. The following diagram shows the possible state machine state transitions:

stateDiagram-v2
    [*] --> NEW
    NEW --> PENDING
    
    note left of PENDING : Possible Actions\n- Finalize
    
    PENDING --> PAYM_RES
    PENDING --> CLOSED_FAILED
    PENDING --> CLOSED_OK
    
    note right of PAYM_RES : Possible Actions\n- Capture\n- Cancel\n- Finalize
    
    PAYM_RES --> CLOSED_OK
    
    note left of CLOSED_FAILED : Possible Actions\n- Finalize (no effect)
    
    note right of CLOSED_OK : Possible Actions\n- Refund\n- Finalize (no effect)
  • PENDING (Pending): The starting point. The payment waits for authentication or authorization by the customer (e.g. PayPal login). This status remains until the maximum waiting time (timeout) has expired or a result is available.
  • PAYM_RES (Reserved): The payment has been successfully reserved with the customer, but the money has not yet been collected. (Only occurs with “RESERVE” type payments, see below).
  • CLOSED_OK (Successful): The payment is completed. Either the money was collected immediately, or a previous reservation (PAYM_RES) has reached its logical end.
  • CLOSED_FAILED (Failed): The payment was rejected (e.g. limit reached, wrong IBAN) or the customer canceled the process with the payment provider.

2. Reservation and immediate move-in (Capture Types)

Section titled “2. Reservation and immediate move-in (Capture Types)”

The status model is significantly influenced by how the payment was initialized. The tebio platform distinguishes between two capture types:

This is the standard case for digital subscriptions. The amount will be authorized and collected immediately.

  • Procedure: If successful, the transaction switches from PENDING directly to CLOSED_OK.

Often used when shipping physical goods: you authorize the amount when purchasing, but only debit it when the goods leave the warehouse.

  • Procedure: If the transaction is successful, it initially changes from PENDING to PAYM_RES.
  • In order to actually receive the money, an explicit Capture (collection) must be triggered later.
  • Important: A reservation transaction always changes to CLOSED_OK later, regardless of whether the money was collected (Capture) or the reservation was canceled (Cancel). The status of the main transaction reflects the success of the reservation. To see what happened to the money, you need to look at the sub-transactions.

Every action that builds on an existing main transaction creates a separate subtransaction in the tebio platform. Because there can be multiple partial collections or partial cancellations for a single reservation, subtransactions have their own simplified status model.

Typical sub-transactions are:

  • CAPTURE: Captures a reserved amount.
  • CANCEL: Releases a reserved amount.
  • REFUND: Transfers money back from an already completely successful payment (CLOSED_OK).

After initiation, subtransactions immediately change to CLOSED_OK or CLOSED_FAILED, as no further customer interaction (such as a PIN entry redirect) is usually necessary here.

If you build your own frontends and use the API, these four core services are relevant to the lifecycle:

  1. Start Payment (startPayment): Initiates the payment. Returns a redirect URL to which the customer must be directed in the browser (e.g. to PayPal).
  2. Complete payment (finalizePayment): This is the most important service after the redirect. If PayPal redirects the customer back to your returnURL or cancelURL, the system must never blindly trust this browser redirect (security risk). Therefore, call finalizePayment on the server side. The system then queries the payment provider directly via a server-to-server connection for the status and sets the transaction from PENDING to CLOSED_OK or CLOSED_FAILED.
  3. Capture / Cancel: Services to finally collect or release the money based on a PAYM_RES main transaction.
  4. Refund Payment (refundPayment): Refunds successfully collected money (from a CLOSED_OK transaction).