syntax = "proto3";

package wix.payment.api.pay.v2;

import "google/protobuf/timestamp.proto";
import "google/protobuf/wrappers.proto";
import "wix/api/entity.proto";
import "wix/api/validations.proto";
import "wix/api/annotations.proto";
import "wix/payment/api/pay/v2/resources/transaction.proto";
import "wix/payment/api/pay/v2/resources/order.proto";

option java_package = "com.wix.payment.api.pay.v2";

// describing a charge (ids, state and intent)
message Charge {

    option (wix.api.entity) = {
      fqdn: "wix.cashier.pay.v2.charge"
      segment: PUBLIC // no domain events produced
    };

    // charge ID
    string charge_id                    = 1;

    // ID of transaction related to this charge
    string transaction_id               = 2;

    ChargeIntent intent                 = 3;

    // order ID
    string order_id                     = 4;

    // state of the charge
    ChargeState state                   = 6;

    // deprecated, use payment_method_display_name
    string payment_method               = 10 [deprecated = true];
    // transaction payment method (internal original value)
    string payment_method_id            = 11;

    // transaction payment method display name (depends on payment provider)
    string payment_method_display_name  = 12;

    double amount                       = 13;

    string currency                     = 14 [(wix.api.format) = CURRENCY];

    // What kind of payment the buyer wants to perform: A one-time payment, a recurring payment, or an authorize
    // payment - authorize is when the provider reserves the funds from the user’s credit card, but doesn’t actually
    // charge them. This is usually done for ‘booking’ style flows, where the hotel reserves the booking amount but only
    // charges it when the guest arrives. Authorize flow is not fully supported by Cashier yet, work in progress.
    enum ChargeIntent {
        UNDEFINED       = 0;
        SALE            = 1;
        RECURRING       = 3;
    }
}

// Describing any additional changes to the charge entity before executing it
message ChargeExecution {
    // override order additional charges during charge execution (optional)
    OrderAdditionalCharges  additional_charges = 1;

    // override order amount during charge execution (optional)
    double amount = 2;
}

// state of the charge
message ChargeState {

    // current status of a transaction associated with charge
    TransactionStatus transaction_status  = 1;

    // in case transaction status is Declined/Failure may contain failure details (alpha)
    TransactionFailureDetails failure_details = 2;

    // contains specific provider data
    map<string, string> provider_data     = 3;

    // URL of page where user should be redirected as next step of payment flow.
    //
    // It might be URL to external payment system (PayPal etc) in case transaction status is `IN_PROCESS` or
    // `INITIALIZATION` or order return URL in case status is `APPROVED`/`PENDING`/`DECLINED`/`FAILED`/`CANCELED`
    string user_redirect_url               = 10;

    // external payment system url where user should be redirected to continue payment, can be in status `IN_PROCESS` or
    // `INITIALIZATION`
    string provider_redirect_url           = 11;

    // the action to perform if any
    oneof next_action {

        // A browser should issue an HTTP GET request and render the result.
        GetMethodRedirect get_method_redirect         = 121;

        // A browser should issue an HTTP POST request and render the result.
        PostMethodRedirect post_method_redirect       = 122;

        // A browser should display a barcode / barcode url to continue payment
        BarcodeDisplay barcode_display                = 123;

        // A client should interact with card reader
        CardReaderInteraction card_reader_interaction = 124;

        // A browser should show a QR code to continue payment.
        QrCodeDisplay qr_code_display                 = 125;

        // A browser should display an iframe with web page.
        // Redirect shouldn't be performed as it's designed to be embedded into checkout page.
        WebPageDisplay web_page_display               = 126;

        // A browser should issue a PayPal express checkout
        PayPalExpressAction pay_pal_window    = 127;
    }
}

// used by Payments Widget (decoding from Base64 token in ChargeResponse)
message ChargeResponseToken {
    string charge_id                            = 1;

    TransactionStatus.Status transaction_status = 2;

    google.protobuf.StringValue failure_code    = 3;

    google.protobuf.StringValue redirect_url    = 4;

    double amount                               = 5;

    string currency                             = 6 [(wix.api.format) = CURRENCY];

    string payment_method                       = 7;

    // the action to perform if any
    oneof next_action {

        // A browser should issue an HTTP GET request and render the result.
        GetMethodRedirect get_method_redirect         = 101;

        // A browser should issue an HTTP POST request and render the result.
        PostMethodRedirect post_method_redirect       = 102;

        // A browser should display a barcode / barcode url to continue payment
        BarcodeDisplay barcode_display                = 103;

        // A client should interact with card reader
        CardReaderInteraction card_reader_interaction = 104;

        // A browser should show a QR code to continue payment.
        QrCodeDisplay qr_code_display                 = 105;

        // A browser should display an iframe with web page.
        // Redirect shouldn't be performed as it's designed to be embedded into checkout page.
        WebPageDisplay web_page_display               = 106;
    }
}

message GetMethodRedirect {

    // a properly encoded URL to perform an HTTP GET request
    string url = 1 [(wix.api.format) = WEB_URL];
}

message PostMethodRedirect {

    message FormField {

        // the field name (not encoded)
        string name = 1 [(wix.api.minLength) = 1 /*, (wix.api.maxLength) = ? */];

        // the field value (not encoded)
        string value = 2 /* [(wix.api.maxLength) = ?]*/;
    }

    // a properly encoded URL to perform an HTTP POST request
    string url = 1 [(wix.api.format) = WEB_URL];

    // not yet encoded form fields to send with the POST request using the application/x-www-form-urlencoded content type
    repeated FormField fields = 2;
}

message BarcodeDisplay {

    // barcode value in decimal digits
    google.protobuf.StringValue barcode         = 1;

    // url to view / download barcode document
    google.protobuf.StringValue barcode_url     = 2;

    // date until barcode / barcode url are valid
    google.protobuf.Timestamp expiration_date   = 3;

    // address to send email with barcode payment details
    google.protobuf.StringValue billing_email   = 4 [(wix.api.format) = EMAIL, (.wix.api.pii) = true];
}

message QrCodeDisplay {

    /*
    QR code raw text payload.
    You can use any QR code generator library to convert it to an image.
    To see more details read [this article](https://www.thonky.com/qr-code-tutorial/introduction).
    */
    google.protobuf.StringValue payload = 1 [(wix.api.minLength) = 1, (wix.api.maxLength) = 1000];

    // Expiration timestamp.
    google.protobuf.Timestamp expiration_date = 2;
}

message WebPageDisplay {

    // a properly encoded URL to perform an HTTP GET request
    string url = 1 [(wix.api.format) = WEB_URL];

    // date until charge should be completed
    google.protobuf.Timestamp expiration_date = 2;
}

message CardReaderInteraction {
    // token for interaction with card reader
    google.protobuf.StringValue reader_token = 1;
}

message PayPalExpressAction {
    // Order Id for initiating PayPal express flow
    google.protobuf.StringValue pay_pal_order_id = 1 [(wix.api.maxLength) = 2048];
}
