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.
1. Understand major transactions
Section titled “1. Understand major transactions”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)
Status values in detail:
Section titled “Status values in detail:”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:
Immediate move-in (IMMEDIATE)
Section titled “Immediate move-in (IMMEDIATE)”This is the standard case for digital subscriptions. The amount will be authorized and collected immediately.
- Procedure: If successful, the transaction switches from
PENDINGdirectly toCLOSED_OK.
Reservation (RESERVE)
Section titled “Reservation (RESERVE)”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
PENDINGtoPAYM_RES. - In order to actually receive the money, an explicit
Capture(collection) must be triggered later. - Important: A reservation transaction always changes to
CLOSED_OKlater, 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.
3. Subtransactions
Section titled “3. Subtransactions”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.
4. Lifecycle (API view)
Section titled “4. Lifecycle (API view)”If you build your own frontends and use the API, these four core services are relevant to the lifecycle:
- Start Payment (
startPayment): Initiates the payment. Returns a redirect URL to which the customer must be directed in the browser (e.g. to PayPal). - Complete payment (
finalizePayment): This is the most important service after the redirect. If PayPal redirects the customer back to yourreturnURLorcancelURL, 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 fromPENDINGtoCLOSED_OKorCLOSED_FAILED. - Capture / Cancel: Services to finally collect or release the money based on a
PAYM_RESmain transaction. - Refund Payment (
refundPayment): Refunds successfully collected money (from aCLOSED_OKtransaction).