//flynt-disable field-type-breaking-change, renamed-field-breaking-change
syntax = "proto3";


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

import "google/api/annotations.proto";
import "google/protobuf/wrappers.proto";
import "google/protobuf/timestamp.proto";
import "wix/api/entity.proto";
import "wix/api/annotations.proto";
import "wix/api/validations.proto";
import "wix/api/api_errors.proto";
import "wix/api/permissions.proto";
import "wix/payment/api/pay/v2/upstream/wix/common/address.proto";

service PrivateProviderChargeService {

  option (wix.api.service_maturity) = NOT_IMPLEMENTED;
  option (wix.api.service_exposure) = PRIVATE;

  // Performs charge on provider and return resulting object
  rpc ProviderCharge(ProviderChargeRequest) returns (ProviderChargeResponse) {
    option (wix.api.permission).name = "PAYMENTS.PRIVATE_PROVIDER_CHARGE";
  };
}

message ProviderChargeRequest {
  // Payment provider id to send request to
  string payment_provider_id = 1 [(.wix.api.minLength) = 1, (.wix.api.maxLength) = 100];

  // Payment method used for the transaction, as of now only CC is supported.
  PaymentMethod payment_method = 2;

  // Credentials that the PSP provided when the merchant connected their account.
  string merchant_credentials = 3 [(wix.api.minLength) = 1, (wix.api.maxLength) = 2048];
  // todo(charges) this is from Refund API, are we 100% sure limit 2048 is ok? Some PP creds can be quite long

  // information about buyer: addresses, ip/id, language etc.
  BuyerInformation buyer_information = 4;

  // information about money amounts sent to provider
  Amounts amounts = 5;

  // Order line items.
  repeated Item items = 6 [(.wix.api.maxSize) = 100];

  // Details of the flow performed: How specifically this charge should be paid
  FlowInfo flow_info = 7;

  // Wix Charge id
  // Some providers need this in the metadata or for the webhook purposes
  string charge_id = 10 [(.wix.api.format) = GUID];
  // Order/payment intent id
  string payment_intent_id = 11 [(.wix.api.format) = GUID];

  // Structure that stores all data passed by clients that we may need to pass to provider
  ExternalData external_data = 12;

  // Charge idempotency key, todo(charges) do we need it?
  string idempotency_key = 20 [(.wix.api.minLength) = 1, (.wix.api.maxLength) = 100];

  // url of seller site, maybe move to some category?
  google.protobuf.StringValue site_url = 30 [(.wix.api.maxLength) = 1000, (wix.api.format) = WEB_URL]; // todo is WEB_URL ok here?

  // deprecated field, for backward compatibility only (mostly reporting)
  PaymentClient payment_client = 100;

  message ExternalData {
    // Transaction/charge id in the vertical
    // think if we need it
    // think if we need external order id as well
    // think if the name should be transaction or charge
    string external_transaction_id = 1 [(.wix.api.format) = GUID];

    // Corresponding invoice ID within the external entity that made the request.
    google.protobuf.StringValue external_invoice_id = 2 [(wix.api.minLength) = 1, (wix.api.maxLength) = 36];

    // Order ID provided by the external entity that initiated the request.
    google.protobuf.StringValue external_order_id = 3 [(wix.api.minLength) = 1, (wix.api.maxLength) = 36];

    // Customer ID provided by the external entity that initiated the request.
    google.protobuf.StringValue external_buyer_id = 4 [(wix.api.minLength) = 1, (wix.api.maxLength) = 36];

    // Metadata to store within the created transaction.
    map<string, string> metadata = 5 [(wix.api.maxSize) = 16];
  }

  message Amounts {
    // currency of the charge
    google.protobuf.StringValue currency = 1 [(wix.api.format) = CURRENCY];
    // total amount to be charged
    google.protobuf.StringValue total = 2 [(wix.api.decimalValue) = {gt: "0", maxScale: 8}];
    // tax amount of the charge
    google.protobuf.StringValue tax = 10 [(wix.api.decimalValue) = {gt: "0", maxScale: 8}];
    // shipping amount of the charge
    google.protobuf.StringValue shipping = 11 [(wix.api.decimalValue) = {gt: "0", maxScale: 8}];
    // discount amount of the charge
    google.protobuf.StringValue discount = 12 [(wix.api.decimalValue) = {gt: "0", maxScale: 8}];

    // application fee to be transferred to the platform. Isn't part of the breakdown
    google.protobuf.StringValue application_fee = 20 [(wix.api.decimalValue) = {gt: "0", maxScale: 8}];
  }

  message NetworkReference {

    // Transaction ID assigned by a card scheme (Trace ID for Mastercard or Transaction ID for Visa).
    string network_transaction_id = 1 [(wix.api.minLength) = 1, (wix.api.maxLength) = 1000];

    // Transaction ID assigned by 3D Secure 2 directory server.
    google.protobuf.StringValue ds_transaction_id = 2 [(wix.api.minLength) = 1, (wix.api.maxLength) = 1000];
  }

  message RecurringInfo {
    // Reference to the transaction that was used to create the payment agreement.
    google.protobuf.StringValue reference_transaction_id = 1 [(.wix.api.format) = GUID];
    // Reference to the method used by the network
    NetworkReference network_reference = 2;
  }

  //flynt-disable deleted-field-enum-reserved
  message FlowInfo {
    enum CheckoutType {
      REGULAR = 0;
      EXPRESS = 1;
    }
    // checkout type used to perform the charge
    CheckoutType checkout_type = 1;
    // checkout session id
    google.protobuf.StringValue checkout_session = 2 [(.wix.api.maxLength) = 1000];
    // is this transaction a test/sandbox transaction
    google.protobuf.BoolValue sandbox = 3;
    // Request charge to be made using strong customer authentication e.g. 3-D Secure.
    google.protobuf.BoolValue sca_requested = 10;

    // Indicates if the charge is off-session.
    // Off-session charges are charges that are initiated by the merchant on behalf of the customer
    // e.g. charging a customer for a late fee or an incidental for a car rental
    // or automatically e.g. subscription renewal.
    google.protobuf.BoolValue off_session = 11;

    // Indicates if the charge is a mail order/telephone order (MOTO).
    google.protobuf.BoolValue moto = 12;

    // Indicates if the charge is an unscheduled merchant initiated payment.
    google.protobuf.BoolValue unscheduled_mit = 13;

    // Indicates that you intend to make future payments with payment method used in this charge.
    // If it’s set to true than payment agreement will be created after charge succeeds.
    google.protobuf.BoolValue setup_future_usages = 14;

    // Number of installments (must be greater than 1 to trigger payment in installments).
    google.protobuf.Int32Value installment_count = 15 [(wix.api.min) = 2, (wix.api.max) = 1000];
    // recurring payment details
    RecurringInfo recurring_info = 20;

    // Redirect URLs for different payment outcomes. PSP-hosted payment pages use these URLs to redirect
    // the buyer back to the merchant’s site.
    ReturnUrls return_urls = 21;
  }

  message PaymentMethod {
    // Id of payment method. As of now only 'credit_card' is supported
    string type_id = 1 [(wix.api.minLength) = 1, (wix.api.maxLength) = 50];

    // Details of the payment method
    oneof payment_method_details {
      // Details of the card payment method
      CardPayment card = 2;
      
      // Details of the Apple Pay payment method
      ApplePayPayment apple_pay = 3;
    }
  }

  message CardPayment {
    // the card number token
    string number_token = 1 [(wix.api.minLength) = 1, (wix.api.maxLength) = 1000];

    // the month of the card expiration date
    google.protobuf.Int32Value expiration_month = 2 [(wix.api.min) = 1, (wix.api.max) = 12];

    // the full year of the card expiration date
    google.protobuf.Int32Value expiration_year = 3 [(wix.api.min) = 2000, (wix.api.max) = 2099];

    // the cardholder name printed on the card
    google.protobuf.StringValue holder_name = 4 [(wix.api.minLength) = 1, (wix.api.maxLength) = 1000];

    // the CVV/CVC/CID token
    google.protobuf.StringValue security_code_token = 5 [(wix.api.minLength) = 1, (wix.api.maxLength) = 1000];
  }

  message ApplePayPayment {
    // D-PAN token
    string dpan_token = 1 [(wix.api.minLength) = 1, (wix.api.maxLength) = 1000];

    // Month of the D-PAN card expiration date.
    google.protobuf.Int32Value expiration_month = 2 [(wix.api.pii) = true, (wix.api.min) = 1, (wix.api.max) = 12];

    // Full year of the D-PAN card expiration date.
    google.protobuf.Int32Value expiration_year = 3 [(wix.api.pii) = true, (wix.api.min) = 2000, (wix.api.max) = 2099];

    // Online payment cryptogram aka 3ds 2.0 challenge result.
    string online_payment_cryptogram = 4 [(wix.api.minLength) = 0, (wix.api.maxLength) = 1000];

    // ECI indicator.
    google.protobuf.StringValue eci = 5 [(wix.api.minLength) = 1, (wix.api.maxLength) = 1000];

    // Card holder name
    google.protobuf.StringValue cardholder_name = 6 [(wix.api.minLength) = 1, (wix.api.maxLength) = 1000];

    // Hex-encoded device manufacturer identifier
    google.protobuf.StringValue device_manufacturer_id = 7 [(wix.api.minLength) = 1, (wix.api.maxLength) = 1000];
  }

  message Address {
    // contact details for the address
    wix.payment.api.pay.v2.upstream.wix.common.FullAddressContactDetails contact_details = 1;
    // address details
    wix.payment.api.pay.v2.upstream.wix.common.Address address = 2;
  }

  message BuyerInformation {
    // language used to display information to the buyer
    google.protobuf.StringValue buyer_language = 1 [(wix.api.format) = LANGUAGE];
    // buyer IP address, used for Fraud detection purposes
    google.protobuf.StringValue buyer_ip = 2[(.wix.api.pii) = true, (wix.api.maxLength) = 100];
    // identifier of the buyer
    google.protobuf.StringValue buyer_id = 3 [(wix.api.maxLength) = 100];
    // buyer billing information
    Address billing_info = 10;
    // buyer shipping information (if applicable)
    Address shipping_info = 11;
  }

  message PaymentClient {
    // application id of the payment client
    string app_id = 1 [(wix.api.maxLength) = 100]; // todo(charges) can we do format=GUID?
    // instance of the application of the payment client
    string instance_id = 2[(wix.api.maxLength) = 100]; // todo(charges) can we do format=GUID?
  }

  message Item {
    // Item ID.
    google.protobuf.StringValue id = 1 [(wix.api.format) = GUID];

    // Item name.
    google.protobuf.StringValue name = 2 [(wix.api.maxLength) = 200];

    // Item quantity.
    google.protobuf.Int32Value quantity = 3;

    // Item price.
    google.protobuf.StringValue price = 4 [(wix.api.decimalValue) = {gt: "0", maxScale: 8}];

    // Item description.
    google.protobuf.StringValue description = 5 [(wix.api.minLength) = 1, (wix.api.maxLength) = 1024];

    // Item weight in KG.
    google.protobuf.DoubleValue weight_in_kg = 6;

    // Is item a tangible product.
    google.protobuf.BoolValue tangible = 7;
  }

  message ReturnUrls {
    // todo(charges): what to do with non-web urls?
    // Url to redirect to on successful payment.
    google.protobuf.StringValue success_url = 1 [(wix.api.format) = WEB_URL];
    // Url to redirect to on payment error.
    google.protobuf.StringValue error_url = 2 [(wix.api.format) = WEB_URL];
    // Url to redirect to on pending payment.
    google.protobuf.StringValue pending_url = 3 [(wix.api.format) = WEB_URL];
  }
}

message ProviderChargeResponse {
  enum Status {
    UNKNOWN_STATUS = 0 [(wix.api.enum_maturity) = NOT_IMPLEMENTED];
    NEEDS_ACTION = 1;
    PENDING = 2;
    AUTHORIZED = 3;
    CAPTURED = 4;
    VOIDED = 5;
    FAILED = 6;
  }

  // Status of the payment after call to the provider
  Status status = 1;
  // information about status: reason, details etc
  StatusInfo status_info = 2;
  // information about payment method used for the charge
  PaymentMethodInfo payment_method_info = 3;
  // details for the recurring transaction
  ChargeRecurringDetails recurring = 4;
  // Action to perform if needed.
  NextAction next_action = 5 [(wix.api.readOnly) = true];

  message StatusInfo {
    // Reason code.
    // [Read more about reason codes.](https://dev.wix.com/docs/rest/api-reference/payment-provider-spi/reason-codes)
    google.protobuf.StringValue code = 1 [(wix.api.minLength) = 1, (wix.api.maxLength) = 10];

    // Free-text description.
    google.protobuf.StringValue description = 2 [(wix.api.minLength) = 1, (wix.api.maxLength) = 1000];

    // Raw provider status details describing current status of payment.
    repeated ProviderStatusDetail provider_status_details = 3 [(wix.api.maxSize) = 10];

    // Status of the charge as reported by the payment provider.
    google.protobuf.StringValue provider_status = 4 [(wix.api.minLength) = 1, (wix.api.maxLength) = 100];
  }

  message ProviderStatusDetail {
    // Provider-specific reason type that describes what this code is representing e.g. issuer_decline_code, card_error, request_error.
    google.protobuf.StringValue type = 1 [(wix.api.minLength) = 1, (wix.api.maxLength) = 100];

    // Reason code.
    google.protobuf.StringValue code = 2 [(wix.api.minLength) = 1, (wix.api.maxLength) = 100];

    // Free-text description.
    google.protobuf.StringValue description = 3 [(wix.api.minLength) = 1, (wix.api.maxLength) = 1000];
  }

  message ChargeRecurringDetails {
    // network reference for setup recurring
    ProviderChargeRequest.NetworkReference network_reference = 1;

    // Tokens that are used to reference a payment agreement in external payment provider.
    google.protobuf.StringValue provider_token = 2 [(wix.api.minLength) = 1, (wix.api.maxLength) = 2048];
  }

  message PaymentMethodInfo {
    // Id of payment method. As of now only 'credit_card' is supported
    string type_id = 1 [(wix.api.minLength) = 1, (wix.api.maxLength) = 50];

    // Details of the payment method
    oneof payment_method_details {
      // card payment method info
      CardPaymentInfo card = 2;
    }
  }

  message CardPaymentInfo {
    // card first digits
    google.protobuf.StringValue bin = 1 [(wix.api.minLength) = 3, (.wix.api.maxLength) = 8]; // todo(charges) check is these limits are good
    // cars last 4 digits
    google.protobuf.StringValue last4 = 2 [(.wix.api.exactLength) = 4]; // todo(charges) check is these limits are good
  }

  message NextAction {
    enum Type {
      UNKNOWN_TYPE = 0 [(.wix.api.enum_maturity) = NOT_IMPLEMENTED];
      GET_METHOD_REDIRECT = 1;
      POST_METHOD_REDIRECT = 2;
      BARCODE_DISPLAY = 3;
      CARD_READER_INTERACTION = 4;
      QR_CODE_DISPLAY = 5;
      WEB_PAGE_DISPLAY = 6;
    }

    // Type of the next action.
    Type type = 1;

    oneof action {
      // A browser should issue an HTTP GET request and render the result.
      GetMethodRedirect get_method_redirect = 2;

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

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

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

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

      // 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 = 7;

      // A browser should call a PayPal SDK.
      PayPalSdkInteraction pay_pal_sdk_interaction = 8;
    }
  }

  message GetMethodRedirect {
    // URL to perform an HTTP GET request to continue the payment flow.
    string url = 1 [(wix.api.format) = WEB_URL];
  }

  message PostMethodRedirect {
    message FormField {
      // Field name to include in the form request.
      string name = 1 [(wix.api.minLength) = 1, (wix.api.maxLength) = 100];

      // Field value to include in the form request.
      string value = 2 [(wix.api.maxLength) = 1000];
    }

    // URL to perform an HTTP POST request to continue the payment flow.
    string url = 1 [(wix.api.format) = WEB_URL];

    // Form fields to be included in the POST request body.
    repeated FormField fields = 2 [(.wix.api.maxSize) = 100];
  }

  message BarcodeDisplay {
    // Barcode value in decimal digits for in-person payment.
    google.protobuf.StringValue barcode = 1 [(wix.api.minLength) = 1, (wix.api.maxLength) = 1000];

    // URL to view or download the barcode document.
    google.protobuf.StringValue barcode_url = 2 [(wix.api.format) = WEB_URL];

    // Date and time when the barcode expires.
    google.protobuf.Timestamp expiration_date = 3;

    // Email address to send billing information to.
    google.protobuf.StringValue billing_email = 4 [(wix.api.format) = EMAIL, (.wix.api.pii) = true];
  }

  message QrCodeDisplay {
    // QR code raw text payload to be converted to an image.
    google.protobuf.StringValue payload = 1 [(wix.api.minLength) = 1, (wix.api.maxLength) = 1000];

    // Date and time when the QR code expires.
    google.protobuf.Timestamp expiration_date = 2;
  }

  message WebPageDisplay {
    // URL to the webpage that should be displayed in an iframe.
    google.protobuf.StringValue url = 1 [(wix.api.format) = WEB_URL];

    // Date and time when the page expires.
    google.protobuf.Timestamp expiration_date = 2;
  }

  message CardReaderInteraction {
    // Token used for interaction with the card reader device.
    google.protobuf.StringValue reader_token = 1 [(wix.api.maxLength) = 1000];
  }

  message PayPalSdkInteraction {
    // PayPal order ID for SDK integration.
    google.protobuf.StringValue pay_pal_order_id = 1 [(wix.api.maxLength) = 100];
    // todo: access token
  }
}
