syntax = "proto3";

package wix.payment.api.pay.v3;

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

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

// This webhook is triggered whenever a payment transaction is updated (including refunds) via specific [Wix Apps](https://dev.wix.com/api/rest/wix-payments/about-wix-payments).
message PaymentEvent {

    option (wix.api.entity) = {
        fqdn: "wix.cashier.pay.v3.payment_event"
        segment: PUBLIC // no domain events produced, but the entity is sent to a topic cashier-payment-event
        app_def_id: "14bca956-e09f-f4d6-14d7-466cb3f09103"
    };

    // Unique event ID.
    string id                               = 1 [(wix.api.format) = GUID];

    // Event timestamp
    google.protobuf.Timestamp event_time    = 2;

    // ID of the [Wix app](https://dev.wix.com/docs/rest/articles/getting-started/wix-business-solutions) that triggered this event.
    string wix_app_id                       = 3 [(wix.api.maxLength) = 100];

    // Unique ID assigned to each Wix app in each site.
    string wix_app_instance_id              = 4 [(wix.api.format) = GUID];

    // Event type.
    EventType event_type                    = 5;

    // ID of Wix app that mediated between Wix Payments and the Wix app that triggered the event (if relevant).
    google.protobuf.StringValue managing_wix_app_id = 6 [(wix.api.maxLength) = 100];

    // Event details.
    oneof event {
        // `TRANSACTION_STATUS_CHANGED` event details.
        TransactionStatusChangedEvent transaction_status_changed_event              = 101;

        // `REFUND_STATUS_CHANGED` event details.
        RefundStatusChangedEvent refund_status_changed_event                        = 102;

        // `RECURRING_PAYMENT_STATUS_CHANGED` event details.
        RecurringPaymentStatusChangedEvent recurring_payment_status_changed_event   = 103 [deprecated = true, (.wix.api.field_deprecated) = {
            target_removal_date: "2026-06-30"
        }];

        // `TRANSACTION_UPDATED` event details.
        TransactionUpdatedEvent transaction_updated_event                           = 104;

        // `TRANSACTION_CREATED` event details.
        TransactionCreatedEvent transaction_created_event                           = 105;
    }

    enum EventType {
        UNDEFINED                           = 0 [(.wix.api.enum_maturity) = NOT_IMPLEMENTED];

        // Fired when a transaction's status changes.
        TRANSACTION_STATUS_CHANGED          = 1;

        // Fired when a refund's status changes.
        REFUND_STATUS_CHANGED               = 2;

        // Fired when a legacy subscription's status changes.
        RECURRING_PAYMENT_STATUS_CHANGED    = 3 [deprecated=true];

        // Fired when a transaction is updated.
        TRANSACTION_UPDATED                 = 4;

        // Fired when a transaction is created.
        TRANSACTION_CREATED                 = 5;
    }
}

message TransactionStatusChangedEvent {

    // Order details (limited to 30 items).
    Order order                                     = 1;

    // New transaction details.
    Transaction transaction                         = 2;

    // Previous transaction status.
    Transaction.TransactionStatus previous_status   = 3;
}

message RefundStatusChangedEvent {

    // Order details (limited to 30 items).
    Order order                         = 1;

    // Updated transaction details.
    Transaction transaction             = 2;

    // Updated refund details.
    Refund refund                       = 3;

    // Previous refund status.
    Refund.RefundStatus previous_status = 4;
}

message RecurringPaymentStatusChangedEvent {

    // Order details(limited to 30 items).
    Order order                                                 = 1;

    // Recurring payment status.
    RecurringPaymentStatus.Status status                        = 2;

    // Previous recurring payment status.
    RecurringPaymentStatus.Status previous_status               = 3;

    // Details of RecurringPayment cancellation (empty if `status` is not CANCELLED).
    RecurringPaymentCancellationDetails cancellation_details    = 4;
}

message TransactionUpdatedEvent {

    // Order details (limited to 30 items).
    Order order                                              = 1;

    // Updated transaction details.
    Transaction transaction                                  = 2;

    // Is event triggered by request to clean user data
    google.protobuf.BoolValue triggered_by_anonymize_request = 3;
}

message TransactionCreatedEvent {

    // Order details (limited to 30 items).
    Order order                                              = 1;

    // Updated transaction details.
    Transaction transaction                                  = 2;
}
