GrantPayout

The GrantPayout-CUWO is responsible for granting a payout. There is no distinction between "authorizing" and "capturing" for payouts, so only a single "grant" operation is used.

It is expected, that the CUWO collects any information that is needed (e.g., user credentials) and then performs the payout.

For the CUWO to end as "canceled", it must not have performed the payout. If the CUWO has already performed it and cannot revert it, it must not end with "canceled" but with "failed".

If the CUWO fails, it should try to revert any payout amount it may have granted. As that cannot be guaranteed, the enfore platform will execute the CancelPayout-CUWO to ensure the reversal. Therefore, the GrantPayout-CUWO must ensure that the CancelPayout-CUWO has enough information to work on. Either by storing the PayoutRequest-ID on the external side or by providing the information via the "payout processing data".

Workflow parameters

The GrantPayout-CUWO will receive an GrantPayoutWorkflowParameters structure as input.

The structure is defined as:

/**
 * The parameter/input structure for an "grant payout" workflow.
 */
class GrantPayoutWorkflowParameters extends WorkflowParameters {
    readonly "@type" : string = "n4.cuwo.workflows.paymentsandpayouts.grantpayout.GrantPayoutWorkflowParameters";

    /**
     * The ID of the payout request for which the payout is to be granted.
     */
    public payoutRequestID : string;

    /**
     * The amount requested for the payout.
     *
     * Note that, for now, the CUWO must process exactly that amount. Partial payouts
     * or "over payout" are not supported.
     */
    public requestedAmount : Money;

    /**
     * Information about the invoices/credit memos that the payout is to be made for.
     * 
     * Note that the enfore platform currently only supports payouts 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 receive 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 GrantPayout-CUWO is expected to pass an GrantPayoutWorkflowResult structure to terminateSuccess.

The structure is defined as:

/**
 * The result/output structure for a successful "grant payout" workflow.
 */
class GrantPayoutWorkflowResult extends WorkflowResult {
    readonly "@type" : string = "n4.cuwo.workflows.paymentsandpayouts.grantpayout.GrantPayoutWorkflowResult";

    /**
     * The amount that has been granted.
     * 
     * Note that, for now, this must be equal to the requested amount.
     */
    public processedAmount : Money;

    /**
     * A human-readable reference identifying the payout.
     * 
     * 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 CancelPayout.
     * 
     * 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 payout in the external system or call the external systems support hotline and
     * be able to provide some kind if reference.
     */
    public payoutReference : string;

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

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

Failure result

On failure, the GrantPayout-CUWO is expected to pass an GrantPayoutWorkflowFailure structure to terminateFailure.

The structure is defined as:

/**
 * The result/output structure for a failed "grant payout" workflow.
 */
class GrantPayoutWorkflowFailure extends WorkflowFailure {
    readonly "@type" : string = "n4.cuwo.workflows.paymentsandpayouts.grantpayout.GrantPayoutWorkflowFailure";

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

    /**
     * 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 payout processing data of the payout.
     * 
     * This data will be stored with the payout request and passed to subsequent CUWOs
     * such as CancelPayout.
     * 
     * Same as the payoutReference, this data is not interpreted by the enfore platform
     * in any way. But other than the payoutReference, this data is not shown in any
     * kind of user interface.
     */
    public payoutProcessingData? : string;
}

Cancelation result

On cancelation, the GrantPayout-CUWO is expected to pass an GrantPayoutWorkflowCancelation structure to terminateCanceled.

The structure is defined as:

/**
 * The result/output structure for a canceled "grant payout" workflow.
 */
class GrantPayoutWorkflowCancelation extends WorkflowCancelation {
    readonly "@type" : string = "n4.cuwo.workflows.paymentsandpayouts.grantpayout.GrantPayoutWorkflowCancelation";

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