This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

Payment lifecycle

Learn about the payment lifecycle in digital commerce and how commercetools Checkout handles it.

commercetools Checkout manages the following stages of a payment lifecycle:

  • Authorization
  • Payment capture
  • Authorization cancellation
  • Refund

Authorization

It is the first stage in a payment process, during which a customer is verified for sufficient funds or credit to complete the payment transaction.

If an authorization is successful, the given amount is reserved and not deducted from the customer's account. The payment is put on hold for a specific period of time (typically between a few days to a week) and the funds will not be available for other transactions during this time.

If the designated timeframe elapses and the funds are not captured meanwhile, the authorization expires and the reserved funds are released. As a result, the customer regains access to these funds, making them available for other transactions.

How Checkout manages authorizations

When a customer clicks the final button in a checkout process, the following takes place:

  1. Checkout creates a Payment containing the selected payment method and a Transaction with state=Initial.
  2. Checkout sends a payment request to the Payment Service Provider (PSP) to authorize the Payment.
  3. Since the authorization request is asynchronous—while the PSP processes the Payment—Checkout sets the state of the Transaction to Pending and creates an Order.
  4. The PSP notifies Checkout about the authorization outcome and, depending on the outcome, the state of the Transaction is set to Success or Failure.

Payment capture

During this stage, an authorized Payment amount is captured—meaning the funds are deducted from a customer's account and transferred to the merchant’s account.

The PSP executes payment capture automatically, if an auto capture process is configured; or any merchant process can manually trigger the process during the processing of an Order.
It might happen after the Order is created—when the goods are ready to be delivered, or in any other business scenario.

How Checkout manages payment captures

The process to capture funds after an Order is created is a business decision and your responsibility, as a merchant.

If you trigger payment capture manually through a process, you can request payment capture to the PSP using the Checkout Payments API. After sending the request, Checkout adds a Transaction of type=Charge to the existing Payment inside the Order.

If the capture is triggered by the PSP through an auto capture process, Checkout adds a Transaction of type=Charge after it's notified by the PSP.

Authorization cancellation

In this stage, an authorization is voided before a payment is captured, allowing the customer to access the reserved funds again. This is typically done when an order must be cancelled, for example, when a customer requests to cancel the order or when the order cannot be fulfilled.

How Checkout manages authorization cancellations

Cancelling an authorization is outside the scope of Checkout—similar to payment capture—as it occurs after an Order is created. However, using the Checkout Payments API, you can request the Payment cancellation to the PSP. After sending the request, Checkout adds a Transaction of type=CancelAuthorization to the existing Payment inside the Order.

Refund

In this stage, a captured payment is returned to the customer for a given order. It occurs when the customer requests a refund, goods are returned, or you need to reimburse the customer for any reason. Depending on the scenario, a refund can be partial or full and cannot exceed the captured amount.

How Checkout manages refunds

You can request a refund to the PSP using the Checkout Payments API. After sending the request, Checkout adds a Transaction of type=Refund to the existing Payment inside the Order, along with the amount to be refunded.

As several partial refunds can happen during the payment lifecycle, you can refund Payment multiple times, as long as the amount to refund does not exceed the total amount of the original Payment.

Payments in the Merchant Center

Payments created by Checkout can be viewed in the Merchant Center from an Order's detail page. To access the Payments related to an Order, go to Orders > Order list, select the Order, and then click the Payments tab.

The following Payment information are available:

  • Payment method: the payment method used by the customer for the Order
  • Payment service provider (PSP): the Payment Service Provider associated with the payment method
  • Payment provider ID: the identifier assigned by the PSP on its system for the payment
  • Amount planned: the total amount of the Payment
  • Payment transactions: the Transactions added to the Payment during its lifecycle and the related information

FAQs

When should I start fulfilling an Order?

As PSPs work asynchronously, regardless of the first response to an authorization request that they return, you must wait for a notification that confirms the authorization of the Payment. To receive notifications about Payment updates, you can use Subscriptions.

You should start fulfilling an Order only if the Payment contains a Transaction whose type=Authorization and state=Success.

What happens if an Order was created but the PSP does not authorize the Payment?

If the PSP does not authorize the Payment, Checkout updates the Payment by setting the state of the Transaction of type=Authorization to Failure. However, it's your responsibility to decide how to proceed with the created Order.

What happens if an Order was not created but the PSP authorized the Payment?

After a Payment is authorized or captured, Checkout updates it accordingly. However, due to unpredictable errors, it can happen that a Cart might not be converted into an Order. In such a case, for example, you can cancel the Payment or create the Order again.

To receive notifications and react to similar scenarios, it's your responsibility to use Subscriptions.