syntax = "proto3";

package wix.payment.api.pay.v2;

import "wix/payment/api/pay/v2/resources/mandatory-field.proto";
import "google/api/annotations.proto";
import "wix/api/entity.proto";

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

// Mandatory fields service
service MandatoryFieldService {

    option (wix.api.service_entity).message = "wix.payment.api.pay.v2.MandatoryField";

    // Returns information about the mandatory fields required by a given
    // provider in a given country.
    //
    // It is also possible to check which fields are missing for a given order.
    //
    // **Auth rules**
    //
    // Requires a person identity to be present.
    //
    // When `order_id` is passed, person identity must have permission to read
    // this order. Only user created the order and site owner have permission to
    // view this order.
    //
    // You can find more information about authentication and authorization in a
    // separate [guide][1].
    //
    // **Error responses**
    //
    // - 401 - person identity is missing.
    // - 403 - when `order_id` is passed, but passed identity does not have
    //   permission to read this order.
    //
    //   [1]: ../../guides/Authentication%20and%20authorization
    rpc List(ListMandatoryFieldsRequest) returns (ListMandatoryFieldsResponse) {
        option (google.api.http) = {
            get: "/api/payments/v2/mandatory-fields"
            additional_bindings {
                get: "/api/payments/v2/orders/{order_id}/mandatory-fields"
            }
        };
    }
}

message ListMandatoryFieldsRequest {
    // provider name (required)
    string provider         = 1;

    // country code (ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3) (optional)
    string country          = 2;

    // order snapshot id (optional)
    //
    // when provided returns all fields that are mandatory, but missing for
    // specified order
    string order_id         = 3;

    // payment method (optional)
    string payment_method   = 4;
}

message ListMandatoryFieldsResponse {
    // fields that buyer needs to fill in order to process payment with specified provider
    repeated MandatoryField mandatory_fields = 1;
}
