Extension points - External Payment Methods

While the enfore platform has built-in handling for various payment methods such as cash, card payments via Donner/ZVT, enfore sales vouchers, enfore customer accounts, etc., the number of payment methods available in the world is essentially unlimited since every day, new methods can be added. Also, many payment methods are also only used by a small set of businesses/customers. Therefore, it is not feasible for enfore to provide built-in support for every existing or upcoming payment method. Instead, we aim to provide a framework that allows businesses/integrators to integrate additional payment methods on their own.

The choice of CUWOs for that integration stems from the fact that most, if not all, payment methods require some kind of user interface. For example, the customer will surely need to enter/provide some credentials to authorize a payment. A CUWO has the additional benefit that the enfore platform does not "see" the information (e.g., credentials) entered by the user. The platform provides the CUWO with a runtime environment but is not involved in the actual user/UI interaction.

In general, the enfore platform processes payments as a "payment request" that goes through the following steps:

  • Started - newly create PR, payment amount has not been reserved or moved yet
  • Authorized - payment amount has been reserved/approved (e.g., by a payment provider)
  • Captured - payment amount has been granted/transferred to the merchant
  • Booked - payment amount has been booked into the merchant's accounting system

Additionally, payment requests can "Fail" or become "Canceled".

Also note that not every payment method supports the distinction between "Authorized" and "Captured". For example, a basic cash payment does not have a "Authorization" stage but is immediately "Captured" when the customer has handed over the money.

Note that transitions from "Authorized" or "Captured" to "Canceled" only occur after a previous authorization/capture of money has been released/reverted. And that transitions from "Authorized" or "Captured" to "Failed" only occur after that release/reversal failed.

For the built-in payment methods, the enfore platform contains the logic to perform the operations necessary to transition the states of the payment/payout requests. For CUWO-based external payment methods, that logic must be provided by the CUWOs. Thus, we will define the following new CUWO extension points for the enfore platform:

  • for payments
    • AuthorizeOrCapturePayment
    • CapturePayment
    • CancelPayment
    • RevertPayment
  • for payouts
    • GrantPayout
    • CancelPayout

For payments, the possible activity flow looks like this:

For payouts, the flow is similar:

About abortion of CUWOs

A CUWO normally ends itself by invoking the terminateSuccess or terminateFailure methods of the CUWOCallback API that is injected into the browser instance by enforePOS.

For cases where the CUWO does not end itself, e.g. when the CUWO application could not be loaded or has bugs, the enforePOS UI wrapper around the CUWO window provides a way to cancel/abort a CUWO. There is a process in place how that UI and the CUWO interact to provide the CUWO with a way to gracefully terminate itself but also ensure that an unresponsive CUWO does not block the enforePOS runtime. See the Aborting Workflows in the CUWO documentation about more details.

When any of the payment/payout-related CUWOs becomes unresponsive and needs to be terminated by the enforePOS runtime, that CUWO will be treated as "failed" as the status of the payment/payout is unknown to the enfore platform.

For example, when an AuthorizeOrCapturePayment CUWO needed to be terminated, the enforePOS runtime will invoke a CancelPayment CUWO as must assume that the AuthorizeOrCapturePayment CUWO has already authorized or captured something. Independent of the result status of the CancelPayment CUWO, the payment request will be marked as failed. The enfore runtime will keep track of which CUWO was invoked and how it terminated (success, failure, cancel) to support investiation of failed payments.