Payment execution workflow

Summary

1. A context (a module that requires payments to be processed, such as a webshop) creates a blank payment and configures it.
2. It displays a payment form (based on the form provided by Payment) that allows the user to select a payment method for the payment.
3. The context then executes the payment and by doing so, gives Payment full control over the payment and the request.
4. Payment uses the selected payment method to validate and execute the payment. The payment method receives full control over the request, which means it is allowed to redirect the user off-site, for instance.
5. Once payment execution is completed, the payment method hands over full control back to the context by calling Payment::finish(). The context can then redirect the user back to where he came from, or show a confirmation.

Detailed workflow

(click to enlarge)

The entire workflow consists of four stages. In each stage a certain module has full control over the request, meaning it is allowed to stop PHP execution by redirecting the user, for instance. This means that if you are creating a context or payment method controller, you should have performed all necessary tasks before initiating the next stage (Contexts initiate stage 2 by calling Payment::execute() and payment method controllers initiate stage 4 by calling Payment::finish()).