Payment initiation flow

Introducing payment initiation flow

Payment initiation flow is composed of two main elements: authorisation of the payment and payment initialisation (send instruction to the institution to make the payment happen). While payment initialisation is handled by Volt behind the scenes, payment authorisation is the part where the payer is heavily involved in.

The state of payment initiation flow is represented in the API responses in the paymentInitiationFlow object. This is the steering part of the integration, as this object tells exactly where the payer or payment is within the whole process, and what is required to finalise the flow.

{
    // ...
    "paymentInitiationFlow": {
        "status": "PROCESSING",
        "details": {
            "reason": "AWAITING_USER_REDIRECT",
            "redirect": {
                "url": "https://vo.lt/AB1XF",
                "directUrl": "https://myBank.com/authorisation?code=xyz"
            }
        }
    }
}

paymentInitiationObject describes status of the flow as well as provides optional details about next action to be taken by you or the payer.

Check out API reference

Initiation flow state machine

The payment initiation flow is governed by a state machine that manages the various stages and transitions during the payment process. Understanding this flow is essential for effectively managing payment statuses and guiding users through authorisation steps.

State machine overview

The payment initiation flow adheres to a simple state machine with the following statuses:

Status	Description	Action required
WAITING_FOR_INPUT	Volt is awaiting additional input from the partner via a `PATCH` request. No background processing is occurring.	Partner must provide the necessary input to proceed.
PROCESSING	The payment is being processed. This state may require the partner to redirect the user or continue polling for status updates.	Depending on the authorisation flow, partner may need to handle redirects or continue monitoring the payment status.
FINISHED	The initiation flow has completed successfully. Note: This status does not guarantee that the payment has been fully executed.	Partner can consider the initiation process complete but may need to verify the actual payment status.
EXCEPTION	The initiation flow ended unexpectedly due to an issue.	Partner should handle the exception, possibly by notifying the user and logging the error for further investigation.
ABORTED	The payer either canceled or abandoned the authorisation process.	Partner may need to clean up any resources or notify the user about the aborted payment.

Authorisation flows

During payment initiation flow, the payer needs to authorise the payment. Institutions handle authorisation of the payment in few different ways:

Redirect

<INSERT IMAGE: payer (checkout) -> bank -> checkout (status scrren) >

With the redirect authorisation flow, the payer is redirected to the institution UI to authenticate and authorise the payment.

Pre-authorisation

<INSERT IMAGE: payer (checkout) -> bank -> bank -> checkout (status scrren) >

With the pre-authorisation flow authentication with the institution and authorisation of the payment are two separate steps. Usually, a payer is redirected to the institution UI to authenticate with the institution, and then is redirected to the institution UI again to authorise the payment.

Embedded

<INSERT IMAGE: payer (checkout) -> checkout (capture credentials) -> checkout (status scrren) >

With the embedded authorisation flow a payer’s credentials to the institution are captured by you or Volt, which are then used for authentication at the institution. There is no redirect to the institution.

All mentioned authorisation flows can include an additional step of authorisation, called decoupled.

<INSERT IMAGE: Payer (checkout) -> bank -> bank mobile app -> checkout (status page) >

With the decoupled authorisation the payer needs to authorise the payment through an additional form of authorisation provided by the institution, outside of the API integration (hence the name decoupled). Additional authorisation is done using whatever solution institution supports. In most scenarios it is done via the institution’s application installed on mobile phone.