AuthorizeRefund

The AuthorizeRefund-CUWO is responsible for authorizing a refund.

This is the first CUWO that is executed for a new refund. It is expected, that the CUWO collects any information that is needed (e.g., original invoice, what to refund) and then authorizes the refund.

The CUWO may receive an "invoice identifier". This is an identifier provided by the customer that requests the refund and that is to identify the original invoice/sales. The CUWO may be invoked without such an identifier. This means that the user chose to directly invoke the CUWO without entering an identifier. The CUWO must then ask the user for the identifier or use other means to determine "what to refund".

If the CUWO fails, it should try to release any authorization that has already been acquired. As that cannot be guaranteed, the enfore platform will execute the CancelRefund-CUWO to ensure the release of any authorization. Therefore, the AuthorizeRefund-CUWO must ensure that the CancelRefund-CUWO has enough information to work on. Either by storing the RefundRequest-ID on the external side or by providing the information via the "refund processing data".

Note: As CUWO can fail unexpectedly (e.g., power loss), the AuthorizeRefund-CUWO should provide "refund 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 CancelRefund-CUWO.

Workflow parameters

The AuthorizeRefund-CUWO will receive an AuthorizeRefundWorkflowParameters structure as input.

The structure is defined as:

/**
 * The parameter/input structure for an "authorize refund" workflow.
 */
class AuthorizeRefundWorkflowParameters extends WorkflowParameters {
    readonly "@type" : string = "n4.cuwo.workflows.refunds.authorizerefund.AuthorizeRefundWorkflowParameters";

    /**
     * The ID of the refund process.
     */
    public refundProcessID : string;

    /**
     * The identifier of the invoice that is to be (partially) refunded.
     *
     * This is the identifier provided by the customer that asks for the refund.
     * The enfore system has checked and determined that it does not know the
     * identifier (in the current organization) and thus invoked the CUWO to
     * allow it to check additional sources (old invoices not available to
     * enfore, invoices from different organizations, etc.).
     *
     * The CUWO may be invoked without such an identifier. This means that
     * the user chose to directly invoke the CUWO.
     */
    public invoiceIdentifier : String;

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

Success result

On success, the AuthorizeRefund-CUWO is expected to pass an AuthorizeRefundWorkflowResult structure to terminateSuccess.

The structure is defined as:

/**
 * The result/output structure for a successful "authorize refund" workflow.
 */
class AuthorizeRefundWorkflowResult extends WorkflowResult {
    readonly "@type" : string = "n4.cuwo.workflows.refunds.authorizerefund.AuthorizeRefundWorkflowResult";

    /**
     * The amount that has been authorized to be refunded.
     */
    public refundAmount : Money;

    /**
     * A human-readable reference identifying the refund that will be shown/printed as
     * part of the payout UI/receipt.
     *
     * This is an "external identifier" for the enfore platform, so it will only be stored,
     * shown in the refund/sales UI of the enforePOS client and passed to subsequent CUWOs
     * such as ProcessRefund or CancelRefund.
     *
     * 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 refund in the external system or call the external systems support hotline and
     * be able to provide some kind if reference.
     */
    public refundReference : string;

    /**
     * An optional date for the refund reference that will be shown/printed as part of the
     * payout UI/receipt.
     */
    public refundReferenceDate : Date?;

    /**
     * The issuer of the authorized refund.
     * 
     * The the OrganizationReference stucture can either is can either be a
     * "CurrentOrganizationReference" or an "OtherOrganizationReference".
     * When using "OtherOrganizationReference", the enfore platform will
     * check if the current organization already has an organization contact
     * with the specified ID. If one exists, it is used and the specified
     * name is ignored. If no such contact exists, a new one is created using
     * the specified name.
     */
    public refundIssuer : OrganizationReference;

    /**
     * Optional processing data of the refund.
     *
     * This data will be stored with the refund process and passed to subsequent CUWOs
     * such as ProcessRefund or CancelRefund.
     *
     * Same as the refundReference, this data is not interpreted by the enfore platform
     * in any way. But other than the refundReference, this data is not shown in any
     * kind of user interface.
     */
    public refundProcessingData? : string;

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

Failure result

On failure, the AuthorizeRefund-CUWO is expected to pass an AuthorizeRefundWorkflowFailure structure to terminateFailure.

The structure is defined as:

/**
 * The result/output structure for a failed "authorize refund" workflow.
 */
class AuthorizeRefundWorkflowFailure extends WorkflowFailure {
    readonly "@type" : string = "n4.cuwo.workflows.refunds.authorizerefund.AuthorizeRefundWorkflowFailure";

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

    /**
     * A failure code specific to the CUWO.
     *
     * 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 UI.
     */
    public failureCode? : string;

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

Cancelation result

On cancelation, the AuthorizeRefund-CUWO is expected to pass an AuthorizeRefundWorkflowCancelation structure to terminateCanceled.

The structure is defined as:

/**
 * The result/output structure for a canceled "authorize refund" workflow.
 */
class AuthorizeRefundWorkflowCancelation extends WorkflowCancelation {
    readonly "@type" : string = "n4.cuwo.workflows.refunds.authorizerefund.AuthorizeRefundWorkflowCancelation";

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