Broadleaf Microservices
  • v1.0.0-latest-prod

Handling Failures

Issues with Capturing

In these scenarios, the fulfillment has gone into the PAYMENT_CAPTURE_FAILED status which will be shown to the admin.

Indeterminate Result

The payment capture transaction failed with an "indeterminate result" meaning Broadleaf attempted the capture with the payment processor, but an error occurred and it is not known whether the transaction succeeded or not.

Situations leading to this result:
  • A network error prevents us from receiving the response

  • The processor returns an unexpected error (e.g. 500 internal server error)

  • The response is received, but cannot be recorded because a Broadleaf service or database is down

How to recover:
  • The admin will need to check in the Payment Processor to see whether the customer was successfully charged completely or not

    • If the charge was successful or the admin was able to manually capture the payment, the fulfillment’s status can be updated to PAYMENT_CAPTURED through the Admin portal, or with an API call

    • If the charge was not successful, see below for how to resolve "Capture Failed"

Capture Failed

If the payment transaction is not "indeterminate result" then the capture failed due to some problem with the payment.

Situations leading to this result, and their recovery options:
  • The payment is no longer valid to be captured, e.g. a credit card has expired or been cancelled

    • Since this payment can no longer be used, the customer will need to attempt the purchase again

    • The admin should cancel the original fulfillment through the Admin portal or with an API call

  • The order has multiple payments, and only one is no longer able to be captured

    • The customer will need to attempt the purchase again

    • The admin should cancel the original fulfillment so that all authorized funds are released

    • The admin should check the transactions on the order to see if any of the multiple payments already succeeded in capturing for this fulfillment. If so, they will need to refund those manually outside of Broadleaf with the payment processor.

Issues Updating Fulfillment

Fulfillment Status is not Changed after Capture

The payment capture was attempted, but the fulfillment was not updated out of the CAPTURING_PAYMENT status.

Situations leading to this result:

If the capture is attempted, normally the Fulfillment status is then updated to either PAYMENT_CAPTURED or PAYMENT_CAPTURE_FAILED. However, if the OrderService or its database are down, the fulfillment status will not be updated, and will be stuck in the CAPTURING_PAYMENT state.

How to recover:

An admin will need to check the result of the capture transactions. They can then use the Broadleaf admin portal or an API call to "override" the CAPTURING_PAYMENT fulfillment into the appropriate status, either PAYMENT_CAPTURED or PAYMENT_CAPTURE_FAILED.