AuthorizeOrCapturePayment

The AuthorizeOrCapturePayment-CUWO is responsible for authorizing or capturing the amount for a payment request.

This is the first CUWO that is executed for a new payment request. It is expected, that the CUWO collects any information that is needed (e.g., user credentials) and then authorizes the payment. If the payment method does not perform separate authorization/capture, the CUWO is allowed to directly capture the amount. This must be reflected in the return status.

The CUWO received a "requested amount". This is the amount to be paid and may already include tip. The amount of tip included in the requested amount is available via the includedTipAmount parameter.

Depending on configuration (via the EPM), the CUWO may authorize/capture an amount different from the requested amount. An authorized/captured amount less than the requested amount means that the customer wants to reduce tip and/or make a partial payment. An authorized/captured amount greater than the requested amount means that the customer has given a (additional) tip (i.e., any excess amount is treated as tip).

For the CUWO to end as "canceled", it must not have any authorized or captured amount. If the CUWO has already authorized/captured the amount and cannot release it, it must not end with "canceled" but with "failed".

If the CUWO fails, it should try to release any amount is may have already authorized/captured. As that cannot be guaranteed, the enfore platform will execute the CancelPayment-CUWO to ensure the release of any authorization. Therefore, the AuthorizeOrCapturePayment-CUWO must ensure that the CancelPayment-CUWO has enough information to work on. Either by storing the PaymentRequest-ID on the external side or by providing the information via the "payment processing data".

Note: As CUWO can fail unexpectedly (e.g., power loss), the AuthorizeOrCapturePayment-CUWO should provide "payment processing data" as soon as possible while it is still running and not just as return value. Then, in case of an unexpected termination, the enfore platform can provide that data to the CancelPayment-CUWO.

Workflow parameters

The AuthorizeOrCapturePayment-CUWO will receive an AuthorizeOrCapturePaymentWorkflowParameters structure as input.

The structure is defined as:

/**
 * The parameter/input structure for an "authorize or capture payment" workflow.
 */
class AuthorizeOrCapturePaymentWorkflowParameters extends WorkflowParameters {
    readonly "@type" : string = "n4.cuwo.workflows.paymentsandpayouts.authorizeorcapturepayment.AuthorizeOrCapturePaymentWorkflowParameters";

    /**
     * The ID of the payment request for which the payment is to be authorized/captured.
     */
    public paymentRequestID : string;

    /**
     * The amount requested for the payment.
     *
     * Note that, depending on settings, the CUWO may process an amount that differs
     * from the requested one.
     */
    public requestedAmount : Money;

    /**
     * The amount of tip that is included in the requested amount.
     */
    public includedTipAmount : Money;

    /**
     * Information about the invoices/credit memos that the payment is to be made for.
     * 
     * Note that the enfore platform currently only supports payments for single invoices/
     * credit memos. The list is used as that functionality is planned to be extended in
     * the future.
     */
    public invoiceOrCreditMemoInformation : DataList<InvoiceOrCreditMemoInformation>

    /**
     * Information about the customer that is to pay the requested amount.
     */
    public customerInformation : CustomerInformation;

    /**
     * Identifiers available for identification of the customer that
     * uses the external payment method.
     */
    public customerIdentifiers : DataList<CustomerIdentifier>;

    /**
     * Information about the context in which the CUWO is executed.
     */
    public cuwoContextInformation : CUWOContextInformation;

    /**
     * Holds a reference to and configuration of the external payment method that the CUWO
     * belongs to. 
     */
    public paymentMethodConfiguration : PaymentMethodConfiguration
}

Success result

On success, the AuthorizeOrCapturePayment-CUWO is expected to pass an AuthorizeOrCapturePaymentWorkflowResult structure to terminateSuccess.

The structure is defined as:

/**
 * The result/output structure for a successful "authorize or capture payment" workflow.
 */
class AuthorizeOrCapturePaymentWorkflowResult extends WorkflowResult {
    readonly "@type" : string = "n4.cuwo.workflows.paymentsandpayouts.authorizeorcapturepayment.AuthorizeOrCapturePaymentWorkflowResult";

    /**
     * The status of the payment.
     * 
     * Must be CAPTURED, if the money has been captured/collected or AUTHROIZED,
     * if the money has only been authorized.
     */
    public status : AuthorizeOrCapturePaymentWorkflowResultStatus;

    /**
     * The amount that has been captured or authorized.
     * 
     * Note that, depending on settings, the external payment processor and user choices, that
     * amount may differ from the amount that was requested to be authorized/captured.
     * 
     * If the processed amount is more than the requested amount, the excess amount
     * is treated as (additional) tip.
     * 
     * If the processed amount is less than the requested amount, the reduction is applied
     * to the tip first. Any reduction beyond the tip causes the payment request to become
     * a partial payment. This then usually leads to a second payment request being created
     * to pay for the remaining amount. This second payment request usually uses a different
     * payment method then though.
     */
    public processedAmount : Money;

    /**
     * A human-readable reference identifying the payment.
     * 
     * This is an "external identifier" for the enfore platform, so it will only be stored,
     * shown in the payment/sales UI of the enforePOS client and passed to subsequent CUWOs
     * such as CapturePayment or CancelPayment.
     * 
     * The reason for requiring this reference is that even when all subsequent processing
     * including CUWOs does not work, there is a way for the merchant/customer to look up
     * the payment in the external system or call the external systems support hotline and
     * be able to provide some kind if reference.
     */
    public paymentReference : string;

    /**
     * Optional payment processing data of the payment.
     * 
     * This data will be stored with the payment request and passed to subsequent CUWOs
     * such as CapturePayment or CancelPayment.
     * 
     * Same as the paymentReference, this data is not interpreted by the enfore platform
     * in any way. But other than the paymentReference, this data is not shown in any
     * kind of user interface.
     */
    public paymentProcessingData? : string;

    /**
     * Additional information to be stored with/printed on the payment
     * receipt/invoice for the payment.
     */
    public customReceiptDocumentInformation? : DataList<CustomDocumentInformation>
}

Failure result

On failure, the AuthorizeOrCapturePayment-CUWO is expected to pass an AuthorizeOrCapturePaymentWorkflowFailure structure to terminateFailure.

The structure is defined as:

/**
 * The result/output structure for a failed "authorize or capture payment" workflow.
 */
class AuthorizeOrCapturePaymentWorkflowFailure extends WorkflowFailure {
    readonly "@type" : string = "n4.cuwo.workflows.paymentsandpayouts.authorizeorcapturepayment.AuthorizeOrCapturePaymentWorkflowFailure";

    /**
     * The reason for the failure.
     */
    public failureReason : AuthorizeOrCapturePaymentWorkflowFailureReason;

    /**
     * A failure code specific to the payment method.
     * 
     * The enfore platform simply stores that code and displays it to the user but does
     * not understand it or base any processing on it.
     * 
     * This enables storing a short error identifier from an external system in a way
     * that allows it to be shown in the enforePOS sales/payment history UI.
     */
    public failureCode? : string;

    /**
     * Optional update for the payment processing data of the payment.
     *
     * When provided, replaces the previously stored payment processing
     * data. When not provided, a previously stored payment processing
     * data stays unchanged.
     */
    public paymentProcessingData? : string;
}

Cancelation result

On cancelation, the AuthorizeOrCapturePayment-CUWO is expected to pass an AuthorizeOrCapturePaymentWorkflowCancelation structure to terminateCanceled.

The structure is defined as:

/**
 * The result/output structure for a canceled "authorize or capture payment" workflow.
 */
class AuthorizeOrCapturePaymentWorkflowCancelation extends WorkflowCancelation {
    readonly "@type" : string = "n4.cuwo.workflows.paymentsandpayouts.authorizeorcapturepayment.AuthorizeOrCapturePaymentWorkflowCancelation";

    /**
     * The reason for the cancelation.
     */
    public cancelationReason : AuthorizeOrCapturePaymentWorkflowCancelationReason;
}