Documentation

1Transaction States

A transaction has different states. Figure 1 shows the states possible including the transitions which are allowed between those states.

Transaction States
Figure 1. The transaction states including the state transitions

The following sections explain what those states mean and when they are set. It is recommended to build those states into the merchant’s application to support all payment methods. Also it is recommended that the timing of those states is considered correctly in the merchant’s application.

We guarantee that all transactions will use these states independently of the payment method and the processor. However some states may be skipped and the timing may be different depending on the payment method.

1.1Pending

When the transaction is created by the merchant the Pending state is set. Most of the properties can be modified until the transaction is moved to the state Confirmed. As long as the transaction is in the pending state the amount can be increased or lowered.

1.1.1Fetch available payment methods

It is possible to fetch already during this state the possible payment methods for this particular transaction.

1.1.2Confirm the Transaction.

The time the transaction remains in this state, it is controlled by the merchant’s application. A state transition to Confirmed can be issued over the web service interface.

1.2Confirmed

When the transaction is Confirmed the transaction can not be changed anymore. This state indicates that the processing of the transaction can start. The reason why transactions can remain in the state Confirmed and do not switch to Processing is typically because the customer is not forwarded to our service and hence the processing has not been started.

Note
The time the transaction remains in this state is controlled by the merchant’s application. As soon as the customer is redirected to our platform the state Processing will be set.

1.2.1Accept Payments via Iframe

You can accept the payments by using our iframe integration. More detailed information can be found in the iframe integration guide.

1.2.2Accept Payments via Payment Page

You can accept the payments by using our payment page integration. More detailed information can be found in the payment page integration guide.

1.3Processing

The Processing state is set when the transaction processing has started, but is not finished. A transaction can stay in the state Processing for seconds or even weeks. This timing depends on the payment methods, the process, the used chargeflow etc. and how the transaction is processed. Charge flows may for example delay the switch to the next state for weeks because the transaction may stay in Processing as long as all charge flow levels are processed.

Note
The timing for the different charge level can be set in the charge flow level configuration. For more information see the charge flow section.

1.4Failed

The transaction is marked as Failed when the payment could not be authorized. Typically either the customer cancels the authorization process or the authorization was refused by the processor. The details of the reason why the transaction failed can be found on the charge attempts associated with the transaction. Eventually the customer tries multiple times with different failure reason each time.

Important
This state is a final state. The transaction will not change the state anymore.
Note
In order to see more information why the transaction was moved to the failed state can be found when opening the transaction and check the process tab Space > Payment > Transaction.

1.5Authorized

The transaction is Authorized when the customer has accepted the transaction and the process has verified that the customer is capable of paying the amount. Authorized means there is a reservation however the funds are not transferred from the customer’s account to the merchant’s account. In this state the merchant may change the amount of the transaction by modifying the line items on the transaction. Those modifications can be issued either via the web service API or via the user interface in our application. When no further modifications should be applied to the transaction has to be completed (see Completions).

Important
Not all payment methods support a reservation on the customer’s account. Hence some payment methods skip this state and switch directly to Completed.

The time the transaction remains in this state is controllable by the merchant. The merchant can issue the completion of the transaction over the web service interface.

Transactions can be completed via the back office or via the web service API. To see example request and more detailed information see the completion guide.

1.6Voided

The transaction is marked voided when an authorized but not completed transaction should not be processed anymore and hence is voided.

Important
This state is a final state. The transaction will not change the state anymore.

Transactions can be voided via the back office or via the web service API. To see example request and more detailed information see the void guide.

1.7Completed

When the transaction is in the state Completed the transfer of the money from the customer’s account to the merchant’s account has been initiated. The amount cannot be changed anymore. Completed does not mean that the goods or services can be delivered to the customer. Depending on the payment method the funds need to be transfered before the delivery can be fulfilled (i. e. pre-payment).

For every transaction we indicate whether the goods can be delivered now of whether the download should be allowed for your merchant. This is indicated by the state Fulfill and Decline. The merchant should wait until one of the final states are reached. The time the transaction remains in this state depends on the payment method and the processor. This can be only a few seconds or weeks. Some payment methods may require a manual decision. This manual decision process is handled by the delivery indication concept explained in Delivery Indications.

Example

When you offer Online Banking as payment method in your shop. The transaction will move to the state Completed once the transaction is completed. However, based on the payment method it can take up to one day until the provider is able to indicate to us if the money has arrived in your account. The transaction will stay in the state completed until we received this confirmation.

In the case there is not automatic process that allows us to notify that the money has arrived or is guaranteed by a third party then you will have to manually check if the payment has arrived and move the transactions manually in the state Fulfill or Decline.

1.8Fulfill

When the transaction is moved into Fulfill the merchant can start fulfilling the transaction. In case of physical goods the delivery process should be started.

Important
This is a final state.

1.9Decline

When the transaction is moved into the Decline state the merchant should decline the transaction and not fulfill the transaction. This state is typically set when the customer is not willing to pay or the chances are high that the customer is creating a charge back (suspicious transactions because of your fraud settings). More information why the transaction was moved to Decline can be found on the Delivery Indications object.

Important
This is a final state.
Note
Within the space there is a setting to automatically initiate a refund when this state is reached. This allows to automatically correct the accounting and automatically refund the transactions to the merchant. Use this function with caution.

2Completions

When the transaction is in state Authorized the merchant can modify the transaction. Those modifications are saved only in our application and are not communicated to the processor. Once no more modifications need to be applied on the transaction, the merchant needs to complete the transaction. The modifications as well as the completion can be issued over the web service interface and over the user interface in our application. The completion of a transaction is also known as capture or activate.

Transactions can be completed via the back office or via the web service API. To see example request and more detailed information see the completion guide.

2.1Single Completion

We allow only to send a single completion for a transaction in order to simplify and streamline the transaction process.

However you can provide us multiple modifications of the transaction. We store and send them all and send them to the processor once you confirm the transaction.

Note
In case you do not confirm the transaction it will be confirmed by the system based on your timeout setting. This can be set in → describe.

2.2Consider using Refunds in favor of Completions

Not all payment methods support the concept of completions. As a result modifications cannot be applied in all cases. For this reason, the process on the merchant side may need to be adapted per payment method.

To avoid that kind of specialization of the process on the merchant side we recommend not to use completions. All payment methods can be configured to directly switch to Completed. The merchant can issue subsequent modifications by creating refunds. This streamlines the process for the merchant, because only one single process has to be deployed.

Note
The behavior regarding direct completion can be set in the connector configuration Space > Payment > Configuration > Connectors. As described above it can be that this can not be set because the payment methods does have the concept of completions and will be captured directly.

3Delivery Indications

Delivery indications is a very important step in the transaction process as they give you a clear statement whether we recommend you to ship the goods based on the characteristics of the payment method. We investigated the process and guarantees of every payment method that we offer and therefore we can clearly state you whether the payment is most likely to be fulfilled or in some cases even better guaranteed by the provider.

3.1When should you activate the download or create a shipment?

Your application should trigger the shipping of a physical good or activate the download once the delivery indication is moved to Fulfill.

3.2Retrieving Delivery Indication for a transaction

You can fetch the delivery indication as follows. In case you have set up the webhooks correctly we will notify you once we have an update of the transaction and you should fetch the delivery indications from our service.