// Copyright (c) Juspay Technologies. All rights reserved.
//
// Package: ucs.v2
// File: payment.proto
//
// Overview:
//   This file defines the core data types, enumerations, and request/response
//   messages used across the Unified Connector Service (UCS) v2 API.
//
//   It is imported by services.proto, which defines the gRPC service interfaces
//   (PaymentService, RefundService, DisputeService). Consumers of the API
//   should treat services.proto as the entry point and this file as the
//   shared type library.
//
// Key Concepts:
//   - Money:         All monetary amounts are represented in minor currency
//   units
//                   (e.g., 1000 = $10.00 USD). See the Money message.
//   - SecretString:  A wrapper type (defined in payment_methods.proto) used for
//                   fields that contain sensitive data such as card numbers,
//                   CVVs, email addresses, and tokens. These values are masked
//                   in logs and traces. Treat them as you would any PII or
//                   credential.
//   - Identifier:   A oneof used to represent a connector transaction ID. Use
//                   the `id` variant for a plain string ID, `encoded_data` for
//                   an opaque/encoded reference, and `no_response_id_marker`
//                   when the connector returns no ID at all (e.g., async
//                   flows).
//   - ConnectorState: Carries session-scoped data (e.g., access tokens) that
//                   must be round-tripped by the caller between requests in a
//                   multi-step flow.
//
// Versioning:
//   Field numbers are stable and must never be reused once reserved or deleted.
//   Any removed field must be listed in a `reserved` statement. Enum zero
//   values follow the convention `ENUM_NAME_UNSPECIFIED = 0` to distinguish an
//   unset field from a meaningful value.
//
// Related Files:
//   - services.proto      — gRPC service definitions
//   - payment_methods.proto — Payment method data types and SecretString

syntax = "proto3";

package types;

import "google/protobuf/empty.proto";
import "payment_methods.proto";

option go_package = "github.com/juspay/connector-service/crates/types-traits/grpc-api-types/proto;proto";

// ============================================================================
// CORE DATA TYPES
// ============================================================================

// Money represents a monetary amount with currency
// All amounts are in minor units (e.g., cents for USD)
message Money {
  int64 minor_amount = 1; // Amount in minor units (e.g., 1000 = $10.00)
  Currency currency = 2; // ISO 4217 currency code (e.g., "USD", "EUR")
}

// Quote details associated with a currency conversion decision.
message CurrencyConversionQuote {
  // Order amount for the transaction, expressed in the merchant's currency.
  Money merchant_order_amount = 1;

  // Decimal exchange rate for this currency conversion quote.
  // It converts merchant_order_amount.currency to PaymentServiceAuthorizeRequest.amount.currency.
  // For an accepted DCC offer, PaymentServiceAuthorizeRequest.amount is the payable amount in the cardholder currency.
  optional string exchange_rate = 2;

  // Quote identifier assigned by the connector or rate provider.
  optional string connector_quote_id = 3;

  // Exchange-rate identifier required to reference the quoted rate.
  optional string exchange_rate_id = 4;

  // Name of the CC provider that supplied the quote.
  optional string provider = 5;

  // Source used by the provider to determine the exchange rate.
  optional string rate_source = 6;

  // Percentage markup included in the exchange rate, represented exactly as
  // supplied by the provider (for example, "3.50").
  optional string markup_percentage = 7;

  // Monetary amount of the markup included in the quote.
  optional Money markup_amount = 8;

  // Type of currency conversion: DCC, MCP, or MCC.
  optional CurrencyConversionType currency_conversion_type = 9;

  // Time when the quote was created, in Unix epoch seconds.
  optional int64 quoted_at = 10;

  // Time when the quote expires, in Unix epoch seconds.
  optional int64 expires_at = 11;
}

// Identifies the currency conversion model used for the payment.
enum CurrencyConversionType {
  // Currency conversion type was not provided or could not be determined.
  CURRENCY_CONVERSION_TYPE_UNSPECIFIED = 0;
  // Dynamic Currency Conversion (DCC).
  CURRENCY_CONVERSION_TYPE_DCC = 1;
  // Multi-Currency Pricing (MCP).
  CURRENCY_CONVERSION_TYPE_MCP = 2;
  // Merchant Currency Conversion (MCC).
  CURRENCY_CONVERSION_TYPE_MCC = 3;
}

// Indicates the customer's decision for a currency conversion offer.
enum CurrencyConversionDecision {
  // Currency conversion decision was not provided or could not be determined.
  CURRENCY_CONVERSION_DECISION_UNSPECIFIED = 0;
  // The customer accepted the currency conversion offer.
  CURRENCY_CONVERSION_DECISION_ACCEPTED = 1;
  // The customer declined the currency conversion offer.
  CURRENCY_CONVERSION_DECISION_DECLINED = 2;
  // Currency conversion does not apply to this payment.
  CURRENCY_CONVERSION_DECISION_NOT_APPLICABLE = 3;
}

// Contains the customer's currency conversion decision and the quote presented to them.
message CurrencyConversionData {
  // Customer's decision for the currency conversion offer.
  CurrencyConversionDecision decision = 1;
  // Currency conversion quote presented to the customer, when available.
  optional CurrencyConversionQuote quote = 2;
}

// Permissions wraps a repeated string field to allow optional presence
// Used for fields like permissions where absence is semantically different from empty
message Permissions {
  repeated string values = 1;
}

// ErrorInfo provides structured error information for API responses
message ErrorInfo {
  optional UnifiedErrorDetails unified_details =
      1; // Machine-readable error code
  optional IssuerErrorDetails issuer_details =
      2; // Human-readable error message
  optional ConnectorErrorDetails connector_details = 3; // Detailed explanation
}

message UnifiedErrorDetails {
  optional string code = 1;        // Machine-readable error code
  optional string message = 2;     // Human-readable error message
  optional string description = 3; // Detailed explanation
  optional string user_guidance_message =
      4; // User-facing message with guidance on next steps
}

// IssuerErrorDetails provides structured error information specific to card
// issuer responses
message IssuerErrorDetails {
  optional string code = 1;    // card scheme Eg: VISA, MASTERCARD etc.
  optional string message = 2; // Human-readable error message
  optional NetworkErrorDetails network_details =
      3; // Network-specific error details, if applicable
}

message NetworkErrorDetails {
  optional string advice_code = 1;   // Network advice code for retry logic
  optional string decline_code = 2;  // Card scheme decline code
  optional string error_message = 3; // Network-specific error details
}

message ConnectorErrorDetails {
  optional string code = 1;    // Connector-specific error code
  optional string message = 2; // Human-readable error message
  optional string reason = 3;  // Detailed explanation
  optional string connector_transaction_id = 4; // Connector's unique transaction ID for debugging and support reference
  
  // Attempt status from the connector flow (Payment/Refund/Dispute).
  // Extracted from ErrorResponse.attempt_status (domain_types::FlowStatus).
  // Only one of payment_status, refund_status, or dispute_status will be set.
  optional FlowStatus status = 5;
}

// The connector's reported status for this response: the code, message and
// reason returned by the connector, when provided.
message RawConnectorStatus {
  optional string code = 1;    // Connector status/response code, e.g. "05"
  optional string message = 2; // Status message, e.g. "Do not honor"
  optional string reason = 3;  // Additional detail, when present
}

// Metadata consolidates all metadata types
message Metadata {
  SecretString general = 1; // General metadata
}

// Represents an identifier, which can be one of several types.
message Identifier {
  oneof id_type {
    // Connector's transaction ID.
    string id = 1;

    // Encoded data representing the ID or related information.
    string encoded_data = 2;

    // Indicates that no specific ID is returned or applicable.
    google.protobuf.Empty no_response_id_marker = 3;
  }
}

message Customer {
  optional string name = 1;        // Customer's full name
  optional SecretString email = 2; // Customer's email address
  optional string id = 3;          // Internal customer ID
  optional string connector_customer_id =
      4;                                  // Customer ID in the connector system
  optional SecretString phone_number = 5; // Customer's phone number
  optional string phone_country_code = 6; // Customer's phone country code
  optional string first_name = 7;       // Customer's first name
  optional string last_name = 8;        // Customer's last name
  optional string salutation = 9;       // Customer's salutation (Mr., Ms., etc.)
  optional CustomerDocumentDetails customer_document_details =
      10; // Customer identification document
}

// Type of customer identification document.
enum DocumentKind {
  DOCUMENT_KIND_UNSPECIFIED = 0; // Default, unspecified document type.
  CPF = 1; // Cadastro de Pessoas Físicas - Brazilian individual taxpayer ID.
  CNPJ = 2; // Cadastro Nacional da Pessoa Jurídica - Brazilian business ID.
  PSN = 3; // Philippine PhilSys Number (12-digit national ID), required by dLocal for GCash.
  OTHER = 4; // Generic / other non-Brazilian national document; the connector validates it per country. Kept last as the catch-all.
}

// Customer's country-specific identification document.
message CustomerDocumentDetails {
  DocumentKind document_type = 1;   // The customer's document type
  SecretString document_number = 2; // The customer's document number
}

// ============================================================================
// COMMON MESSAGES
// ============================================================================

// HTTP methods
enum HttpMethod {
  HTTP_METHOD_UNSPECIFIED = 0; // Default, unspecified HTTP method.
  HTTP_METHOD_GET = 1;         // HTTP GET method.
  HTTP_METHOD_POST = 2;        // HTTP POST method.
  HTTP_METHOD_PUT = 3;         // HTTP PUT method.
  HTTP_METHOD_DELETE = 4;      // HTTP DELETE method.
}

// Status of a payment attempt
enum PaymentStatus {
  PAYMENT_STATUS_UNSPECIFIED = 0; // Default value

  // Initial states
  STARTED = 1;
  PAYMENT_METHOD_AWAITED = 22; // Waiting for customer to provide payment method
  DEVICE_DATA_COLLECTION_PENDING = 24; // Waiting for device data collection
  CONFIRMATION_AWAITED = 23;           // Waiting for customer confirmation

  // Authentication flow
  AUTHENTICATION_PENDING = 4;
  AUTHENTICATION_SUCCESSFUL = 5;
  AUTHENTICATION_FAILED = 2;

  // Authorization flow
  AUTHORIZING = 9;
  AUTHORIZED = 6;
  AUTHORIZATION_FAILED = 7;
  PARTIALLY_AUTHORIZED = 25;

  // Charging flow
  CHARGED = 8;
  PARTIAL_CHARGED = 17;
  PARTIAL_CHARGED_AND_CHARGEABLE =
      18; // Partially charged, remaining amount can be captured
  AUTO_REFUNDED = 16;

  // Capture flow
  CAPTURE_INITIATED = 13;
  CAPTURE_FAILED = 14;

  // Void flow
  VOID_INITIATED = 12;
  VOIDED = 11;
  VOID_FAILED = 15;
  VOIDED_POST_CAPTURE = 57;

  // Other payment flows
  COD_INITIATED = 10; // Cash on Delivery initiated
  EXPIRED = 26;       // Payment expired before it could be captured

  // Terminal/fallback states
  ROUTER_DECLINED = 3;
  PENDING = 20;    // General pending state
  FAILURE = 21;    // General failure state
  UNRESOLVED = 19; // Status could not be determined
}

// Status of a payment authorization
enum AuthorizationStatus {
  AUTHORIZATION_STATUS_UNSPECIFIED = 0; // Default value
  AUTHORIZATION_SUCCESS = 1;
  AUTHORIZATION_FAILURE = 2;
  AUTHORIZATION_PROCESSING = 3;
  AUTHORIZATION_UNRESOLVED = 4;
}

// Status of generic operations (non-payment specific).
enum OperationStatus {
  OPERATION_STATUS_UNSPECIFIED = 0; // Default value
  OPERATION_STATUS_SUCCESS = 1;     // Operation completed successfully
  OPERATION_STATUS_FAILURE = 2;     // Operation failed
  OPERATION_STATUS_PENDING = 3;     // Operation is in progress
  OPERATION_STATUS_AUTHENTICATION_FAILED =
      4;                                // Authentication/authorization failed
  OPERATION_STATUS_RATE_LIMITED = 5;    // Rate limit exceeded
  OPERATION_STATUS_INVALID_REQUEST = 6; // Invalid request parameters
}

// Status of a refund
enum RefundStatus {
  REFUND_STATUS_UNSPECIFIED = 0; // Default value
  REFUND_FAILURE = 1;
  REFUND_MANUAL_REVIEW = 2; // Refund requires manual review
  REFUND_PENDING = 3;
  REFUND_SUCCESS = 4;
  REFUND_TRANSACTION_FAILURE =
      5; // Failure at the transaction level for the refund
}

// Status of a dispute
enum DisputeStatus {
  DISPUTE_STATUS_UNSPECIFIED = 0; // Default value
  DISPUTE_OPENED = 1;
  DISPUTE_EXPIRED = 2;
  DISPUTE_ACCEPTED = 3;
  DISPUTE_CANCELLED = 4;
  DISPUTE_CHALLENGED = 5; // Dispute is being challenged with evidence
  DISPUTE_WON = 6;
  DISPUTE_LOST = 7;
}

// Unified flow status wrapping payment, refund, or dispute status.
// Used to represent the attempt status in error responses and flow results.
// Only one variant should be set at a time.
message FlowStatus {
  oneof status {
    PaymentStatus payment_status = 1;  // Status for payment flow
    RefundStatus refund_status = 2;    // Status for refund flow
    DisputeStatus dispute_status = 3;  // Status for dispute flow
  }
}

// Status of a mandate
enum MandateStatus {
  MANDATE_STATUS_UNSPECIFIED = 0; // Default value
  MANDATE_PENDING = 1;
  ACTIVE = 2;
  MANDATE_INACTIVE = 3;
  REVOKED = 4;
  MANDATE_REVOKE_FAILED = 5;
}

// Method for capturing a payment
enum CaptureMethod {
  CAPTURE_METHOD_UNSPECIFIED = 0; // Default value
  AUTOMATIC = 1;       // Capture is done automatically after authorization.
  MANUAL = 2;          // Capture must be triggered manually.
  MANUAL_MULTIPLE = 3; // Multiple manual captures are possible.
  SCHEDULED = 4;       // Capture is scheduled for a later time.
  SEQUENTIAL_AUTOMATIC = 5; // Sequential automatic captures.
}

// Indicates how a payment method might be used in the future
enum FutureUsage {
  FUTURE_USAGE_UNSPECIFIED = 0; // Default value
  OFF_SESSION = 1; // For merchant-initiated transactions (e.g., subscriptions).
  ON_SESSION = 2;  // For customer-initiated transactions.
}

// Indicates the category of MIT
enum MitCategory {
  MIT_CATEGORY_UNSPECIFIED = 0; // Default value
  // A fixed purchase amount split into multiple scheduled payments until the
  // total is paid.
  INSTALLMENT_MIT = 1;
  // Merchant-initiated transaction using stored credentials, but not tied to a
  // fixed schedule
  UNSCHEDULED_MIT = 2;
  // Merchant-initiated payments that happen at regular intervals (usually the
  // same amount each time).
  RECURRING_MIT = 3;
  // A retried MIT after a previous transaction failed or was declined.
  RESUBMISSION_MIT = 4;
}

// Indicates the type of payment sync request
enum SyncRequestType {
  SYNC_REQUEST_TYPE_UNSPECIFIED = 0; // Default value
  SINGLE_PAYMENT_SYNC = 1;
  MULTIPLE_CAPTURE_SYNC = 2;
}

// Type of acceptance
enum AcceptanceType {
  ACCEPTANCE_TYPE_UNSPECIFIED = 0; // Default value
  ONLINE = 1;                      // Acceptance was given online.
  OFFLINE = 2;                     // Acceptance was given offline.
}

// Type of authentication used for a payment
enum AuthenticationType {
  AUTHENTICATION_TYPE_UNSPECIFIED = 0; // Default value
  THREE_DS = 1;                        // 3D Secure authentication.
  NO_THREE_DS = 2; // No 3D Secure, or 3DS explicitly bypassed.
}

// Indicates if 3DS method data was successfully completed
enum ThreeDsCompletionIndicator {
  THREE_DS_COMPLETION_INDICATOR_UNSPECIFIED = 0; // Default value
  THREE_DS_COMPLETION_INDICATOR_SUCCESS =
      1; // 3DS method successfully completed ("Y")
  THREE_DS_COMPLETION_INDICATOR_FAILURE =
      2; // 3DS method was not successful ("N")
  THREE_DS_COMPLETION_INDICATOR_NOT_AVAILABLE =
      3; // 3DS method URL was unavailable ("U")
}

// Transaction status from authentication/verification process
enum TransactionStatus {
  TRANSACTION_STATUS_UNSPECIFIED = 0; // Default value
  // Authentication/Account Verification Successful
  TRANSACTION_STATUS_SUCCESS = 1; // "Y"

  // Not Authenticated/Account Not Verified; Transaction denied
  TRANSACTION_STATUS_FAILURE = 2; // "N"

  // Authentication/Account Verification Could Not Be Performed; Technical or
  // other problem
  TRANSACTION_STATUS_VERIFICATION_NOT_PERFORMED = 3; // "U"

  // Attempts Processing Performed; Not Authenticated/Verified, but proof of
  // attempted authentication/verification is provided
  TRANSACTION_STATUS_NOT_VERIFIED = 4; // "A"

  // Authentication/Account Verification Rejected; Issuer is rejecting
  // authentication/verification
  TRANSACTION_STATUS_REJECTED = 5; // "R"

  // Challenge Required; Additional authentication is required using the
  // Challenge Request (CReq) / Challenge Response (CRes)
  TRANSACTION_STATUS_CHALLENGE_REQUIRED = 6; // "C"
  // Challenge Required; Decoupled Authentication confirmed
  TRANSACTION_STATUS_CHALLENGE_REQUIRED_DECOUPLED_AUTHENTICATION = 7; // "D"

  // Informational Only; 3DS Requestor challenge preference acknowledged
  TRANSACTION_STATUS_INFORMATION_ONLY = 8; // "I"
}

// SCA (Strong Customer Authentication) exemption indicators.
enum ExemptionIndicator {
  // Unspecified/default value.
  EXEMPTION_INDICATOR_UNSPECIFIED = 0;

  // Low-value payment exemption (below regulatory threshold).
  EXEMPTION_INDICATOR_LOW_VALUE = 1;

  // Secure corporate payment (SCP) exemption.
  EXEMPTION_INDICATOR_SECURE_CORPORATE_PAYMENT = 2;

  // Trusted beneficiary or whitelist exemption.
  EXEMPTION_INDICATOR_TRUSTED_LISTING = 3;

  // Transaction Risk Analysis (TRA) exemption.
  EXEMPTION_INDICATOR_TRANSACTION_RISK_ASSESSMENT = 4;

  // 3DS server or ACS outage exemption.
  EXEMPTION_INDICATOR_THREE_DS_OUTAGE = 5;

  // SCA delegation exemption (authentication delegated to another party).
  EXEMPTION_INDICATOR_SCA_DELEGATION = 6;

  // Out of SCA scope (e.g., one-leg-out transactions).
  EXEMPTION_INDICATOR_OUT_OF_SCA_SCOPE = 7;

  // Other exemption reason not covered by known types.
  EXEMPTION_INDICATOR_OTHER = 8;

  // Low-risk program exemption (network-initiated low-risk flag).
  EXEMPTION_INDICATOR_LOW_RISK_PROGRAM = 9;

  // Recurring transaction exemption (subsequent payment in a series).
  EXEMPTION_INDICATOR_RECURRING_OPERATION = 10;
}

// Preferred payment experience for the customer
enum PaymentExperience {
  PAYMENT_EXPERIENCE_UNSPECIFIED = 0; // Default value
  REDIRECT_TO_URL = 1;                // Redirect customer to a URL.
  INVOKE_SDK_CLIENT = 2;              // Invoke a client-side SDK.
  DISPLAY_QR_CODE = 3;                // Display a QR code.
  ONE_CLICK = 4;                      // One-click payment experience.
  LINK_WALLET = 5;                    // Link a digital wallet.
  INVOKE_PAYMENT_APP = 6;             // Invoke a payment application.
  DISPLAY_WAIT_SCREEN = 7;            // Display a waiting screen.
  COLLECT_OTP = 8;                    // Collect an OTP from the customer.
}

// Channel through which the payment was initiated
enum PaymentChannel {
  PAYMENT_CHANNEL_UNSPECIFIED = 0; // Default value
  ECOMMERCE = 1;
  MAIL_ORDER = 2;
  TELEPHONE_ORDER = 3;
}

// Type of event that a webhook can represent
enum WebhookEventType {
  WEBHOOK_EVENT_TYPE_UNSPECIFIED = 0; // Default unspecified event

  // Payment intent events
  PAYMENT_INTENT_FAILURE = 1;          // Authorization + Capture failure
  PAYMENT_INTENT_SUCCESS = 2;          // Authorization + Capture success
  PAYMENT_INTENT_PROCESSING = 3;       // Payment intent is processing
  PAYMENT_INTENT_PARTIALLY_FUNDED = 4; // Payment intent is partially funded
  PAYMENT_INTENT_CANCELLED = 5;        // Payment intent cancelled
  PAYMENT_INTENT_CANCEL_FAILURE = 6;   // Payment intent cancel failure
  PAYMENT_INTENT_AUTHORIZATION_SUCCESS = 7; // Authorization success
  PAYMENT_INTENT_AUTHORIZATION_FAILURE = 8; // Authorization failure
  PAYMENT_INTENT_CAPTURE_SUCCESS = 9;       // Capture success
  PAYMENT_INTENT_CAPTURE_FAILURE = 10;      // Capture failure
  PAYMENT_INTENT_EXPIRED = 11;              // Payment intent expired
  PAYMENT_ACTION_REQUIRED = 12; // Payment requires additional action

  SOURCE_CHARGEABLE = 13;          // Source is chargeable
  SOURCE_TRANSACTION_CREATED = 14; // Source transaction created

  // Refund events
  WEBHOOK_REFUND_FAILURE = 15; // Refund failure
  WEBHOOK_REFUND_SUCCESS = 16; // Refund success
  WEBHOOK_REFUND_PROCESSING = 42; // Refund processing

  // Dispute events
  WEBHOOK_DISPUTE_OPENED = 17;     // Dispute opened
  WEBHOOK_DISPUTE_EXPIRED = 18;    // Dispute expired
  WEBHOOK_DISPUTE_ACCEPTED = 19;   // Dispute accepted
  WEBHOOK_DISPUTE_CANCELLED = 20;  // Dispute cancelled
  WEBHOOK_DISPUTE_CHALLENGED = 21; // Dispute challenged
  WEBHOOK_DISPUTE_WON = 22;  // Dispute successfully challenged by merchant
  WEBHOOK_DISPUTE_LOST = 23; // Dispute unsuccessfully challenged

  // Mandate events
  MANDATE_ACTIVE = 24;  // Mandate is active
  MANDATE_FAILED = 41;  // Mandate failed
  MANDATE_REVOKED = 25; // Mandate revoked

  // Misc events
  ENDPOINT_VERIFICATION = 26;        // Endpoint verification
  EXTERNAL_AUTHENTICATION_ARES = 27; // External authentication ARes
  FRM_APPROVED = 28;                 // Fraud risk management approved
  FRM_REJECTED = 29;                 // Fraud risk management rejected

  // Payout events
  PAYOUT_SUCCESS = 30;    // Payout success
  PAYOUT_FAILURE = 31;    // Payout failure
  PAYOUT_PROCESSING = 32; // Payout processing
  PAYOUT_CANCELLED = 33;  // Payout cancelled
  PAYOUT_CREATED = 34;    // Payout created
  PAYOUT_EXPIRED = 35;    // Payout expired
  PAYOUT_REVERSED = 36;   // Payout reversed

  // Recovery events
  RECOVERY_PAYMENT_FAILURE = 37; // Recovery payment failure
  RECOVERY_PAYMENT_SUCCESS = 38; // Recovery payment success
  RECOVERY_PAYMENT_PENDING = 39; // Recovery payment pending
  RECOVERY_INVOICE_CANCEL = 40;  // Recovery invoice cancelled
}

// Type of event for outgoing connector notifications (not webhooks)
enum NotifyEventType {
  NOTIFY_EVENT_TYPE_UNSPECIFIED = 0; // Default unspecified event

  // Surcharge events
  SURCHARGE_PAYMENT_SUCCEEDED = 1; // Surcharge payment succeeded
  SURCHARGE_REFUND_SUCCEEDED = 2;  // Surcharge refund succeeded

  // FRM events
  FRM_PAYMENT_SUCCEEDED = 6;     // Payment authorized/captured — update FRM with outcome
  FRM_PAYMENT_FAILURE = 7;       // Payment authorized/captured — update FRM with outcome
  FRM_REFUND_PROCESSED = 8;      // Refund completed — notify FRM of return
  FRM_CHARGEBACK_RECEIVED = 9;   // Chargeback opened — notify FRM of reversal
}

// Currency codes (ISO 4217)
// Note: Using enum for type safety. Consider string for flexibility.
enum Currency {
  CURRENCY_UNSPECIFIED = 0;
  AED = 1;
  AFN = 2;
  ALL = 3;
  AMD = 4;
  ANG = 5;
  AOA = 6;
  ARS = 7;
  AUD = 8;
  AWG = 9;
  AZN = 10;
  BAM = 11;
  BBD = 12;
  BDT = 13;
  BGN = 14;
  BHD = 15;
  BIF = 16;
  BMD = 17;
  BND = 18;
  BOB = 19;
  BRL = 20;
  BSD = 21;
  BTN = 22;
  BWP = 23;
  BYN = 24;
  BZD = 25;
  CAD = 26;
  CDF = 27;
  CHF = 28;
  CLF = 29;
  CLP = 30;
  CNY = 31;
  COP = 32;
  CRC = 33;
  CUC = 34;
  CUP = 35;
  CVE = 36;
  CZK = 37;
  DJF = 38;
  DKK = 39;
  DOP = 40;
  DZD = 41;
  EGP = 42;
  ERN = 43;
  ETB = 44;
  EUR = 45;
  FJD = 46;
  FKP = 47;
  GBP = 48;
  GEL = 49;
  GHS = 50;
  GIP = 51;
  GMD = 52;
  GNF = 53;
  GTQ = 54;
  GYD = 55;
  HKD = 56;
  HNL = 57;
  HRK = 58;
  HTG = 59;
  HUF = 60;
  IDR = 61;
  ILS = 62;
  INR = 63;
  IQD = 64;
  IRR = 65;
  ISK = 66;
  JMD = 67;
  JOD = 68;
  JPY = 69;
  KES = 70;
  KGS = 71;
  KHR = 72;
  KMF = 73;
  KPW = 74;
  KRW = 75;
  KWD = 76;
  KYD = 77;
  KZT = 78;
  LAK = 79;
  LBP = 80;
  LKR = 81;
  LRD = 82;
  LSL = 83;
  LYD = 84;
  MAD = 85;
  MDL = 86;
  MGA = 87;
  MKD = 88;
  MMK = 89;
  MNT = 90;
  MOP = 91;
  MRU = 92;
  MUR = 93;
  MVR = 94;
  MWK = 95;
  MXN = 96;
  MYR = 97;
  MZN = 98;
  NAD = 99;
  NGN = 100;
  NIO = 101;
  NOK = 102;
  NPR = 103;
  NZD = 104;
  OMR = 105;
  PAB = 106;
  PEN = 107;
  PGK = 108;
  PHP = 109;
  PKR = 110;
  PLN = 111;
  PYG = 112;
  QAR = 113;
  RON = 114;
  RSD = 115;
  RUB = 116;
  RWF = 117;
  SAR = 118;
  SBD = 119;
  SCR = 120;
  SDG = 121;
  SEK = 122;
  SGD = 123;
  SHP = 124;
  SLE = 125;
  SLL = 126;
  SOS = 127;
  SRD = 128;
  SSP = 129;
  STD = 130;
  STN = 131;
  SVC = 132;
  SYP = 133;
  SZL = 134;
  THB = 135;
  TJS = 136;
  TMT = 137;
  TND = 138;
  TOP = 139;
  TRY = 140;
  TTD = 141;
  TWD = 142;
  TZS = 143;
  UAH = 144;
  UGX = 145;
  USD = 146;
  UYU = 147;
  UZS = 148;
  VES = 149;
  VND = 150;
  VUV = 151;
  WST = 152;
  XAF = 153;
  XCD = 154;
  XOF = 155;
  XPF = 156;
  YER = 157;
  ZAR = 158;
  ZMW = 159;
  ZWL = 160;
}

// Connector enumeration
enum Connector {
  CONNECTOR_UNSPECIFIED = 0; // Default value
  ADYENPLATFORM = 1;
  ACI = 2;
  ADYEN = 3;
  AIRWALLEX = 4;
  AUTHORIZEDOTNET = 5;
  BAMBORA = 6;
  BAMBORAAPAC = 7;
  BANKOFAMERICA = 8;
  BILLWERK = 9;
  BITPAY = 10;
  BLUESNAP = 11;
  BOKU = 12;
  BRAINTREE = 13;
  CASHTOCODE = 14;
  CHARGEBEE = 15;
  CHECKOUT = 16;
  COINBASE = 17;
  COINGATE = 18;
  CRYPTOPAY = 19;
  CTP_MASTERCARD = 20;
  CTP_VISA = 21;
  CYBERSOURCE = 22;
  DATATRANS = 23;
  DEUTSCHEBANK = 24;
  DIGITALVIRGO = 25;
  DLOCAL = 26;
  EBANX = 27;
  ELAVON = 28;
  FISERV = 29;
  FISERVEMEA = 30;
  FIUU = 31;
  FORTE = 32;
  GETNET = 33;
  GLOBALPAY = 34;
  GLOBEPAY = 35;
  GOCARDLESS = 36;
  GPAYMENTS = 37;
  HIPAY = 38;
  HELCIM = 39;
  INESPAY = 40;
  IATAPAY = 41;
  ITAUBANK = 42;
  JPMORGAN = 43;
  JUSPAYTHREEDSSERVER = 44;
  KLARNA = 45;
  MIFINITY = 46;
  MOLLIE = 47;
  MONERIS = 48;
  MULTISAFEPAY = 49;
  NETCETERA = 50;
  NEXINETS = 51;
  NEXIXPAY = 52;
  NMI = 53;
  NOMUPAY = 54;
  NOON = 55;
  NOVALNET = 56;
  NUVEI = 57;
  OPENNODE = 58;
  PAYBOX = 59;
  PAYME = 60;
  PAYONE = 61;
  PAYPAL = 62;
  PAYSTACK = 63;
  PAYU = 64;
  PLACETOPAY = 65;
  POWERTRANZ = 66;
  PROPHETPAY = 67;
  RAPYD = 68;
  RAZORPAY = 69;
  RECURLY = 70;
  REDSYS = 71;
  SHIFT4 = 72;
  SQUARE = 73;
  STAX = 74;
  STRIPE = 75;
  TAXJAR = 76;
  THREEDSECUREIO = 77;
  TRUSTPAY = 78;
  TSYS = 79;
  VOLT = 80;
  WELLSFARGO = 81;
  WISE = 82;
  WORLDLINE = 83;
  WORLDPAY = 84;
  WORLDPAYVANTIV = 85;
  SIGNIFYD = 86;
  PLAID = 87;
  RISKIFIED = 88;
  XENDIT = 89;
  ZEN = 90;
  ZSL = 91;
  PHONEPE = 92;
  CASHFREE = 93;
  PAYTM = 94;
  CALIDA = 95;
  PAYLOAD = 96;
  AUTHIPAY = 97;
  SILVERFLOW = 98;
  CELERO = 99;
  TRUSTPAYMENTS = 100;
  PAYSAFE = 101;
  BARCLAYCARD = 102;
  WORLDPAYXML = 103;
  REVOLUT = 104;
  LOONIO = 105;
  GIGADAT = 106;
  HYPERPG = 107;
  ZIFT = 108;
  REVOLV3 = 109;
  TRUELAYER = 110;
  FINIX = 111;
  PEACHPAYMENTS = 112;
  PPRO = 113;
  FISERVCOMMERCEHUB = 114;
  TRUSTLY = 115;
  ABSA_SANLAM = 116;
  PINELABS_ONLINE = 117;
  IMERCHANTSOLUTIONS = 118;
  AXISBANK = 119;
  EASEBUZZ = 120;
  TWOC_TWOP_PACO = 121;
  JUSPAY = 122;
  TAMARA = 123;
  PAYCONEX = 124;
  QWIKCILVER = 125;
  HYPERSWITCH = 126;
  TSYS_TRANSIT = 127;
  KOUNT = 128;
  FLYWIRE = 129;
  GLOMOPAY = 130;
  GIVEPAYMENTS = 131;
  TESOURO = 132;
  SANTANDER = 133;
  MAYA = 134;
}

// Payment method types
enum PaymentMethodType {
  PAYMENT_METHOD_TYPE_UNSPECIFIED = 0; // Default value
  ACH = 1;
  AFFIRM = 2;
  AFTERPAY_CLEARPAY = 3;
  ALFAMART = 4;
  ALI_PAY = 5;
  ALI_PAY_HK = 6;
  ALMA = 7;
  AMAZON_PAY = 8;
  APPLE_PAY = 9;
  ATOME = 10;
  BACS = 11;
  BANCONTACT_CARD = 12;
  BECS = 13;
  BENEFIT = 14;
  BIZUM = 15;
  BLIK = 16;
  BOLETO = 17;
  BCA_BANK_TRANSFER = 18;
  BNI_VA = 19;
  BRI_VA = 20;
  CARD_REDIRECT = 21;
  CIMB_VA = 22;
  CLASSIC_REWARD = 23;
  CREDIT = 24;
  CRYPTO_CURRENCY = 25;
  CASHAPP = 26;
  DANA = 27;
  DANAMON_VA = 28;
  DEBIT = 29;
  DUIT_NOW = 30;
  EFECTY = 31;
  EFT = 32;
  EPS = 33;
  FPS = 34;
  EVOUCHER = 35;
  GIROPAY = 36;
  GIVEX = 37;
  GOOGLE_PAY = 38;
  GO_PAY = 39;
  GCASH = 40;
  IDEAL = 41;
  INTERAC = 42;
  INDOMARET = 43;
  KAKAO_PAY = 44;
  LOCAL_BANK_REDIRECT = 45;
  MANDIRI_VA = 46;
  KNET = 47;
  MB_WAY = 48;
  MOBILE_PAY = 49;
  MOMO = 50;
  MOMO_ATM = 51;
  MULTIBANCO = 52;
  ONLINE_BANKING_THAILAND = 53;
  ONLINE_BANKING_CZECH_REPUBLIC = 54;
  ONLINE_BANKING_FINLAND = 55;
  ONLINE_BANKING_FPX = 56;
  ONLINE_BANKING_POLAND = 57;
  ONLINE_BANKING_SLOVAKIA = 58;
  OXXO = 59;
  PAGO_EFECTIVO = 60;
  PERMATA_BANK_TRANSFER = 61;
  OPEN_BANKING_UK = 62;
  PAY_BRIGHT = 63;
  PAZE = 64;
  PIX = 65;
  PAY_SAFE_CARD = 66;
  PRZELEWY24 = 67;
  PROMPT_PAY = 68;
  PSE = 69;
  RED_COMPRA = 70;
  RED_PAGOS = 71;
  SAMSUNG_PAY = 72;
  SEPA = 73;
  SEPA_BANK_TRANSFER = 74;
  SOFORT = 75;
  SWISH = 76;
  TOUCH_N_GO = 77;
  TRUSTLY_BANK_REDIRECT = 78;
  TWINT = 79;
  UPI_COLLECT = 80;
  UPI_INTENT = 81;
  UPI_QR = 82;
  VIPPS = 83;
  VIET_QR = 84;
  VENMO = 85;
  WALLEY = 86;
  WE_CHAT_PAY = 87;
  SEVEN_ELEVEN = 88;
  LAWSON = 89;
  MINI_STOP = 90;
  FAMILY_MART = 91;
  SEICOMART = 92;
  PAY_EASY = 93;
  LOCAL_BANK_TRANSFER = 94;
  OPEN_BANKING_PIS = 95;
  DIRECT_CARRIER_BILLING = 96;
  INSTANT_BANK_TRANSFER = 97;
  PAY_PAL = 98;
  REVOLUT_PAY = 99;
  INSTANT_BANK_TRANSFER_FINLAND = 100;
  INSTANT_BANK_TRANSFER_POLAND = 101;
  SATISPAY = 102;
  WERO = 103;
  NETWORK_TOKEN = 104;
  NETBANKING = 105;
  LAZY_PAY = 106;
  PHONE_PE = 107;
  BILL_DESK = 108;
  CASH_FREE = 109;
  PAY_U = 110;
  EASE_BUZZ = 111;
  OPEN_BANKING = 112;
  QWIKCILVER_WALLET = 113;
  SKRILL = 114;
  PAYMAYA = 115;
}

// Product type enumeration
enum ProductType {
  PRODUCT_TYPE_UNSPECIFIED = 0; // Default value
  PHYSICAL = 1;
  DIGITAL = 2;
  TRAVEL = 3;
  RIDE = 4;
  EVENT = 5;
  ACCOMMODATION = 6;
}

// Dispute stage enumeration
enum DisputeStage {
  DISPUTE_STAGE_UNSPECIFIED = 0; // Default value
  PRE_DISPUTE = 1;
  ACTIVE_DISPUTE = 2;
  PRE_ARBITRATION = 3;
}

// Tokenization options for payment processing
enum Tokenization {
  TOKENIZATION_UNSPECIFIED = 0;     // Default value
  TOKENIZATION_TOKENIZE_AT_PSP = 1; // Use default tokenization behavior
  TOKENIZATION_SKIP_PSP = 2;        // Skip PSP-side token creation
}

// Represents a physical address with contact information
message Address {
  // Personal Information
  optional SecretString first_name = 1;
  optional SecretString last_name = 2;

  // Address Details
  optional SecretString line1 = 3;
  optional SecretString line2 = 4;
  optional SecretString line3 = 5;
  optional SecretString city = 6;
  optional SecretString state = 7;
  optional SecretString zip_code = 8;
  optional CountryAlpha2 country_alpha2_code = 9;

  // Contact Information
  optional SecretString email = 10;
  optional SecretString phone_number = 11;
  optional string phone_country_code = 12;
}

// Details of a single product in an order
message OrderDetailsWithAmount {
  // Name of the product that is being purchased
  string product_name = 1;
  // The quantity of the product to be purchased
  uint32 quantity = 2;
  // Amount per quantity (in minor currency units)
  int64 amount = 3;
  // Tax rate applicable to the product
  optional double tax_rate = 4;
  // Total tax amount (in minor currency units)
  optional int64 total_tax_amount = 5;
  // Indicates if the product requires shipping
  optional bool requires_shipping = 6;
  // The image URL of the product
  optional string product_img_link = 7;
  // ID of the product that is being purchased
  optional string product_id = 8;
  // Category of the product that is being purchased
  optional string category = 9;
  // Sub category of the product that is being purchased
  optional string sub_category = 10;
  // Brand of the product that is being purchased
  optional string brand = 11;
  // Description for the item
  optional string description = 12;
  // Unit of measure used for the item quantity.
  optional string unit_of_measure = 13;
  // Type of the product that is being purchased
  optional ProductType product_type = 14;
  // The tax code for the product
  optional string product_tax_code = 15;
  // Stock Keeping Unit (SKU) or item identifier for the product
  optional string sku = 16;
  // Universal Product Code for the product
  optional string upc = 17;
  // Commodity code describing the product classification
  optional string commodity_code = 18;
  // Discount amount applied to a single unit (in minor currency units)
  optional int64 unit_discount_amount = 19;
  // Discount name applied to this item
  optional string discount_name = 20;
  // Discount percentage applied to this item
  optional double discount_percentage = 21;
  // Discount type applied to this item
  optional string discount_type = 22;
}

// Access token details
message AccessToken {
  // The token string.
  SecretString token = 1;
  // Expiration timestamp (seconds since epoch)
  optional int64 expires_in_seconds = 2;
  // Token type (e.g., "Bearer", "Basic").
  optional string token_type = 3;
}

// State data for connector storage
message ConnectorState {
  // Access token obtained from connector
  optional AccessToken access_token = 1;
  // Connector's customer ID (e.g., Authorize.net customer profile ID)
  optional string connector_customer_id = 2;
}

// Billing descriptor information
message BillingDescriptor {
  // Customer's billing name
  optional SecretString name = 1;
  // Customer's billing city
  optional SecretString city = 2;
  // Customer's billing phone number
  optional SecretString phone = 3;
  // Complete description that appears on customers' statements
  optional string statement_descriptor = 4;
  // Provides information about a card payment that customers see on their
  // statements
  optional string statement_descriptor_suffix = 5;
  // A reference to be shown on billing description
  optional string reference = 6;
}

// Algorithm used to generate CAVV (Cardholder Authentication Verification
// Value)
enum CavvAlgorithm {
  CAVV_ALGORITHM_UNSPECIFIED = 0;
  CAVV_ALGORITHM_ZERO = 1; // "00" — Reserved or unspecified algorithm.
  CAVV_ALGORITHM_ONE = 2;  // "01" — HMAC-based algorithm.
  CAVV_ALGORITHM_TWO =
      3; // "02" — RSA-based algorithm (standard 3DS cryptographic method).
  CAVV_ALGORITHM_THREE = 4; // "03" — Elliptic Curve algorithm.
  CAVV_ALGORITHM_FOUR =
      5; // "04" — Proprietary algorithm defined by the card network.
  CAVV_ALGORITHM_A = 6; // "A" — Custom or network-defined algorithm indicator.
}

// Cartes Bancaires network-specific parameters for 3DS
message CartesBancairesParams {
  // Algorithm used to generate the CAVV value.
  CavvAlgorithm cavv_algorithm = 1;

  // Exemption indicator specific to Cartes Bancaires network.
  string cb_exemption = 2;

  // Cartes Bancaires risk score assigned during 3DS authentication.
  int32 cb_score = 3;
}

// Network-level parameters for 3DS processing
message NetworkParams {
  // Parameters specific to Cartes Bancaires network, if applicable.
  optional CartesBancairesParams cartes_bancaires = 1;
}

// Type of decoupled (external) 3DS authentication that was performed.
enum DecoupledAuthenticationType {
  // Unspecified/default value.
  DECOUPLED_AUTHENTICATION_TYPE_UNSPECIFIED = 0;
  // Challenge flow - the cardholder was challenged by the ACS.
  DECOUPLED_AUTHENTICATION_TYPE_CHALLENGE = 1;
  // Frictionless flow - authentication completed without a challenge.
  DECOUPLED_AUTHENTICATION_TYPE_FRICTIONLESS = 2;
}

// Additional authentication data, typically from 3DS
message AuthenticationData {
  // Electronic Commerce Indicator (ECI) from 3DS.
  optional string eci = 1;
  // Cardholder Authentication Verification Value (CAVV).
  optional string cavv = 2;
  // 3DS Server Transaction ID.
  optional string threeds_server_transaction_id = 3;

  // 3DS Message Version (e.g., "2.1.0", "2.2.0").
  optional string message_version = 4;
  // Directory Server Transaction ID (DS Trans ID).
  optional string ds_transaction_id = 5;
  // Transaction status from authentication/verification process.
  optional TransactionStatus trans_status = 6;
  // ACS Transaction ID (ACS Trans ID).
  optional string acs_transaction_id = 7;
  // Transaction identifier generated by the 3DS system.
  optional string connector_transaction_id = 8;
  // UCAF (Universal Cardholder Authentication Field) collection indicator.
  optional string ucaf_collection_indicator = 9;
  // SCA exemption indicator for this authentication.
  optional ExemptionIndicator exemption_indicator = 10;
  // Network-specific parameters for 3DS processing.
  optional NetworkParams network_params = 11;
  // Authentication timestamp (Unix epoch seconds, UTC) when the 3DS
  // authentication was performed. Used by connectors (e.g. Cybersource) that
  // send an authenticationDate in their request.
  optional int64 created_at = 12;
  // 3DS challenge code from the ACS challenge flow (e.g. Cybersource
  // challengeCode).
  optional string challenge_code = 13;
  // 3DS challenge cancellation indicator (e.g. Cybersource
  // challengeCancelCode).
  optional string challenge_cancel = 14;
  // Reason associated with the 3DS challenge code (e.g. Cybersource
  // signedParesStatusReason).
  optional string challenge_code_reason = 15;
  // JSON-serialized 3DS message extension attributes (e.g. Cartes Bancaires
  // score used for Cybersource networkScore).
  optional string message_extension = 16;
  // Type of decoupled (external) authentication performed (challenge vs
  // frictionless). Used by connectors (e.g. Cybersource
  // effectiveAuthenticationType).
  optional DecoupledAuthenticationType authentication_type = 17;
}

// Details of customer acceptance for mandates or terms
message CustomerAcceptance {
  // Type of acceptance (e.g., online, offline).
  AcceptanceType acceptance_type = 1;
  // Timestamp when the acceptance was made (Unix timestamp, seconds since
  // epoch).
  int64 accepted_at = 2;
  // Details if the acceptance was an online mandate.
  optional OnlineMandate online_mandate_details = 3;
}

// Details for an online mandate acceptance
message OnlineMandate {
  // IP address from which the mandate was accepted.
  optional string ip_address = 1;
  // User agent string of the browser used for mandate acceptance.
  string user_agent = 2;
}

// Amount data for mandate.
//
// Also carries subscription / recurring-order context consumed by FRM risk
// scoring (e.g. Kount's `recurring` block). In that FRM usage `amount` is the
// per-period billing amount and `frequency` is the billing period.
message MandateAmountData {
  int64 amount = 1 [deprecated = true]; // Use amount_money instead (will be removed in a future release)
  Currency currency = 2 [deprecated = true]; // Use amount_money.currency instead (will be removed in a future release)
  optional int64 start_date = 3;        // Unix timestamp for start date
  optional int64 end_date = 4;          // Unix timestamp for end date
  optional string amount_type =
      5; // Amount type for variable mandates ("exact", "max", "variable")
  optional string frequency =
      6; // Frequency for recurring mandates ("daily", "weekly", "monthly")
  optional Money amount_money = 7; // Amount in Money type

  // Initial / First billing amount.
  optional Money initial_billing_amount = 8;
  // Merchant's external subscription identifier.
  optional string external_subscription_id = 9;
  // Subscription status. UNSPECIFIED (0) means undefined / unset.
  MandateStatus mandate_status = 10;
  // Unix timestamp for the next billing date.
  optional int64 next_billing_date = 11;
  // Number of billing cycles elapsed / scheduled.
  optional int32 billing_cycle = 12;
  // Free-form description of the subscription.
  optional string description = 13;
}

// Mandate type with amount details
message MandateType {
  oneof mandate_type {
    // Single use mandate with amount details
    MandateAmountData single_use = 1;

    // Multi use mandate with amount details (for recurring payments)
    MandateAmountData multi_use = 2;
  }
}

// Setup mandate details for payment authorization
message SetupMandateDetails {
  // A way to update the mandate's payment method details
  optional string update_mandate_id = 1;
  // Details of customer acceptance
  optional CustomerAcceptance customer_acceptance = 2;

  // Type of mandate (single_use or multi_use) with amount details
  optional MandateType mandate_type = 3;
}

// Information about the customer's browser
message BrowserInformation {
  // Display Information
  optional uint32 color_depth = 1;
  optional uint32 screen_height = 2;
  optional uint32 screen_width = 3;
  // Browser Settings
  optional bool java_enabled = 4;
  optional bool java_script_enabled = 5;
  optional string language = 6;
  optional int32 time_zone_offset_minutes = 7;

  // Browser Headers
  optional string accept_header = 8;
  optional string user_agent = 9;
  optional string accept_language = 10;
  optional string referer = 11;

  // Device Information
  optional string ip_address = 12;
  optional string os_type = 13;
  optional string os_version = 14;
  optional string device_model = 15;
}

message MandateReferenceDetails {
  optional string connector_mandate_id = 1;
  optional string payment_method_id = 2;
  optional string connector_mandate_request_reference_id = 3;
  optional SecretString mandate_metadata = 4;
}

message MandateReference {
  oneof mandate_id_type {
    // mandate_id sent by the connector
    ConnectorMandateReferenceId connector_mandate_id = 1;

    // network_mandate_id sent by Issuer to connector, Used for PG agnostic mandate
    // txns along with card data
    NetworkMandateId network_mandate_id = 2;

    // network_txns_id sent by Issuer to connector, Used for PG agnostic mandate
    // txns along with network token data
    NetworkTokenWithNTI network_token_with_nti = 3;
  }
}

message ConnectorMandateReferenceId {
  optional string connector_mandate_id = 1;
  optional string payment_method_id = 2;
  optional string connector_mandate_request_reference_id = 3;
  optional SecretString mandate_metadata = 4;
}

message NetworkMandateId {
  string network_transaction_id = 1;
  // Mastercard Transaction Link Identifier (TLID) provided by the card network
  // during a CIT when setup_future_usage is off_session.
  optional string transaction_link_id = 2;
}

message NetworkTokenWithNTI {
  string network_transaction_id = 1;
  optional SecretString token_exp_month = 2;
  optional SecretString token_exp_year = 3;
  // Mastercard Transaction Link Identifier (TLID) provided by the card network
  // during a CIT when setup_future_usage is off_session.
  optional string transaction_link_id = 4;
}

// Container for various address types related to a payment
message PaymentAddress {
  Address shipping_address = 1;
  Address billing_address = 2;
}

// Tax status for L2/L3 data.
enum TaxStatus {
  TAX_STATUS_UNSPECIFIED = 0; // Default value
  TAX_STATUS_TAXABLE = 1;     // The order is taxable
  TAX_STATUS_EXEMPT = 2;      // The order is tax-exempt
}

// Order-level information for L2/L3 data.
message OrderInfo {
  // Date the order was placed (Unix timestamp in seconds)
  optional int64 order_date = 1;

  // Line items for the order
  repeated OrderDetailsWithAmount order_details = 2;

  // Merchant's internal reference ID for the order
  optional string merchant_order_reference_id = 3;

  // Discount applied to the order (in minor currency units)
  optional int64 discount_amount = 4;

  // Shipping cost for the order (in minor currency units)
  optional int64 shipping_cost = 5;

  // Duty/customs amount for the order (in minor currency units)
  optional int64 duty_amount = 6;
}

// Tax information for L2/L3 data.
message TaxInfo {
  // Tax status of the order
  optional TaxStatus tax_status = 1;

  // Customer's tax registration ID (sensitive)
  optional SecretString customer_tax_registration_id = 2;

  // Merchant's tax registration ID (sensitive)
  optional SecretString merchant_tax_registration_id = 3;

  // Tax on the shipping amount (in minor currency units)
  optional int64 shipping_amount_tax = 4;

  // Total tax amount for the order (in minor currency units)
  optional int64 order_tax_amount = 5;
}

// Level 2 / Level 3 data for enhanced payment processing.
message L2L3Data {
  // Order-level information
  optional OrderInfo order_info = 1;

  // Tax information
  optional TaxInfo tax_info = 2;
}

// Domain-specific data supplied by the merchant.
message DomainData {
  optional AirlineData airline_data = 1; // Airline / travel itinerary data
  optional EducationData education_data = 2; // Education / student data
}

// Connector-agnostic education data (e.g. Flywire tuition payments).
message EducationData {
  optional StudentDetails student_details = 1;
}

// Student details for education payments (e.g. Flywire recipient fields).
message StudentDetails {
  optional string student_id = 1;
  optional string student_first_name = 2;
  optional string student_last_name = 3;
  optional SecretString student_email = 4; // PII — student's email address
}

// Whether the ticket can be refunded 
enum TicketRefundability {
  TICKET_REFUNDABILITY_UNSPECIFIED = 0;
  REFUNDABLE = 1;
  NON_REFUNDABLE = 2;
}

// Ticket medium — electronic vs paper
enum TicketDeliveryType {
  TICKET_DELIVERY_TYPE_UNSPECIFIED = 0;
  ELECTRONIC = 1;
  PAPER = 2;
}

// Whether the cardholder is among the passengers a fraud signal.
enum CardholderTravelStatus {
  CARDHOLDER_TRAVEL_STATUS_UNSPECIFIED = 0;
  CARDHOLDER_TRAVELING = 1;
  CARDHOLDER_NOT_TRAVELING = 2;
}

// Connector-agnostic airline / travel itinerary data. The union of fields
// across processors (2C2P PACO, CyberSource, Adyen, Worldpay, Checkout.com,
// Nuvei); every field is optional so each connector enforces its own required
// subset. Amounts use Money (minor units + currency); dates are strings since
// processors disagree on format.
message AirlineData {
  // ---- Booking / ticket level ----
  optional string pnr_code = 1;                 // PNR / reservation-system code
  optional string booking_reference = 2;        // Merchant booking / customer reference
  optional string ticket_number = 3;            // Airline ticket number
  optional string ticket_issue_date = 4;        // Date the ticket was issued
  optional string booking_date_time = 5;        // Booking timestamp (RFC 3339)
  optional string flight_date = 6;              // Departure date of the first leg
  optional string issuing_carrier_code = 7;     // IATA code of the ticket issuer
  optional string airline_code = 8;             // IATA numeric accounting code
  optional string passenger_name = 9;           // Primary passenger name
  optional uint32 number_of_passengers = 10;    // Passenger count on the ticket
  optional string document_type = 11;           // Travel document type code
  TicketRefundability refundability = 12;       // Refundable / non-refundable
  TicketDeliveryType ticket_delivery_type = 13; // Electronic vs paper ticket
  CardholderTravelStatus cardholder_travel_status = 14; // Is the cardholder a passenger
  optional Address ticket_issue_address = 15;   // Address of the issuing agency
  optional string booking_system_unique_id = 16; // Booking-system unique identifier

  // Travel agency
  optional string agency_code = 20;             // IATA / ARC travel agency code
  optional string agency_name = 21;             // Travel agency name
  optional string agency_invoice_number = 22;   // Agency-issued invoice number
  optional string agency_plan_name = 23;        // Agency plan identifier

  // Ticket-level amounts (each carries its own currency)
  optional Money total_fare = 30;               // Total ticket fare
  optional Money total_taxes = 31;              // Total taxes on the ticket
  optional Money total_fee = 32;                // Total fees on the ticket
  optional Money boarding_fee = 33;             // Chargeable boarding fee

  repeated AirlineSegment flight_segments = 40; // Flight legs, in itinerary order
  repeated AirlinePassenger passengers = 41;    // Passengers on the ticket
}

// One flight leg. departure/arrival reuse the shared AirlineLocation, mirroring
// how Address is reused for billing/shipping.
message AirlineSegment {
  optional uint32 sequence_no = 1;              // 1-based leg order
  optional string marketing_carrier_code = 2;   // Marketing carrier IATA-2 (ticket-issuing airline)
  optional string flight_number = 3;            // Marketing flight number
  optional string flight_type = 4;              // "Domestic" / "International"
  optional string class_of_service = 5;         // F / J / Y / W
  optional string fare_basis_code = 6;          // Fare basis code
  optional string stopover_code = 7;            // O = stopover allowed / X = not
  AirlineLocation departure = 8;                // Departure endpoint
  AirlineLocation arrival = 9;                  // Arrival endpoint

  // Per-leg amounts (each carries its own currency)
  optional Money fare_amount = 10;              // Fare for this leg
  optional Money fee_amount = 11;               // Fee for this leg
  optional Money tax_amount = 12;               // Departure tax for this leg

  // Exchange / coupon details
  optional string exchange_ticket_number = 13;  // New ticket number on exchange
  optional string conjunction_ticket = 14;      // Conjunction ticket for >4 legs
  optional string coupon_number = 15;           // Coupon number for this leg
  optional string endorsements_restrictions = 16; // Endorsements / restrictions

  optional string operating_carrier_code = 17;  // Operating carrier IATA-2
  optional string operating_flight_number = 18; // Operating flight number
}

// A flight endpoint, reused for both departure and arrival.
message AirlineLocation {
  optional string airport_code = 1;             // IATA-3 airport code
  optional string city_code = 2;                // IATA-3 city code
  optional string city_name = 3;                // City name
  optional string country_code = 4;             // ISO 3166-1 alpha-2 country code (connectors convert to numeric/alpha-3 as needed)
  optional string country_name = 5;             // Country name
  optional string date_time = 6;                // Local scheduled time (RFC 3339)
}

message AirlinePassenger {
  optional uint32 sequence_no = 1;              // 1-based passenger order

  // Identity fields shared with the cardholder/payer model — salutation,
  // first_name, last_name, email (Secret) and phone_number (Secret).
  optional Customer customer = 2;

  // Passenger-specific fields not on Customer.
  optional string middle_name = 3;              // Middle name
  optional string gender = 4;                   // M / F / X
  optional string date_of_birth = 5;            // Date of birth (yyyy-MM-dd)
  optional string passenger_type = 6;           // IATA PTC, e.g. ADT
  optional string frequent_flyer_number = 7;    // Loyalty / frequent-flyer number
  optional string loyalty_tier = 8;             // Loyalty-program tier
  optional SecretString passport_number = 9;    // Passport number
  optional string nationality = 10;             // ISO 3166-1 alpha-2 nationality
  optional SecretString ticket_number = 11;     // Per-passenger ticket number
}

// Redirection response data
message RedirectionResponse {
  optional string params = 1;
  map<string, string> payload = 2;
}

// Data for a redirection, can be either form data, raw HTML, or URI.
message RedirectForm {
  oneof form_type {
    // Data for constructing an HTML form for redirection.
    FormData form = 1;
    // Raw HTML data for redirection.
    HtmlData html = 2;

    // URI for direct redirection (e.g., UPI deep links).
    UriData uri = 3;

    // Braintree-specific redirection data for SDK-based flows.
    BraintreeData braintree = 4;

    // Mifinity-specific redirection data for SDK-based flows.
    MifinityData mifinity = 5;

    // NMI-specific redirection data for 3DS flows.
    NmiData nmi = 6;

    // Generic hosted-iframe redirection: load `endpoint` in an iframe and
    // attach the connector-built `events` postMessage listener.
    HostedIframeData hosted_iframe = 7;
  }
}

// Represents data for an HTML form to be submitted
message FormData {
  // The endpoint URL where the form should be submitted.
  string endpoint = 1;

  // HTTP method to be used for form submission (e.g., POST).
  HttpMethod method = 2;

  // Key-value pairs representing the form fields.
  map<string, string> form_fields = 3;
}

// Represents raw HTML data
message HtmlData {
  // The HTML content as a string.
  string html_data = 1;
}

// Represents URI data for direct redirection
message UriData {
  // The URI for redirection (e.g., UPI deep link).
  string uri = 1;
}

// Represents Braintree-specific redirection data
message BraintreeData {
  // Client token for Braintree SDK initialization
  string client_token = 1;

  // Tokenized payment method identifier
  string card_token = 2;

  // Bank Identification Number for card verification
  string bin = 3;

  // URL for completing the authorization flow
  string acs_url = 4;
}

// Represents Mifinity-specific redirection data
message MifinityData {
  // Initialization token for Mifinity SDK initialization
  string initialization_token = 1;
}

// Generic hosted-iframe redirection data. The connector supplies a URL to
// load into an iframe and a self-contained postMessage listener script that
// navigates the payer to the (pre-substituted) return URL on completion.
message HostedIframeData {
  // URL to load inside the iframe.
  string endpoint = 1;

  // HTTP method the client should use to fetch `endpoint`.
  HttpMethod method = 2;

  // postMessage listener script; `return_url` is already substituted by the
  // connector so the client just inlines this verbatim in a <script> tag.
  string events = 3;
}

// Represents NMI-specific redirection data for 3DS flows
message NmiData {
  // Transaction amount
  Money amount = 1;

  // NMI public key for 3DS
  SecretString public_key = 2;

  // Customer vault ID for the tokenized card
  string customer_vault_id = 3;

  // Order ID for the transaction
  string order_id = 4;

  // URL to redirect to after 3DS completion
  string continue_redirection_url = 5;
}

// Details of an HTTP request, typically for incoming webhooks
message RequestDetails {
  // HTTP method of the request (e.g., GET, POST).
  HttpMethod method = 1;

  // URI of the request.
  optional string uri = 2;

  // Headers of the HTTP request.
  map<string, string> headers = 3;

  // Body of the HTTP request.
  bytes body = 4;

  // Query parameters of the request.
  optional string query_params = 5;
}

// Secrets used for verifying connector webhooks.
message WebhookSecrets {
  // Primary secret for webhook verification.
  string secret = 1;

  // Additional secret, if required by the connector.
  optional string additional_secret = 2;
}

// Secrets used for source verification.
message RedirectResponseSecrets {
  // Primary secret for source verification.
  string secret = 1;

  // Additional secret, if required by the connector.
  optional string additional_secret = 2;
}

// Integrity dimensions a connector can confirm are present in a webhook payload.
enum IntegrityCheck {
  INTEGRITY_CHECK_UNSPECIFIED = 0; // Default value
  INTEGRITY_CHECK_CONNECTOR_TRANSACTION_ID = 1; // Maps to: EventContent.*.connector_transaction_id
  INTEGRITY_CHECK_AMOUNT = 2; // Maps to: EventContent.payments_response.amount.minor_amount
  INTEGRITY_CHECK_CURRENCY = 3; // Maps to: EventContent.payments_response.amount.currency
}

// Response for EventService.HandleEvent.
// event_content mirrors PaymentService.Get / RefundService.Get / DisputeService.Get.
// Returns INVALID_ARGUMENT if required EventContext fields are absent for this connector.

// Response for handling an event, which may contain different types of content
// based on the event type.
message EventServiceHandleResponse {
  // Event type
  WebhookEventType event_type = 1;

  // Content
  EventContent event_content = 2;

  // Verification
  bool source_verified = 3;

  // Reference
  optional string merchant_event_id = 4;

  // Suggested HTTP response to send back to the connector for webhook acknowledgement
  optional EventAckResponse event_ack_response = 5;

  // Integrity fields that downstream can use to verify the webhook payload.
  repeated IntegrityCheck supported_integrity_checks = 6;
}

// Request for notifying connectors about events
message NotifyConnectorRequest {
  // Unique event identifier
  string event_id = 1;

  // Event type
  NotifyEventType event_type = 2;

  // Event content with notify connector content
  NotifyConnectorContent content = 3;

  // Timestamp when the event occurred (Unix timestamp in seconds)
  int64 timestamp = 4;

  // Connector state for access token management (optional)
  optional ConnectorState state = 5;
}


// Content of an event
message NotifyConnectorContent {
  oneof content {
    // surcharge details
    SurchargeContent surcharge_content = 1;

    // FRM notification content
    FrmNotificationContent frm_notification = 2;
  }
}


// Surcharge details object
message SurchargeContent {
  // Connector surcharge identifier
  string connector_surcharge_id = 1;
}

// Risk management decision outcomes from the FRM service
enum FrmDecision {
  FRM_DECISION_UNSPECIFIED = 0; // Default, unspecified FRM Decision
  APPROVE = 1;                  // Transaction is low risk; proceed with payment authorization.
  REJECT = 2;                   // Transaction is fraudulent or high risk; block the payment.
  REVIEW = 3;                   // Transaction is suspicious; hold for manual review.
  ERROR = 4;                    // The FRM check itself failed (network, timeout, misconfiguration).
}

// Merchant details used for FRM risk scoring.
message MerchantDetails {
  // Merchant identifier.
  optional string merchant_id = 1;

  // Merchant Category Code (ISO 18245).
  optional uint32 merchant_category_code = 2;
}

// Unified FRM notification content.
// Used for all FRM lifecycle events (payment success, refund, chargeback).
message FrmNotificationContent {
  // Merchant-facing identifiers
  optional string connector_transaction_id = 1;
  Money amount = 2;

  // Correlation ID from PreRiskCheck, if available
  optional string frm_transaction_id = 3;

  // The specific notification type — exactly one must be set
  oneof notification_type {
    FrmPaymentDetails payment_details = 4;
    FrmRefundDetails refund = 5;
    FrmChargebackDetails chargeback = 6;
  }

  // Risk assessment outcome
  optional FrmDecision frm_decision = 7;

  // Merchant details for risk scoring.
  optional MerchantDetails merchant_details = 8;
}

// FRM payment success details
message FrmPaymentDetails {
  optional string connector_transaction_id = 1;
  optional string merchant_transaction_id = 2;
  PaymentStatus payment_status = 3;
}

// FRM refund details
message FrmRefundDetails {
  optional string connector_refund_id = 1;
  optional string merchant_refund_id = 2;
  optional string refund_reason = 3;
}

// FRM chargeback details
message FrmChargebackDetails {
  optional string connector_dispute_id = 1;
  optional string merchant_dispute_id = 2;
  optional string chargeback_reason = 3;
}

// Response for notifying connectors
message NotifyConnectorResponse {
  // Status of the notification
  uint32 status_code = 1;

  // Optional error information if notification failed
  optional ErrorInfo error = 2;
}

// Suggested HTTP response for webhook acknowledgement (status, headers, body).
message EventAckResponse {
  uint32 status_code = 1;
  map<string, string> headers = 2;
  bytes body = 3;
}

// Content of an event
message EventContent {
  oneof content {
    // Content if the event is for a payment synchronization.
    PaymentServiceGetResponse payments_response = 1;
    // Content if the event is for a refund synchronization.
    RefundResponse refunds_response = 2;
    // Content if the event is for a dispute synchronization.
    DisputeResponse disputes_response = 3;
  }
}


// Data for a multiple capture request
message MultipleCaptureRequestData {
  // Sequence number for this capture in a series of multiple captures.
  int64 capture_sequence = 1;
  // Reference for this specific capture.
  string capture_reference = 2;
}

// Type of evidence that can be submitted for a dispute
enum EvidenceType {
  EVIDENCE_TYPE_UNSPECIFIED = 0; // Default value
  CANCELLATION_POLICY = 1;       // Cancellation policy document
  CUSTOMER_COMMUNICATION = 2;    // Communication with customer
  CUSTOMER_SIGNATURE = 3;        // Customer signature document
  RECEIPT = 4;                   // Receipt or proof of purchase
  REFUND_POLICY = 5;             // Refund policy document
  SERVICE_DOCUMENTATION = 6;     // Service documentation
  SHIPPING_DOCUMENTATION = 7;    // Shipping documentation
  INVOICE_SHOWING_DISTINCT_TRANSACTIONS =
      8;                               // Invoice showing distinct transactions
  RECURRING_TRANSACTION_AGREEMENT = 9; // Recurring transaction agreement
  UNCATEGORIZED_FILE = 10;             // Uncategorized evidence file
}

// Represents a single piece of evidence for a dispute
message EvidenceDocument {
  // Type of the evidence.
  EvidenceType evidence_type = 1;
  // Content Options
  // Content of the document, if it's a file.
  optional bytes file_content = 2;
  // MIME type of the file (e.g., "application/pdf", "image/png"), if
  // file_content is provided.
  optional string file_mime_type = 3;
  // Identifier for the file if stored with an external provider.
  optional string provider_file_id = 4;
  // Textual content of the evidence, if it's not a file or in addition to a
  // file.
  optional string text_content = 5;
}

// Extended authorization response data
message ExtendedAuthorizationResponseData {
  optional bool extended_authentication_applied =
      1; // Whether extended authentication was applied
  optional int64 capture_before =
      2; // Unix timestamp before which capture must occur
  optional int64 extended_authorization_last_applied_at =
      3; // Unix timestamp of when extended authentication was last applied
}

// Additional payment method data for card payments
message CardConnectorResponse {
  optional bytes authentication_data =
      1;                             // Authentication details as JSON bytes
  optional bytes payment_checks = 2; // Payment checks as JSON bytes
  optional string card_network = 3;  // Card network returned by the processor
  optional string domestic_network = 4; // Domestic (co-branded) card network
  optional string auth_code =
      5; // Unique authorisation code generated for the payment
}

// Additional card information for payment processing
message AdditionalCardInfo {
  // The name of issuer of the card
  optional string card_issuer = 1;

  // Last 4 digits of the card number
  optional string last4 = 2;

  // The ISIN of the card
  optional string card_isin = 3;

  // Extended bin of card, contains the first 8 digits of card number
  optional string card_extended_bin = 4;

  // Card expiry month (sensitive)
  optional SecretString card_exp_month = 5;

  // Card expiry year (sensitive)
  optional SecretString card_exp_year = 6;

  // Card holder name (sensitive)
  optional SecretString card_holder_name = 7;

}

// Additional payment data for various payment methods
message AdditionalPaymentData {
  oneof payment_method_data {
    AdditionalCardInfo card = 1;
  }
}

// Additional payment method data for Google Pay
message GooglePayConnectorResponse {
  optional string auth_code =
      1; // Unique authorisation code generated for the payment
}

// Additional payment method data for Apple Pay
message ApplePayConnectorResponse {
  optional string auth_code =
      1; // Unique authorisation code generated for the payment
}

// Customer information for payments
message CustomerInfo {
  optional SecretString customer_name = 1; // Full name of the customer
  optional SecretString customer_email =
      2; // Email address of the customer for notifications and receipts
  optional SecretString customer_phone_number =
      3; // Phone number for SMS verification and customer contact
  optional SecretString customer_bank_id =
      4; // Bank identifier or institution number for the customer's bank
  optional SecretString customer_bank_name =
      5; // Name of the customer's bank for display purposes
}

// Interac-specific customer information wrapper
message InteracCustomerInfo {
  optional CustomerInfo customer_info =
      1; // Base customer information for Interac payments
}

// Additional payment method data for Bank Redirect
message BankRedirectConnectorResponse {
  optional InteracCustomerInfo interac =
      1; // Interac-specific customer information when using bank redirect
}

// Additional payment method connector response
message AdditionalPaymentMethodConnectorResponse {
  oneof payment_method_data {
    CardConnectorResponse card = 1; // Card-specific response data
    UpiConnectorResponse upi = 2;   // UPI-specific response data
    GooglePayConnectorResponse google_pay =
        3; // Google Pay-specific response data
    ApplePayConnectorResponse apple_pay = 4; // Apple Pay-specific response data
    BankRedirectConnectorResponse bank_redirect =
        5; // Bank Redirect-specific response data
  }
}

// Connector response data containing various information from the connector
message ConnectorResponseData {
  // Additional payment method specific data
  optional AdditionalPaymentMethodConnectorResponse
      additional_payment_method_data = 1;
  // Extended authorization data
  optional ExtendedAuthorizationResponseData
      extended_authorization_response_data = 2;
  // Whether overcapture is enabled
  optional bool is_overcapture_enabled = 3;
}

// Payment method update information extracted from a connector response or webhook.
// This is intended to be used by integrators to update stored payment method details
// (e.g., expiry/last4 updates from network account updater programs).
message PaymentMethodUpdate {
  oneof payment_method_update_data {
    CardDetailUpdate card = 1;
  }
}

message CardDetailUpdate {
  optional string card_exp_month = 1;
  optional string card_exp_year = 2;
  optional string last4_digits = 3;
  optional string issuer_country = 4;
  optional string card_issuer = 5;
  optional string card_network = 6;
  optional string card_holder_name = 7;
}

// ============================================================================
// SDK SESSION DATA MESSAGES
// ============================================================================

message ClientAuthenticationTokenData {
  oneof sdk_type {
    // Wallet SDKs — standalone digital wallets, independent of payment connector
    GpayClientAuthenticationResponse google_pay = 1;
    PaypalClientAuthenticationResponse paypal = 2;
    ApplepayClientAuthenticationResponse apple_pay = 3;
    // Connector SDKs — payment connector-specific SDKs for rendering payment forms
    ConnectorSpecificClientAuthenticationResponse connector_specific = 4;
    // Authenticator SDKs — account linking/verification flows
    AuthenticatorConnectorSpecificClientAuthenticationResponse authenticator_connector_specific = 5;
  }
}

// Generic authenticator connector-specific SDK session data — discriminated by connector
message AuthenticatorConnectorSpecificClientAuthenticationResponse {
  oneof connector {
    PlaidClientAuthenticationResponse plaid = 1;
  }
}

// Generic connector-specific SDK session data — discriminated by connector
message ConnectorSpecificClientAuthenticationResponse {
  oneof connector {
    StripeClientAuthenticationResponse stripe = 1;
    AdyenClientAuthenticationResponse adyen = 2;
    CheckoutClientAuthenticationResponse checkout = 3;
    CybersourceClientAuthenticationResponse cybersource = 4;
    NuveiClientAuthenticationResponse nuvei = 5;
    MollieClientAuthenticationResponse mollie = 6;
    GlobalpayClientAuthenticationResponse globalpay = 7;
    BluesnapClientAuthenticationResponse bluesnap = 8;
    RapydClientAuthenticationResponse rapyd = 9;
    Shift4ClientAuthenticationResponse shift4 = 10;
    BankOfAmericaClientAuthenticationResponse bank_of_america = 11;
    WellsfargoClientAuthenticationResponse wellsfargo = 12;
    FiservClientAuthenticationResponse fiserv = 13;
    ElavonClientAuthenticationResponse elavon = 14;
    NoonClientAuthenticationResponse noon = 15;
    PaysafeClientAuthenticationResponse paysafe = 16;
    BamboraapacClientAuthenticationResponse bamboraapac = 17;
    JpmorganClientAuthenticationResponse jpmorgan = 18;
    BillwerkClientAuthenticationResponse billwerk = 19;
    DatatransClientAuthenticationResponse datatrans = 20;
    BamboraClientAuthenticationResponse bambora = 21;
    PayloadClientAuthenticationResponse payload = 22;
    MultisafepayClientAuthenticationResponse multisafepay = 23;
    NexinetsClientAuthenticationResponse nexinets = 24;
    NexixpayClientAuthenticationResponse nexixpay = 25;
    RevolutClientAuthenticationResponse revolut = 26;
  }
}

// Adyen SDK initialization data — session_id + session_data for Adyen Drop-in/Components
message AdyenClientAuthenticationResponse {
  string session_id = 1;
  SecretString session_data = 2;
}

// Checkout.com SDK initialization data — payment_session_token + payment_session_secret for Frames/Flow
message CheckoutClientAuthenticationResponse {
  string payment_session_id = 1;
  SecretString payment_session_token = 2;
  SecretString payment_session_secret = 3;
}

// Cybersource SDK initialization data — capture_context JWT for Flex Microform SDK
message CybersourceClientAuthenticationResponse {
  SecretString capture_context = 1;
  string client_library = 2;
  string client_library_integrity = 3;
}

// Nuvei SDK initialization data — session_token for client-side SDK operations
message NuveiClientAuthenticationResponse {
  SecretString session_token = 1;
}

// Mollie SDK initialization data — payment_id + checkout_url for client-side redirect
message MollieClientAuthenticationResponse {
  string payment_id = 1;
  SecretString checkout_url = 2;
}

// Globalpay SDK initialization data — access_token for client-side SDK operations
message GlobalpayClientAuthenticationResponse {
  SecretString access_token = 1;
  optional string token_type = 2;
  optional int64 expires_in = 3;
}

// Bluesnap SDK initialization data — pfToken for Hosted Payment Fields initialization
message BluesnapClientAuthenticationResponse {
  SecretString pf_token = 1;
}

// Rapyd SDK initialization data — checkout_id + redirect_url for client-side checkout
message RapydClientAuthenticationResponse {
  string checkout_id = 1;
  string redirect_url = 2;
}

// Shift4 SDK initialization data — client_secret for client-side SDK
message Shift4ClientAuthenticationResponse {
  SecretString client_secret = 1;
}

// Bank of America SDK initialization data — capture_context JWT for Flex Microform
message BankOfAmericaClientAuthenticationResponse {
  SecretString capture_context = 1;
}

// Wellsfargo SDK initialization data — capture_context JWT for Flex Microform
message WellsfargoClientAuthenticationResponse {
  SecretString capture_context = 1;
}

// Fiserv SDK initialization data — session_id for client-side SDK
message FiservClientAuthenticationResponse {
  SecretString session_id = 1;
}

// Elavon SDK initialization data — session_token for Converge Hosted Payments Lightbox
message ElavonClientAuthenticationResponse {
  SecretString session_token = 1;
}

// Noon SDK initialization data — order_id + checkout_url
message NoonClientAuthenticationResponse {
  uint64 order_id = 1;
  SecretString checkout_url = 2;
}

// Paysafe SDK initialization data — payment_handle_token for client-side SDK
message PaysafeClientAuthenticationResponse {
  SecretString payment_handle_token = 1;
}

// Bamboraapac SDK initialization data — token for client-side SDK
message BamboraapacClientAuthenticationResponse {
  SecretString token = 1;
}

// Jpmorgan SDK initialization data — transaction_id + request_id
message JpmorganClientAuthenticationResponse {
  string transaction_id = 1;
  string request_id = 2;
}

// Billwerk SDK initialization data — session_id for checkout session
message BillwerkClientAuthenticationResponse {
  string session_id = 1;
}

// Datatrans SDK initialization data — transaction_id for Secure Fields initialization
message DatatransClientAuthenticationResponse {
  SecretString transaction_id = 1;
}

// Bambora SDK initialization data — token for Custom Checkout initialization
message BamboraClientAuthenticationResponse {
  SecretString token = 1;
}

// Payload SDK initialization data — client_token for Payload.js Checkout/Secure Input SDK
message PayloadClientAuthenticationResponse {
  SecretString client_token = 1;
}

// Multisafepay SDK initialization data — api_token for Payment Components initialization
message MultisafepayClientAuthenticationResponse {
  SecretString api_token = 1;
}

// Nexinets SDK initialization data — order_id for client-side hosted payment page initialization
message NexinetsClientAuthenticationResponse {
  string order_id = 1;
}

// Nexixpay SDK initialization data — security_token and hosted_page URL for HPP initialization
message NexixpayClientAuthenticationResponse {
  SecretString security_token = 1;
  string hosted_page = 2;
}

// Revolut SDK initialization data — order_id and token for Revolut Pay widget initialization
message RevolutClientAuthenticationResponse {
  // The order ID created on Revolut
  string order_id = 1;
  // The client authentication token for SDK initialization
  SecretString token = 2;
}

// Plaid Link SDK initialization data — link_token for Plaid Link initialization
message PlaidClientAuthenticationResponse {
  SecretString link_token = 1;                    // Required: The Plaid Link token
  optional int64 expires_in_seconds = 2;          // Seconds until the link_token expires
  optional string hosted_link_url = 3;            // Hosted Link URL (if enabled)
}

// Stripe SDK initialization data — client_secret for stripe.confirmPayment()
message StripeClientAuthenticationResponse {
  SecretString client_secret = 1;
}

// Google Pay Session Data
message GpayClientAuthenticationResponse {
  GooglePaySessionResponse google_pay_session = 1;
}

message GooglePayThirdPartySdk {
  bool delayed_session_token = 1;
  string connector = 2;
  SdkNextAction sdk_next_action = 3;
}

message GooglePaySessionResponse {
  GpayMerchantInfo merchant_info = 1;
  bool shipping_address_required = 2;
  bool email_required = 3;
  GpayShippingAddressParameters shipping_address_parameters = 4;
  repeated GpayAllowedPaymentMethods allowed_payment_methods = 5;
  GpayTransactionInfo transaction_info = 6;
  bool delayed_session_token = 7;
  string connector = 8;
  SdkNextAction sdk_next_action = 9;
  optional SecretInfoToInitiateSdk secrets = 10;
}

message GpayMerchantInfo {
  optional string merchant_id = 1;
  string merchant_name = 2;
}

message GpayShippingAddressParameters { bool phone_number_required = 1; }

message GpayAllowedPaymentMethods {
  string payment_method_type = 1;
  GpayAllowedMethodsParameters parameters = 2;
  GpayTokenizationSpecification tokenization_specification = 3;
}

message GpayAllowedMethodsParameters {
  repeated string allowed_auth_methods = 1;
  repeated string allowed_card_networks = 2;
  optional bool billing_address = 3;
  optional GpayBillingAddressParameters billing_address_parameters = 4;
  optional bool assurance_details = 5;
}

message GpayBillingAddressParameters {
  bool phone_number = 1;
  GpayBillingAddressFormat format = 2;
}

enum GpayBillingAddressFormat {
  BILLING_ADDRESS_FORMAT_UNSPECIFIED = 0;
  BILLING_ADDRESS_FORMAT_FULL = 1;
  BILLING_ADDRESS_FORMAT_MIN = 2;
}

message GpayTokenizationSpecification {
  string token_specification_type = 1;
  GpayTokenParameters parameters = 2;
}

message GpayTokenParameters {
  optional string gateway = 1;
  optional string gateway_merchant_id = 2;
  optional string protocol_version = 3;
  optional SecretString public_key = 4;
}

message GpayTransactionInfo {
  CountryAlpha2 country_code = 1;
  Currency currency_code = 2;
  string total_price_status = 3;
  int64 total_price = 4; // Minor units
}

// Apple Pay Session Data
message ApplepayClientAuthenticationResponse {
  optional ApplePaySessionResponse session_response = 1;
  ApplePayPaymentRequest payment_request_data = 2;
  string connector = 3;
  bool delayed_session_token = 4;
  SdkNextAction sdk_next_action = 5;
  optional string connector_reference_id = 6;
  optional string connector_sdk_public_key = 7;
  optional string connector_merchant_id = 8;
}

message ApplePaySessionResponse {
  ThirdPartySdkSessionResponse third_party_sdk = 1;
}

message ThirdPartySdkSessionResponse { SecretInfoToInitiateSdk secrets = 1; }

message NoThirdPartySdkSessionResponse {
  uint64 epoch_timestamp = 1;
  uint64 expires_at = 2;
  string merchant_session_identifier = 3;
  string nonce = 4;
  string merchant_identifier = 5;
  string domain_name = 6;
  string display_name = 7;
  string signature = 8;
  string operational_analytics_identifier = 9;
  uint32 retries = 10;
  string psp_id = 11;
}

message ApplePayPaymentRequest {
  CountryAlpha2 country_code = 1;
  Currency currency_code = 2;
  AmountInfo total = 3;
  repeated string merchant_capabilities = 4;
  repeated string supported_networks = 5;
  optional string merchant_identifier = 6;
}

message AmountInfo {
  string label = 1;
  optional string total_type = 2;
  int64 amount = 3; // Minor units
}

message ApplePayBillingContactFields {
  repeated ApplePayAddressParameters fields = 1;
}

message ApplePayShippingContactFields {
  repeated ApplePayAddressParameters fields = 1;
}

enum ApplePayAddressParameters {
  APPLE_PAY_ADDRESS_PARAMETERS_UNSPECIFIED = 0;
  POSTAL_ADDRESS = 1;
  PHONE = 2;
  EMAIL = 3;
}

message ApplePayRecurringPaymentRequest {
  string payment_description = 1;
  ApplePayRegularBillingRequest regular_billing = 2;
  optional string billing_agreement = 3;
  string management_url = 4;
}

message ApplePayRegularBillingRequest {
  int64 amount = 1; // Minor units
  string label = 2;
  ApplePayPaymentTiming payment_timing = 3;
  optional int64 recurring_payment_start_date = 4;
  optional int64 recurring_payment_end_date = 5;
  optional RecurringPaymentIntervalUnit recurring_payment_interval_unit = 6;
  optional int32 recurring_payment_interval_count = 7;
}

enum ApplePayPaymentTiming {
  APPLE_PAY_PAYMENT_TIMING_UNSPECIFIED = 0;
  IMMEDIATE = 1;
  RECURRING = 2;
}

enum RecurringPaymentIntervalUnit {
  RECURRING_PAYMENT_INTERVAL_UNIT_UNSPECIFIED = 0;
  YEAR = 1;
  MONTH = 2;
  DAY = 3;
  HOUR = 4;
  MINUTE = 5;
}

// PayPal Session Data
message PaypalClientAuthenticationResponse {
  string connector = 1;
  string session_token = 2;
  SdkNextAction sdk_next_action = 3;
  optional string client_token = 4;
  optional PaypalTransactionInfo transaction_info = 5;
}

message PaypalTransactionInfo {
  PaypalFlow flow = 1;
  Currency currency_code = 2;
  int64 total_price = 3; // Minor units
}

enum PaypalFlow {
  PAYPAL_FLOW_UNSPECIFIED = 0;
  PAYPAL_FLOW_CHECKOUT = 1;
}

// Common SDK Session Types
enum SdkNextAction {
  SDK_NEXT_ACTION_UNSPECIFIED = 0;
  SDK_NEXT_ACTION_POST_SESSION_TOKENS = 1;
  SDK_NEXT_ACTION_CONFIRM = 2;
}

message SecretInfoToInitiateSdk {
  SecretString display = 1;
  optional SecretString payment = 2;
}

// ============================================================================
// PAYMENT SERVICE REQUESTS
// ============================================================================

// Request message for authorizing a payment
message PaymentServiceAuthorizeRequest {
  // Identification
  optional string merchant_transaction_id = 1;

  // Amount Information (using Money for consistency)
  Money amount = 2;                    // The amount for the payment
  optional int64 order_tax_amount = 3; // Tax amount for the order
  optional int64 shipping_cost = 4;    // Cost of shipping for the order

  // Payment Method and Capture Settings
  PaymentMethod payment_method = 5;          // Payment method to be used
  optional CaptureMethod capture_method = 6; // Method for capturing the payment

  // Customer Information
  optional Customer customer = 7;

  // Address Information
  PaymentAddress address = 8;

  // Authentication Details
  AuthenticationType auth_type = 9;
  optional bool enrolled_for_3ds = 10;
  optional AuthenticationData authentication_data = 11;

  optional SecretString metadata = 12; // Additional metadata for the connector
  optional SecretString connector_feature_data =
      13; // Connector-specific feature data for the transaction

  // URLs for Redirection and Webhooks
  optional string return_url = 14;
  optional string webhook_url = 15;
  optional string complete_authorize_url = 16;

  // Session and Token Information
  optional string session_token = 17;

  // Order Details
  optional string order_category = 18;
  optional string merchant_order_id = 19;

  // Behavioral Flags and Preferences
  optional FutureUsage setup_future_usage = 20;
  optional bool off_session = 21;
  optional bool request_incremental_authorization = 22;
  optional bool request_extended_authorization = 23;
  optional bool enable_partial_authorization = 24;

  // Contextual Information
  optional CustomerAcceptance customer_acceptance = 25;
  optional BrowserInformation browser_info = 26;
  optional PaymentExperience payment_experience = 27;
  optional string description = 28;
  optional PaymentChannel payment_channel = 29;

  // Environment Configuration
  optional bool test_mode = 30;

  // Mandate Setup Details
  optional SetupMandateDetails setup_mandate_details = 31;

  optional string statement_descriptor_name =
      32; // Complete description that appears on customers' statements

  optional string statement_descriptor_suffix =
      33; // Provides information about a card payment that customers see on
          // their statements

  // Statement Descriptor
  optional BillingDescriptor billing_descriptor = 34;
  // State Information
  optional ConnectorState state = 35;
  // Order Details
  repeated OrderDetailsWithAmount order_details = 36;

  // Locale Information
  optional string locale = 37;

  // Tokenization configuration
  optional Tokenization tokenization_strategy = 38;

  // Indicates if 3DS method data was successfully completed or not
  optional ThreeDsCompletionIndicator threeds_completion_indicator = 39;

  // Redirection Information after DDC step
  optional RedirectionResponse redirection_response =
      40; // Redirection Response from client browser

  // URL for Redirection
  optional string continue_redirection_url =
       41; // URL to complete authorization

  // Level 2 / Level 3 data for enhanced payment processing
  optional L2L3Data l2_l3_data = 43;

  // Send the connector order identifier here if an order was created before
  // authorize
  optional string connector_order_id = 44;

  // Request ID generated by the caller system for payment gateway requests.
  // Required by some connectors for authorize requests.
  optional string merchant_request_id = 45;

  // Domain-specific data (e.g. airline itinerary) the merchant supplies for
  // connectors that need it. Connectors map from this into their own payloads.
  optional DomainData domain_data = 46;

  // Split payment configuration (platform fees, transfers, etc.)
  optional SplitPaymentsDetails split_payments = 47;

  // MIT Category — for CIT (this request) it signals the future intended MIT
  // type; for Authorize-as-MIT (with mandate_id set) it signals the actual
  // MIT category being processed. Mirrors the field on
  // RecurringPaymentServiceChargeRequest.
  optional MitCategory mit_category = 48;

  // Surcharge amount to send separately for connectors that support a first-class
  // surcharge field. This does not change the transaction amount.
  optional Money surcharge_amount = 49;

  optional PartnerMerchantIdentifierDetails partner_merchant_identifier_details = 50;

  // Currency conversion quote and decision data passed through the
  // authorization flow for future connector-specific processing.
  optional CurrencyConversionData currency_conversion_data = 51;
}

// Partner / external-platform application details.
message PartnerApplicationDetails {
  optional string name = 1;
  optional string version = 2;
  optional string integrator = 3;
}

// Merchant application details.
message MerchantApplicationDetails {
  optional string name = 1;
  optional string version = 2;
}

// Partner and merchant application identifiers initiating the request.
message PartnerMerchantIdentifierDetails {
  optional PartnerApplicationDetails partner_details = 1;
  optional MerchantApplicationDetails merchant_details = 2;
}

// Response message for a payment authorization
message PaymentServiceAuthorizeResponse {
  // Identification
  optional string merchant_transaction_id = 1;
  optional string connector_transaction_id = 2;

  // Status Information
  PaymentStatus status = 3;
  optional ErrorInfo error = 4;
  uint32 status_code = 5;
  map<string, string> response_headers = 6;

  // Redirection and Transaction Details
  optional RedirectForm redirection_data = 7;
  optional string network_transaction_id = 8;

  // Authorization Details
  optional bool incremental_authorization_allowed = 9;

  // State Information
  optional ConnectorState state = 10;

  // Raw Response/Request for debugging
  optional SecretString raw_connector_response = 11;
  optional SecretString raw_connector_request = 12;

  // Payment Details
  optional int64 captured_amount = 13;
  optional int64 capturable_amount = 14;
  optional int64 authorized_amount = 15 [deprecated = true]; // use authorized_money instead (will be removed in a future release)
  optional Money authorized_money = 20; // populated from AuthoriseIntegrityObject for integrity check

  // Mandate and Connector Response
  optional MandateReference mandate_reference = 16 [deprecated = true]; // use mandate_reference_details instead (will be removed in a future release)
  optional ConnectorResponseData connector_response = 17;
  optional SecretString connector_feature_data =
      18; // Connector-specific metadata for the transaction
  // A scheme-generated reference that Mastercard intends to use for tracking and linking transactions across the ecosystem.
  // Distinct from network_transaction_id.
  optional string network_txn_link_id = 19;

  // Split payment response data from connector
  optional ConnectorSplitResponseData splits = 21;

  // Mandate reference details returned by the connector for future recurring payments.
  optional MandateReferenceDetails mandate_reference_details = 22;
  // The connector's reported status (code/message/reason).
  optional RawConnectorStatus raw_connector_status = 23;

  // Another reference for the connector's transaction, returned in the connector's response.
  // Distinct from connector_transaction_id — e.g. Stripe charge ID (ch_xxx), order codes, invoice numbers.
  optional string connector_reference_id = 24;

}

// Request message for synchronizing payment status
message PaymentServiceGetRequest {
  // Identification
  optional string merchant_transaction_id = 1;
  string connector_transaction_id = 2;

  optional string encoded_data = 3;

  // Capture Settings
  optional CaptureMethod capture_method = 4;

  reserved 5; // was: handle_response (bytes) — removed as incomplete transformation of webhook is removed

  // Amount Information
  optional Money amount = 6;

  // Behavioral Flags
  optional FutureUsage setup_future_usage = 7;

  // State Information
  optional ConnectorState state = 8;

  optional SecretString metadata = 9; // Additional metadata for the connector
  optional SecretString connector_feature_data =
      10; // Connector-specific metadata for the transaction

  // Sync Type
  optional SyncRequestType sync_type = 11;

  // Connector Reference Id
  optional string connector_order_reference_id = 12;

  // Environment Configuration
  optional bool test_mode = 13;

  // Payment Experience
  optional PaymentExperience payment_experience = 14;

  // Request ID generated by the caller system for payment gateway requests.
  // Required by some connectors that demand a per-request idempotency token.
  optional string merchant_request_id = 15;

  // Payment method type, supplied by the caller so connectors that need it on
  // sync (e.g. Adyen, to build connector_response) can populate it.
  optional PaymentMethodType payment_method_type = 16;

  // Split payment configuration (platform fees, transfers, etc.)
  optional SplitPaymentsDetails split_payments = 17;

  optional ConnectorMandateReferenceId mandate_reference = 18;
}

// Settlement phase reported by the connector on PaymentServiceGetResponse.
enum SettlementStatus {
  // Connector emitted the field but the txn is in neither Settled nor
  // Not-Settled phase (terminal or in-flight states).
  SETTLEMENT_STATUS_UNSPECIFIED = 0;
  // Funds finalised — Refund is the valid reversal.
  SETTLEMENT_STATUS_SETTLED = 1;
  // Authorised only, settlement pending — Void is the valid reversal.
  SETTLEMENT_STATUS_NOT_SETTLED = 2;
}

// Response message for a payment status synchronization
message PaymentServiceGetResponse {
  // Identification
  string connector_transaction_id = 1;
  optional string merchant_transaction_id = 28;

  // Status Information
  PaymentStatus status = 2;
  optional ErrorInfo error = 3;
  uint32 status_code = 4;
  map<string, string> response_headers = 5;

  // Transaction Details
  optional MandateReference mandate_reference = 6 [deprecated = true]; // use mandate_reference_details instead (will be removed in a future release)
  optional string network_transaction_id = 7;
  // A scheme-generated reference that Mastercard intends to use for tracking and linking transactions across the ecosystem.
  // Distinct from network_transaction_id.
  optional string network_txn_link_id = 31;

  // Payment Details
  optional Money amount = 8;
  optional int64 captured_amount = 9; // Captured amount in minor currency units
  optional PaymentMethodType payment_method_type = 10;
  optional CaptureMethod capture_method = 11;
  optional AuthenticationType auth_type = 12;

  // Timestamps
  optional int64 created_at = 13;
  optional int64 updated_at = 14;
  optional int64 authorized_at = 15;
  optional int64 captured_at = 16;
  // Additional Context
  optional string customer_name = 17;
  optional string email = 18;
  optional string connector_customer_id = 19;
  optional string merchant_order_id = 20;
  optional SecretString metadata = 21; // Additional metadata from the connector
  optional ConnectorResponseData connector_response = 22;

  // State Information
  optional ConnectorState state = 23;

  // Raw Response/Request for debugging
  optional SecretString raw_connector_response = 24;
  optional SecretString raw_connector_request = 25;

  // Redirection and Transaction Details
  optional RedirectForm redirection_data = 26;

  // Capability Flags
  optional bool incremental_authorization_allowed = 27;
  // Payment method updates
  optional PaymentMethodUpdate payment_method_update = 29; // Updated payment method details, if present

  optional string sender_payment_instrument_id = 30;

  // Split payment response data from connector
  optional ConnectorSplitResponseData splits = 32;

  optional SecretString connector_feature_data = 33;
  // Settlement phase reported by the connector. See SettlementStatus for the
  // per-value semantics. Absent when the connector doesn't distinguish phases.
  optional SettlementStatus settlement_status = 34;
  

  // Mandate reference details returned by the connector for future recurring payments.
  optional MandateReferenceDetails mandate_reference_details = 35;
  // The connector's reported status (code/message/reason).
  optional RawConnectorStatus raw_connector_status = 36;

  // Another reference for the connector's transaction, returned in the connector's response.
  // Distinct from connector_transaction_id — e.g. Stripe charge ID (ch_xxx), order codes, invoice numbers.
  optional string connector_reference_id = 37;
}

// Request message for voiding a payment
message PaymentServiceVoidRequest {
  // Identification
  optional string merchant_void_id = 1;
  string connector_transaction_id = 2;

  // Void Details
  optional string cancellation_reason = 3;
  optional bool all_keys_required = 4;

  // Browser Information
  optional BrowserInformation browser_info = 5;
  // Amount Information
  optional Money amount = 6;

  optional SecretString metadata = 7; // Additional metadata for the connector
  optional SecretString connector_feature_data =
      8; // Connector-specific metadata for the transaction

  // State Information
  optional ConnectorState state = 9;

  // Environment Configuration
  optional bool test_mode = 10;
  // Additional Context
  optional string merchant_order_id = 11;

  // Request ID generated by the caller system for payment gateway requests.
  // Required by some connectors that demand a per-request idempotency token.
  optional string merchant_request_id = 12;

  // Split payment configuration (platform fees, transfers, etc.)
  optional SplitPaymentsDetails split_payments = 13;
}

// Response message for a payment void operation
message PaymentServiceVoidResponse {
  // Identification
  string connector_transaction_id = 1;

  // Status Information
  PaymentStatus status = 2;
  optional ErrorInfo error = 3;
  uint32 status_code = 4;
  map<string, string> response_headers = 5;

  // Reference
  optional string merchant_void_id = 6;
  // State Information
  optional ConnectorState state = 7;

  // Raw Request for debugging
  optional SecretString raw_connector_request = 8;

  // Mandate Details
  optional MandateReference mandate_reference = 9 [deprecated = true]; // use mandate_reference_details instead (will be removed in a future release)

  // Authorization Details
  optional bool incremental_authorization_allowed = 10;

  optional SecretString connector_feature_data =
      11; // Connector-specific metadata for the transaction

  // Split payment response data from connector
  optional ConnectorSplitResponseData splits = 12;

  // Raw Response/Request for debugging
  optional SecretString raw_connector_response = 13;

  // Mandate reference details returned by the connector for future recurring payments.
  optional MandateReferenceDetails mandate_reference_details = 14;
  // The connector's reported status (code/message/reason).
  optional RawConnectorStatus raw_connector_status = 15;

  // Another reference for the connector's transaction, returned in the connector's response.
  // Distinct from connector_transaction_id — e.g. Stripe charge ID (ch_xxx), order codes, invoice numbers.
  optional string connector_reference_id = 16;
}

// Request message for reversing a captured payment if not yet settled (similar
// to void but for post-capture transactions)
message PaymentServiceReverseRequest {
  // Identification
  optional string merchant_reverse_id = 1;
  string connector_transaction_id = 2;

  // Reverse Details
  optional string cancellation_reason = 3;
  optional bool all_keys_required = 4;

  // Browser Information
  optional BrowserInformation browser_info = 5;

  optional SecretString metadata = 6; // Additional metadata for the connector
  optional SecretString connector_feature_data =
      7; // Connector-specific metadata for the transaction

  // Request ID generated by the caller system for payment gateway requests.
  // Required by some connectors that demand a per-request idempotency token.
  optional string merchant_request_id = 8;
}

// Response message for reversing a captured payment if not yet settled (similar
// to void but for post-capture transactions)
message PaymentServiceReverseResponse {
  // Identification
  string connector_transaction_id = 1;

  // Status Information
  PaymentStatus status = 2;
  optional ErrorInfo error = 3;
  uint32 status_code = 4;
  map<string, string> response_headers = 5;

  // Reference
  optional string merchant_reverse_id = 6;

  // Raw Request and Response for debugging
  optional SecretString raw_connector_request = 7;
  optional SecretString raw_connector_response = 8;

  // The connector's reported status for this response.
  optional RawConnectorStatus raw_connector_status = 9;

  // Another reference for the connector's transaction, returned in the connector's response.
  // Distinct from connector_transaction_id — e.g. Stripe charge ID (ch_xxx), order codes, invoice numbers.
  optional string connector_reference_id = 10;
}

// Request message for creating an access token
message MerchantAuthenticationServiceCreateServerAuthenticationTokenRequest {
  optional string merchant_access_token_id = 1;
  Connector connector = 2; // The connector to create the access token for

  optional SecretString metadata = 3; // Additional metadata for the connector
  optional SecretString connector_feature_data =
      4; // Connector-specific metadata for the transaction

  // Environment Configuration
  optional bool test_mode =
      5; // A boolean value to indicate if the connector is in Test mode

  // Per-request idempotency / correlation token propagated from the parent composite request.
  optional string merchant_request_id = 6;
}

// Response message for creating an access token
message MerchantAuthenticationServiceCreateServerAuthenticationTokenResponse {
  SecretString access_token = 1;  // The access token string
  optional string token_type = 2; // Token type (e.g., "Bearer", "Basic")
  optional int64 expires_in_seconds =
      3; // Expiration timestamp of the token (seconds since epoch)
  OperationStatus status = 4; // Status of the access token creation attempt
  optional ErrorInfo error = 5;
  uint32 status_code = 6; // HTTP status code from the connector
  optional string merchant_access_token_id = 7;
}

// Request message for creating a connector session
message MerchantAuthenticationServiceCreateServerSessionAuthenticationTokenRequest {
  // Infrastructure (about the session itself)
  optional string merchant_server_session_id = 1;
  optional SecretString connector_feature_data = 2;
  optional ConnectorState state = 3;
  optional bool test_mode = 4;

  // Domain-specific context
  oneof domain_context {
    PaymentSessionContext payment = 5;
    // PayoutSessionContext payout = 6;  // future
    // FrmSessionContext frm = 7;        // future
  }
}

// Payment-specific context for connector session creation
message PaymentSessionContext {
  Money amount = 1;
  optional SecretString metadata = 2;
  optional BrowserInformation browser_info = 3;
  optional Customer customer = 4;
  optional PaymentAddress address = 5;
}

// Response message for creating a connector session
message MerchantAuthenticationServiceCreateServerSessionAuthenticationTokenResponse {
  // Error Information
  optional ErrorInfo error = 1;
  uint32 status_code = 2;

  // Session Details
  string session_token = 3;
}

// Request message for SDK session
message MerchantAuthenticationServiceCreateClientAuthenticationTokenRequest {
  // Infrastructure
  string merchant_client_session_id = 1;
  optional SecretString connector_feature_data = 2;
  optional bool test_mode = 3;

  // Domain-specific context
  oneof domain_context {
    PaymentClientAuthenticationContext payment = 4;
    AuthenticatorClientAuthenticationContext authenticator = 8; // Account linking, identity verification
    // FrmClientAuthenticationContext frm = 5;      // future: device fingerprinting
    // PayoutClientAuthenticationContext payout = 6; // future: payout verification widget
  }

  // Connector-specific permissions for client authentication token
  // e.g., ["PMT_POST_Create_Single"] for GlobalPay hosted fields
  optional Permissions permissions = 7;
}

// Payment-specific context for client authentication token creation
message PaymentClientAuthenticationContext {
  Money amount = 1;
  optional int64 order_tax_amount = 2;
  optional int64 shipping_cost = 3;
  optional PaymentMethodType payment_method_type = 4;
  optional CountryAlpha2 country_alpha2_code = 5;
  optional Customer customer = 6;
  optional SecretString metadata = 7;
  optional string return_url = 8;
}

// Authenticator-specific context for client authentication token creation
message AuthenticatorClientAuthenticationContext {
  optional string return_url = 1;           // OAuth redirect URL for Link completion
  optional string webhook_url = 2;          // Webhook endpoint for events
  repeated CountryAlpha2 country_codes = 3; // ISO-3166-1 alpha-2 country codes
  optional string locale = 4;               // Locale/language preference (e.g., "en", "es", "en-US")
  optional Customer customer = 5;           // User/customer context
  optional string metadata = 6;             // Additional provider-specific config as JSON
}

// Response message for SDK session
message MerchantAuthenticationServiceCreateClientAuthenticationTokenResponse {
  ClientAuthenticationTokenData session_data = 1;
  optional ErrorInfo error = 2;
  uint32 status_code = 3;
  optional SecretString raw_connector_response = 4;
  optional SecretString raw_connector_request = 5;
}

// Request message for capturing a payment
message PaymentServiceCaptureRequest {
  // Identification
  optional string merchant_capture_id = 1;
  string connector_transaction_id = 2;

  // Capture Details
  Money amount_to_capture = 3;

  optional SecretString metadata = 4; // Additional metadata for the connector
  optional SecretString connector_feature_data =
      5; // Connector-specific metadata for the transaction

  // Multiple Capture Information
  optional MultipleCaptureRequestData multiple_capture_data = 6;
  // Browser Information
  optional BrowserInformation browser_info = 7;

  // Capture Settings
  optional CaptureMethod capture_method = 8;

  // State Information
  optional ConnectorState state = 9;

  // Environment Configuration
  optional bool test_mode = 10;

  // Additional Context
  optional string merchant_order_id = 11;

  // Request ID generated by the caller system for payment gateway requests.
  // Required by some connectors that demand a per-request idempotency token.
  optional string merchant_request_id = 12;

  // Order-level tax amount. Some processors require this again on capture so
  // settlement receives the Level II sales tax value.
  optional Money order_tax_amount = 13;

  // Split payment configuration (platform fees, transfers, etc.)
  optional SplitPaymentsDetails split_payments = 14;
}

// Response message for a payment capture operation
message PaymentServiceCaptureResponse {
  // Identification
  string connector_transaction_id = 1;

  // Status Information
  PaymentStatus status = 2;
  optional ErrorInfo error = 3;
  uint32 status_code = 4;
  map<string, string> response_headers = 5;

  // Reference
  optional string merchant_capture_id = 6;

  // State Information
  optional ConnectorState state = 7;

  // Raw Request for debugging
  optional SecretString raw_connector_request = 8;

  // Payment Details
  optional int64 captured_amount = 9; // Captured amount in minor currency units

  // Mandate Details
  MandateReference mandate_reference = 10 [deprecated = true]; // use mandate_reference_details instead (will be removed in a future release)

  // Authorization Details
  optional bool incremental_authorization_allowed = 11;

  optional SecretString connector_feature_data =
      12; // Connector-specific metadata for the transaction

  // Additional connector response details (e.g. AVS / CVV checks, auth code)
  optional ConnectorResponseData connector_response = 13;

  // Split payment response data from connector
  optional ConnectorSplitResponseData splits = 14;

  // Mandate reference details returned by the connector for future recurring payments.
  optional MandateReferenceDetails mandate_reference_details = 15;
  // The connector's reported status (code/message/reason).
  optional RawConnectorStatus raw_connector_status = 17;

  // Raw Response for debugging
  optional SecretString raw_connector_response = 16;

  // Another reference for the connector's transaction, returned in the connector's response.
  // Distinct from connector_transaction_id — e.g. Stripe charge ID (ch_xxx), order codes, invoice numbers.
  optional string connector_reference_id = 18;
}

// Request message for creating an order
message PaymentServiceCreateOrderRequest {
  // Identification
  optional string merchant_order_id = 1;

  // Amount Information
  Money amount = 2;

  // URLs for Redirection and Webhooks
  optional string webhook_url = 3;

  optional SecretString metadata = 4; // Additional metadata for the connector
  optional SecretString connector_feature_data =
      5; // Connector-specific metadata for the transaction

  // State Information
  optional ConnectorState state = 6;

  // Environment Configuration
  optional bool test_mode = 7;

  // Payment Method Type
  optional PaymentMethodType payment_method_type =
      8; // The type of payment method (e.g., apple_pay, google_pay)

  // Order line items. Required by some connectors (e.g. Airwallex PayLater /
  // Klarna) when creating the order/payment-intent.
  repeated OrderDetailsWithAmount order_details = 9;
}

// Response message for create order operation
message PaymentServiceCreateOrderResponse {
  // Identification
  optional string connector_order_id =
      1; // Identifier for the create order response

  // Status Information
  PaymentStatus status = 2; // Status of the order creation attempt
  optional ErrorInfo error = 3;
  uint32 status_code = 4;
  map<string, string> response_headers = 5;

  // Reference
  optional string merchant_order_id = 6;

  // Raw Request/Response for debugging
  optional SecretString raw_connector_request = 7;
  optional SecretString raw_connector_response = 8;

  // SDK Session Data
  optional ClientAuthenticationTokenData session_data =
      9; // SDK session data for wallets (Apple Pay, Google Pay) and other SDK types

  // The connector's reported status for this response.
  optional RawConnectorStatus raw_connector_status = 10;
}

// Request message for processing a refund
message PaymentServiceRefundRequest {
  // Identification
  optional string merchant_refund_id = 1;
  string connector_transaction_id = 2;

  // Amount Information
  int64 payment_amount = 3;
  Money refund_amount = 4;

  // Refund Context
  optional string reason = 5;              // Reason for the refund
  optional string webhook_url = 6;         // URL for webhook notifications
  optional string merchant_account_id = 7; // Merchant account ID for the refund
  optional CaptureMethod capture_method =
      8; // Capture method related to the original payment

  optional SecretString metadata = 9; // Metadata specific to the connector
  optional SecretString refund_metadata = 10; // Metadata specific to the refund
  optional SecretString connector_feature_data =
      11; // Connector-specific metadata for the transaction

  // Browser Information
  optional BrowserInformation browser_info =
      12; // Browser information, if relevant
  // State Information
  optional ConnectorState state = 13; // State data for access token storage and
                                      // other connector-specific state

  // Environment Configuration
  optional bool test_mode =
      14; // A boolean value to indicate if the connector is in Test mode

  // Payment Method Type
  optional PaymentMethodType payment_method_type =
      15; // Indicates the sub type of payment method. (e.g., card,
          // bank_redirect, bank_transfer)
  optional string customer_id = 16; // Merchant's customer ID

  // Request ID generated by the caller system for payment gateway requests.
  // Required by some connectors that demand a per-request idempotency token.
  optional string merchant_request_id = 17;

  // Connector-side identifier for the original payment that this refund targets.  
  optional string connector_order_id = 18;

  // Optional typed payment method (e.g. wallet number for direct-wallet refunds).
  optional PaymentMethod payment_method = 19;

  // Split refund data for platform fee reversals and transfers
  optional SplitRefundsDetails split_refunds = 20;
}

// Response message for a refund operation (unified for both Create and Get)
message RefundResponse {
  // Identification
  optional string merchant_refund_id =
      1;                          // Identifier for the synchronized resource
  string connector_refund_id = 2; // Connector's ID for the refund

  // Status Information
  RefundStatus status = 3; // Current status of the refund
  optional ErrorInfo error = 4;
  uint32 status_code = 5; // HTTP status code from the connector
  map<string, string> response_headers =
      6; // Optional HTTP response headers from the connector

  // Refund Details
  optional Money refund_amount = 7;
  optional int64 payment_amount = 8;
  optional string refund_reason = 9; // Reason for the refund

  // Timestamps
  optional int64 created_at = 10; // Unix timestamp when the refund was created
  optional int64 updated_at =
      11; // Unix timestamp when the refund was last updated
  optional int64 processed_at =
      12; // Unix timestamp when the refund was processed

  // Additional Context
  optional string customer_name = 13; // Name of the customer
  optional SecretString email = 14;   // Email address of the customer
  optional string merchant_order_id = 15;
  optional SecretString metadata = 16;
  optional SecretString refund_metadata =
      17; // Refund-specific metadata from the connector
  optional string connector_transaction_id = 18;
  optional SecretString acquirer_reference_number =
      19; // Acquirer reference number for the refund, if provided by the
          // connector
  // State Information
  optional ConnectorState state = 20;

  // Raw Response/Request for debugging
  optional SecretString raw_connector_response = 21;
  optional SecretString raw_connector_request = 22;

  // Connector/domain state metadata to persist across calls.
  // For refund-reverse, carries the underlying TSYS void status while the
  // user-facing `status` field remains `RefundSuccess`.
  optional SecretString state_metadata = 23;

  // Merchant's reference for the original payment/transaction the refund
  // belongs to
  optional string merchant_transaction_id = 24;
  // The connector's reported status (code/message/reason).
  optional RawConnectorStatus raw_connector_status = 25;

  // Another reference for the connector's transaction, returned in the connector's response.
  // Distinct from connector_refund_id — e.g. secondary refund references, invoice numbers.
  optional string connector_reference_id = 26;
}

// Request message for voiding/reversing a refund before settlement.
message RefundServiceVoidPostRefundRequest {
  // Identification
  optional string merchant_refund_id = 1;
  string connector_refund_id = 2;

  // Reverse Details
  optional string cancellation_reason = 4;

  // Browser Information
  optional BrowserInformation browser_info = 5;

  optional SecretString refund_metadata = 6;

  // State Information
  optional ConnectorState state = 7;

  // Environment Configuration
  optional bool test_mode = 8;

  // Payment Method Type
  optional PaymentMethodType payment_method_type = 9;

  optional SecretString connector_feature_data = 10;

  // Request ID generated by the caller system for payment gateway requests.
  optional string merchant_request_id = 11;

  // Connector-side identifier for the original payment that this refund targets.
  optional string connector_order_id = 12;
}

// Request message for creating a dispute
message PaymentServiceDisputeRequest {
  // Identification
  optional string merchant_dispute_id = 1;
  string connector_transaction_id =
      2; // Transaction ID to raise the dispute for

  // State Information
  optional ConnectorState state = 4; // State data for access token storage and
                                     // other connector-specific state
}

// Response message for dispute operations (unified for both Create and Get)
message DisputeResponse {
  // Identification
  optional string connector_dispute_id =
      1; // Connector's unique identifier for the dispute
  optional string connector_transaction_id =
      2; // Transaction ID associated with the dispute

  // Status Information
  DisputeStatus dispute_status = 3;
  DisputeStage dispute_stage = 4;
  optional string connector_status_code = 5;
  optional ErrorInfo error = 6;
  uint32 status_code = 7;
  map<string, string> response_headers = 8;

  // Dispute Details
  optional Money dispute_amount = 9;
  optional int64 dispute_date = 10;  // Unix timestamp
  optional int64 service_date = 11;  // Unix timestamp
  optional int64 shipping_date = 12; // Unix timestamp
  optional int64 due_date = 13;      // Unix timestamp

  // Evidence
  repeated EvidenceDocument evidence_documents =
      14; // Collection of evidence documents submitted

  // Additional Context
  optional string dispute_reason = 15;
  optional string dispute_message = 16;

  // Reference
  optional string merchant_dispute_id = 17;

  // Raw Request for debugging
  optional SecretString raw_connector_request = 18;

  // Another reference for the connector's transaction, returned in the connector's response.
  optional string connector_reference_id = 19;
}

// Request message for setting up a mandate
message PaymentServiceSetupRecurringRequest {
  // Identification
  string merchant_recurring_payment_id = 1;

  // Mandate Details
  Money amount = 2;
  PaymentMethod payment_method = 3;

  optional Customer customer = 4;
  // Address Information
  PaymentAddress address = 5;

  // Authentication Details
  AuthenticationType auth_type = 6; // Type of authentication to be used
  bool enrolled_for_3ds =
      7; // Indicates if the customer is enrolled for 3D Secure
  optional AuthenticationData authentication_data =
      8; // Additional authentication data

  optional SecretString metadata = 9; // Additional metadata for the connector
  optional SecretString connector_feature_data =
      10; // Connector-specific metadata for the transaction

  // URLs for Redirection and Webhooks
  optional string return_url = 11;             // URL to redirect after setup
  optional string webhook_url = 12;            // URL for webhook notifications
  optional string complete_authorize_url = 13; // URL to complete authorization

  // Session and Token Information
  optional string session_token = 14; // Session token, if applicable

  // Order Details
  optional int64 order_tax_amount =
      15; // Tax amount, if an initial payment is part of setup
  optional string order_category =
      16; // Category of the order/service related to the mandate
  optional string merchant_order_id = 17; // Merchant's internal reference ID
  optional int64 shipping_cost =
      18; // Shipping cost, if an initial payment is part of setup

  // Behavioral Flags and Preferences
  optional FutureUsage setup_future_usage =
      19;                         // Indicates future usage intention
  optional bool off_session = 20; // Indicates if off-session process
  bool request_incremental_authorization =
      21; // Indicates if incremental authorization is requested
  optional bool request_extended_authorization =
      22; // Indicates if extended authorization is requested
  optional bool enable_partial_authorization =
      23; // Indicates if partial authorization is enabled

  // Contextual Information
  optional CustomerAcceptance customer_acceptance =
      24; // Details of customer acceptance
  optional BrowserInformation browser_info =
      25; // Information about the customer's browser
  optional PaymentExperience payment_experience =
      26; // Preferred payment experience
  optional PaymentChannel payment_channel =
      27; // Describes the channel through which the payment was initiated

  // Billing Descriptor
  optional BillingDescriptor billing_descriptor =
      28; // Billing Descriptor information to be sent to the payment gateway
  // State Information
  optional ConnectorState state = 29; // State data for access token storage and
                                      // other connector-specific state

  // Send the connector order identifier here if an order was created before
  // authorize
  optional string order_id = 31;

  // Locale Information
  optional string locale =
      32; // Locale/language preference for the shopper (e.g., "en-US")
  // Testing Data
  optional SecretString connector_testing_data =
      33; // Connector-specific testing data (JSON stringified)

  // Level 2 / Level 3 data for enhanced payment processing
  optional L2L3Data l2_l3_data = 34;

  // Mandate setup details
  optional SetupMandateDetails setup_mandate_details = 35;

  // MIT Category — for CIT (this SetupRecurring request) it signals the
  // future intended MIT type (e.g. Recurring vs Installment), so connectors
  // can emit the correct CIT-side credential-on-file intent codes.
  optional MitCategory mit_category = 36;

  // Partner / merchant application identifiers initiating the request.
  optional PartnerMerchantIdentifierDetails partner_merchant_identifier_details = 37;
}

// Response message for a mandate setup operation
message PaymentServiceSetupRecurringResponse {
  // Identification
  optional string connector_recurring_payment_id =
      1; // Identifier for the mandate registration

  // Status Information
  PaymentStatus status = 2; // Status of the mandate setup attempt (using
                            // PaymentStatus with mandate values)
  optional ErrorInfo error = 3;
  uint32 status_code = 4; // HTTP status code from the connector
  map<string, string> response_headers =
      5; // Optional HTTP response headers from the connector

  // Mandate Details
  MandateReference mandate_reference = 6 [deprecated = true]; // use mandate_reference_details instead (will be removed in a future release)

  // Redirection and Transaction Details
  optional RedirectForm redirection_data =
      7; // Data for redirecting the customer's browser
  optional string network_transaction_id =
      8; // Renamed from network_transaction_id
  string merchant_recurring_payment_id = 9;
  optional ConnectorResponseData connector_response =
      10; // Various data regarding the response from connector

  // Authorization Details
  optional bool incremental_authorization_allowed =
      11; // Indicates if incremental authorization is allowed

  // Captured Amount Details
  optional int64 captured_amount =
      12; // Captured amount in minor currency units

  // State Information
  optional ConnectorState state = 13; // State data for access token storage and
                                      // other connector-specific state

  // Raw Request for debugging
  optional SecretString raw_connector_request =
      14; // Raw request to the connector for debugging
  optional SecretString connector_feature_data =
      15; // Connector-specific metadata for the transaction

  // Split payment response data from connector
  optional ConnectorSplitResponseData splits = 16;

  // Mandate reference details returned by the connector for future recurring payments.
  optional MandateReferenceDetails mandate_reference_details = 17;
  // The connector's reported status (code/message/reason).
  optional RawConnectorStatus raw_connector_status = 19;

  // Raw Response for debugging
  optional SecretString raw_connector_response = 18;
}

// Request message for repeat payment (MIT - Merchant Initiated Transaction)
message RecurringPaymentServiceChargeRequest {
  // Identification
  optional string merchant_charge_id = 1; // Reference ID for tracking

  // Mandate Information (for MIT)
  optional MandateReference connector_recurring_payment_id =
      2; // Reference to existing mandate

  // Amount Information
  Money amount = 3;

  // Optional payment Method Information (for network transaction flows)
  optional PaymentMethod payment_method = 4;

  // Optional fields
  optional string merchant_order_id = 5;
  optional SecretString metadata = 6; // Additional metadata for the connector
  optional SecretString connector_feature_data =
      7; // Connector-specific metadata for the transaction
  optional string webhook_url = 8;
  optional string return_url = 9;
  optional string description = 10;

  // Address Information
  optional PaymentAddress address = 11;

  // Capture Settings
  optional CaptureMethod capture_method = 12;

  // Customer Information
  optional SecretString email = 13;
  optional string connector_customer_id = 14;

  // Browser Information
  optional BrowserInformation browser_info = 15;

  optional bool test_mode = 16;
  optional PaymentMethodType payment_method_type = 17;

  // Merchant Account Configuration
  optional SecretString merchant_account_id = 18;
  optional Currency merchant_configured_currency = 19;

  // Behavioral Flags and Preferences
  optional bool off_session = 20;
  optional bool enable_partial_authorization = 21;

  // State Information
  optional ConnectorState state = 22;

  // Original Payment Details (for reference and validation in MIT flows)
  optional Money original_payment_authorized_amount = 23;

  // Shipping Cost
  optional int64 shipping_cost =
      24; // Shipping cost in minor units (e.g., cents)
  // Billing Descriptor
  optional BillingDescriptor billing_descriptor = 25;

  // MIT Category
  optional MitCategory mit_category = 26;

  // Authentication Data
  optional AuthenticationData authentication_data = 27;

  // Locale Information
  optional string locale = 28;

  // Testing Data
  optional SecretString connector_testing_data = 29;

  // Customer Information
  optional Customer customer = 30;

  // Level 2 / Level 3 data for enhanced payment processing
  optional L2L3Data l2_l3_data = 31;

  optional CustomerDocumentDetails customer_document_details =
      32; // Customer identification document

  // Additional payment data for various payment methods
  optional AdditionalPaymentData additional_payment_data = 33;

  // Split payment configuration (platform fees, transfers, etc.)
  optional SplitPaymentsDetails split_payments = 34;

  optional PartnerMerchantIdentifierDetails partner_merchant_identifier_details = 35;

  optional AuthenticationType auth_type = 36;
  
  optional string complete_authorize_url = 37;

  // Channel through which the repeat payment was initiated.
  optional PaymentChannel payment_channel = 38;
}

// Response message for repeat payment operation
message RecurringPaymentServiceChargeResponse {
  // Identification
  optional string connector_transaction_id = 1;

  // Status Information
  PaymentStatus status = 2;
  optional ErrorInfo error = 3;
  uint32 status_code = 4;
  map<string, string> response_headers = 5;

  optional SecretString connector_feature_data = 6;

  // Transaction Details
  optional string network_transaction_id = 7;
  optional string merchant_charge_id = 8;
  optional MandateReference mandate_reference = 9 [deprecated = true]; // use mandate_reference_details instead (will be removed in a future release)

  // State Information
  optional ConnectorState state = 10;

  // Raw Response/Request for debugging
  optional SecretString raw_connector_response = 11;
  optional SecretString raw_connector_request = 12;

  // Payment Details
  optional int64 captured_amount =
      13; // Captured amount in minor currency units
  optional ConnectorResponseData connector_response = 14;

  // Authorization Details
  optional bool incremental_authorization_allowed = 15;

  // Split payment response data from connector
  optional ConnectorSplitResponseData splits = 16;

  // Mandate reference details returned by the connector for future recurring payments.
  optional MandateReferenceDetails mandate_reference_details = 17;

  // Redirection data (e.g. 3DS challenge or buyer-approval URL) for wallet-MIT /
  // repeat payments that require buyer interaction. Mirrors
  // PaymentServiceAuthorizeResponse.redirection_data so a redirected recurring
  // charge can surface a next_action to the buyer.
  optional RedirectForm redirection_data = 18;

  // The connector's reported status (code/message/reason).
  optional RawConnectorStatus raw_connector_status = 19;

  // A scheme-generated reference that Mastercard intends to use for tracking and linking transactions across the ecosystem.
  // Distinct from network_transaction_id.
  optional string network_txn_link_id = 20;
}

// Request message for a mandate revoke operation
message RecurringPaymentServiceRevokeRequest {
  // Identification
  optional string merchant_revoke_id = 1;

  // Mandate Details
  string mandate_id = 2;
  optional string connector_mandate_id = 3;
}

// Response message for a mandate revoke operation
message RecurringPaymentServiceRevokeResponse {
  // Status Information
  MandateStatus status = 1;
  optional ErrorInfo error = 2;
  uint32 status_code = 3;
  map<string, string> response_headers = 4;

  // Transaction Details
  optional string network_transaction_id = 5;
  optional string merchant_revoke_id = 6;

  // Raw Response/Request for debugging
  optional SecretString raw_connector_response = 7;
  optional SecretString raw_connector_request = 8;
}

// ============================================================================
// 3DS AUTHENTICATION FLOW MESSAGES
// ============================================================================

// Request message for pre-authentication step
message PaymentMethodAuthenticationServicePreAuthenticateRequest {
  // Payment Identification
  optional string merchant_order_id = 1;

  // Amount Information
  Money amount = 2;

  // Payment Method
  PaymentMethod payment_method = 3;

  // Customer Information
  optional Customer customer = 4;

  // Address Information
  PaymentAddress address = 5;
  // Authentication Details
  bool enrolled_for_3ds = 6;

  optional SecretString metadata = 7; // Additional metadata for the connector
  optional SecretString connector_feature_data =
      8; // Connector-specific metadata for the transaction

  // URLs for Redirection
  optional string return_url = 9;
  optional string continue_redirection_url = 10;
  // Contextual Information
  optional BrowserInformation browser_info = 11;
  // State Information
  optional ConnectorState state = 12;

  // Capture Settings
  optional CaptureMethod capture_method = 13;

  // Description
  optional string description = 14;

  // Merchant transaction identifier.
  optional string merchant_transaction_id = 15;
}

// Response message for pre-authentication step
message PaymentMethodAuthenticationServicePreAuthenticateResponse {
  // Identification
  optional string connector_transaction_id = 1;

  // Status Information
  PaymentStatus status = 2;
  optional ErrorInfo error = 3;
  uint32 status_code = 4;
  map<string, string> response_headers = 5;

  // Redirection and Transaction Details
  optional RedirectForm redirection_data = 6;
  optional string network_transaction_id = 7;
  optional string merchant_order_id = 8;

  optional SecretString connector_feature_data =
      9; // Connector-specific metadata for the transaction

  // State Information
  optional ConnectorState state = 10;

  // Raw Response for debugging
  optional SecretString raw_connector_response = 11;
  // Authentication Results
  optional AuthenticationData authentication_data = 12;
}

// Request message for authentication step
message PaymentMethodAuthenticationServiceAuthenticateRequest {
  // Payment Identification
  optional string merchant_order_id = 1;

  // Amount Information
  Money amount = 2;

  // Payment Method
  PaymentMethod payment_method = 3;

  // Customer Information
  optional Customer customer = 4;

  // Address Information
  PaymentAddress address = 5;

  // Authentication Details
  optional AuthenticationData authentication_data = 6;

  optional SecretString metadata = 7; // Additional metadata for the connector
  optional SecretString connector_feature_data =
      8; // Connector-specific metadata for the transaction

  // URLs for Redirection
  optional string return_url = 9;
  optional string continue_redirection_url = 10;

  // Contextual Information
  optional BrowserInformation browser_info = 11;

  // State Information
  optional ConnectorState state = 12;

  // Redirection Information after DDC step
  optional RedirectionResponse redirection_response = 13;

  // Capture Settings
  optional CaptureMethod capture_method = 14;

  // URL for webhook notifications
  optional string webhook_url = 15;

  // Domain-specific data (e.g. student fields for tuition payments)
  optional DomainData domain_data = 16;
}

// Response message for authentication step
message PaymentMethodAuthenticationServiceAuthenticateResponse {
  // Identification
  optional string connector_transaction_id = 1;

  // Status Information
  PaymentStatus status = 2;
  optional ErrorInfo error = 3;
  uint32 status_code = 4;
  map<string, string> response_headers = 5;

  // Redirection and Transaction Details
  optional RedirectForm redirection_data = 6;
  optional string network_transaction_id = 7;
  optional string merchant_order_id = 8;

  // Authentication Results
  optional AuthenticationData authentication_data = 9;

  optional SecretString connector_feature_data = 10;

  // State Information
  optional ConnectorState state = 11;

  // Raw Response for debugging
  optional SecretString raw_connector_response = 12;

  // The connector's reported status (code/message/reason).
  optional RawConnectorStatus raw_connector_status = 13;
}

// Request message for post-authentication step
message PaymentMethodAuthenticationServicePostAuthenticateRequest {
  // Payment Identification
  optional string merchant_order_id = 1;

  // Amount Information
  Money amount = 2;

  // Payment Method
  PaymentMethod payment_method = 3;

  // Customer Information
  optional Customer customer = 4;
  // Address Information
  PaymentAddress address = 5;

  // Authentication Details
  optional AuthenticationData authentication_data = 6;
  optional string connector_order_reference_id = 7;

  optional SecretString metadata = 8;
  optional SecretString connector_feature_data =
      9; // Connector-specific metadata for the transaction

  // URLs for Redirection
  optional string return_url = 10;
  optional string continue_redirection_url = 11;
  // Contextual Information
  optional BrowserInformation browser_info = 12;
  // State Information
  optional ConnectorState state = 13;

  // Redirection Information after DDC step
  optional RedirectionResponse redirection_response = 14;
  
  // Capture Settings
  optional CaptureMethod capture_method = 15;
}

// Response message for post-authentication step
message PaymentMethodAuthenticationServicePostAuthenticateResponse {
  // Identification
  optional string connector_transaction_id = 1;

  // Status Information
  PaymentStatus status = 2;
  optional ErrorInfo error = 3;
  uint32 status_code = 4;
  map<string, string> response_headers = 5;

  // Redirection and Transaction Details
  optional RedirectForm redirection_data = 6;
  optional string network_transaction_id = 7;
  optional string merchant_order_id = 8;

  // Authentication Results
  optional AuthenticationData authentication_data = 9;

  // Authorization Details
  optional bool incremental_authorization_allowed = 10;

  optional SecretString connector_feature_data = 11;

  // State Information
  optional ConnectorState state = 12;

  // Raw Response for debugging
  optional SecretString raw_connector_response = 13;

  // The connector's reported status for this response.
  optional RawConnectorStatus raw_connector_status = 14;
}

// Request message for incremental authorization
message PaymentServiceIncrementalAuthorizationRequest {
  // Identification
  optional string merchant_authorization_id = 1;
  string connector_transaction_id = 2;

  // Amount Information
  Money amount = 3; // new amount to be authorized (in minor currency units)

  // Optional Fields
  optional string reason = 4;

  optional SecretString connector_feature_data = 5;

  // State Information
  optional ConnectorState state = 6;
}

// Response message for incremental authorization
message PaymentServiceIncrementalAuthorizationResponse {
  // Identification
  optional string connector_authorization_id = 1;

  // Status Information
  AuthorizationStatus status = 2;
  optional ErrorInfo error = 3;
  uint32 status_code = 4;
  map<string, string> response_headers = 5;

  // State Information
  optional ConnectorState state = 6;

  // Raw Request and Response for debugging
  optional SecretString raw_connector_request = 7;
  optional SecretString raw_connector_response = 8;
}

// IDs extracted from a payment webhook.
// connector_transaction_id: connector-assigned ID (e.g. Stripe "pi_xxx", Adyen "pspReference" on capture events).
// merchant_transaction_id:  merchant reference echoed by the connector (e.g. Adyen "merchantReference"
//                           on transaction events, Stripe metadata.order_id).
// Exactly one is expected to be present; both may be present when the connector echoes both.
message PaymentEventReference {
  optional string connector_transaction_id = 1;
  optional string merchant_transaction_id  = 2;
}

// IDs extracted from a refund webhook.
// connector_refund_id:      connector-assigned refund ID (e.g. PayPal refund resource.id).
// merchant_refund_id:       merchant reference echoed for the refund (e.g. Adyen "merchantReference"
//                           on refund events).
// connector_transaction_id: parent payment ID, if the connector includes it.
message RefundEventReference {
  optional string connector_refund_id      = 1;
  optional string merchant_refund_id       = 2;
  optional string connector_transaction_id = 3;  // Parent payment ID, if present.
  optional string merchant_transaction_id  = 4;
}

// IDs extracted from a dispute webhook.
// Connectors typically reference disputes via the parent payment's connector_transaction_id
// (e.g. Adyen originalReference, PayPal seller_transaction_id).
// connector_dispute_id is populated when the connector issues a dispute-specific identifier.
message DisputeEventReference {
  optional string connector_dispute_id     = 1;
  optional string connector_transaction_id = 2;  // Parent payment ID.
}

// IDs extracted from a mandate webhook.
message MandateEventReference {
  optional string connector_mandate_id = 1;
  optional string merchant_transaction_id = 2;
}

// IDs extracted from a payout webhook.
// connector_payout_id: connector-assigned payout ID (e.g. PayPal payout_batch_id).
// merchant_payout_id:  merchant reference echoed by the connector (e.g. Adyen "merchantReference"
//                      on payout events).
message PayoutEventReference {
  optional string connector_payout_id = 1;
  optional string merchant_payout_id  = 2;
}

// Resource reference extracted from a webhook payload.
// The oneof variant identifies the entity class. Unset for non-resource events (e.g. account/capability notifications).
message EventReference {
  oneof resource {
    PaymentEventReference payment = 1;
    RefundEventReference  refund  = 2;
    DisputeEventReference dispute = 3;
    MandateEventReference mandate = 4;
    PayoutEventReference  payout  = 5;
  }
}

// Request for EventService.ParseEvent. No credentials required.
message EventServiceParseRequest {
  RequestDetails request_details = 1;
}

// Response for EventService.ParseEvent.
message EventServiceParseResponse {
  optional EventReference   reference  = 1;  // Absent for non-resource events (e.g. account/capability notifications).
  optional WebhookEventType event_type = 2;
}

// Business context the caller passes back to fill UCS's stateless gap.
// UCS is stateless — it cannot retrieve the original request parameters.
// Pass back the fields from your original request that correspond to the
// EventReference arm returned by ParseEvent.
// UCS returns INVALID_ARGUMENT with an actionable message if a required field
// is missing for the connector being handled.
message EventContext {
  oneof event_context {
    PaymentEventContext  payment  = 1;
    RefundEventContext   refund   = 2;
    DisputeEventContext  dispute  = 3;
    MandateEventContext  mandate  = 4;
    PayoutEventContext   payout   = 5;
  }
}

// Context from the original PaymentServiceAuthorizeRequest.
// Required by connectors whose webhook payloads do not unambiguously distinguish
// AUTHORIZED from CAPTURED (e.g. Noon, Fiuu).
message PaymentEventContext {
  // From original PaymentServiceAuthorizeRequest.capture_method.
  optional CaptureMethod capture_method = 1;
}

// Context from the original RefundServiceRefundRequest.
// Reserved for future use — no connectors currently require it.
message RefundEventContext {
}

// Context from the original dispute flow.
// Reserved for future use — no connectors currently require it.
message DisputeEventContext {
}

// Context from the original mandate flow.
// Reserved for future use — no connectors currently require it.
message MandateEventContext {
}

// Context from the original mandate flow.
// Reserved for future use — no connectors currently require it.
message PayoutEventContext {
}

// Request for EventService.HandleEvent.
// Supply event_context for connectors that require it (see connector integration guide).
// access_token required for connectors that verify webhooks via an outbound API call
// (e.g. PayPal POST /v1/notifications/verify-webhook-signature requires OAuth2).
message EventServiceHandleRequest {
  // Caller-supplied correlation key, echoed in the response. Not used by UCS for processing.
  optional string         merchant_event_id = 1;
  RequestDetails          request_details   = 2;
  optional WebhookSecrets webhook_secrets   = 3;
  optional AccessToken    access_token      = 4;
  optional EventContext   event_context     = 5;
}

// Request message for VerifyRedirectResponse
message PaymentServiceVerifyRedirectResponseRequest {
  // Identification
  optional string merchant_order_id = 1;

  // Request Details
  RequestDetails request_details = 2;

  // Security
  optional RedirectResponseSecrets redirect_response_secrets = 3;
}

// Response message for VerifyRedirectResponse
message PaymentServiceVerifyRedirectResponseResponse {
  // Verification
  bool source_verified = 1;

  // Identification
  optional string connector_transaction_id = 2;

  // Response Amount Information
  optional Money response_amount = 3;

  // Reference
  optional string merchant_order_id = 4;

  // Status Information
  optional PaymentStatus status = 5;
  optional ErrorInfo error = 6;

  // Raw Response
  optional SecretString raw_connector_response = 7;
}

// ============================================================================
// REFUND SERVICE MESSAGES
// ============================================================================

// Request message for synchronizing refund status
message RefundServiceGetRequest {
  // Identification
  optional string merchant_refund_id = 1;
  string connector_transaction_id = 2;
  string refund_id = 3; // Deprecated
  string connector_refund_id = 14;

  // Refund Details
  optional string refund_reason = 4;

  // Browser Information
  optional BrowserInformation browser_info = 5;

  optional SecretString refund_metadata =
      6; // Metadata specific to the refund sync

  // State Information
  optional ConnectorState state = 7;

  // Environment Configuration
  optional bool test_mode = 8;
  // Payment Method Type
  optional PaymentMethodType payment_method_type = 9;

  optional SecretString connector_feature_data = 10;

  // Amount Information
  optional Money refund_amount = 15;

  // Request ID generated by the caller system for payment gateway requests.
  // Required by some connectors that demand a per-request idempotency token.
  optional string merchant_request_id = 16;

  // Connector-side identifier for the original payment that this refund sync targets. 
  optional string connector_order_id = 17;

  // Split refund data for platform fee reversals and transfers
  optional SplitRefundsDetails split_refunds = 18;
}

// ============================================================================
// DISPUTE SERVICE MESSAGES
// ============================================================================

// Request message for submitting evidence for a dispute
message DisputeServiceSubmitEvidenceRequest {
  // Identification
  optional string merchant_dispute_id = 1;
  optional string connector_transaction_id = 2;
  string dispute_id = 3;

  // Dates
  optional int64 service_date = 4;
  optional int64 shipping_date = 5;

  // Evidence
  repeated EvidenceDocument evidence_documents =
      6; // Collection of evidence documents
}

// Response message for a submit evidence operation
message DisputeServiceSubmitEvidenceResponse {
  // Identification
  optional string dispute_id = 1;
  repeated string submitted_evidence_ids = 2;

  // Status Information
  DisputeStatus dispute_status = 3;
  optional string connector_status_code = 4;
  optional ErrorInfo error = 5;
  uint32 status_code = 6;
  map<string, string> response_headers = 7;

  // Reference
  optional string merchant_dispute_id = 8;

  // Raw Request for debugging
  optional SecretString raw_connector_request = 9;
}

// Request message for retrieving dispute information
message DisputeServiceGetRequest {
  // Identification
  optional string merchant_dispute_id = 1;
  optional string dispute_id = 2;
  string connector_dispute_id = 3;
}

// Request message for defending a dispute
message DisputeServiceDefendRequest {
  // Identification
  optional string merchant_dispute_id = 1;
  string connector_transaction_id = 2;
  string dispute_id = 3;

  // Defend Details
  optional string reason_code = 4;
}

// Response message for defending a dispute
message DisputeServiceDefendResponse {
  // Identification
  string dispute_id = 1;

  // Status Information
  DisputeStatus dispute_status = 2;
  optional string connector_status_code = 3;
  optional ErrorInfo error = 4;
  uint32 status_code = 5;
  map<string, string> response_headers = 6;

  // Reference
  optional string merchant_dispute_id = 7;

  // Raw Request for debugging
  optional SecretString raw_connector_request = 8;
}

// Request message for accepting a dispute
message DisputeServiceAcceptRequest {
  // Identification
  optional string merchant_dispute_id = 1;
  string connector_transaction_id = 2;
  string dispute_id = 3;
}

// Response message for accepting a dispute
message DisputeServiceAcceptResponse {
  // Identification
  string dispute_id = 1;

  // Status Information
  DisputeStatus dispute_status = 2;
  optional string connector_status_code = 3;
  optional ErrorInfo error = 4;
  uint32 status_code = 5;
  map<string, string> response_headers = 6;

  // Reference
  optional string merchant_dispute_id = 7;

  // Raw Request for debugging
  optional SecretString raw_connector_request = 8;
}

// ============================================================================
// ADDITIONAL REQUEST/RESPONSE MESSAGES
// ============================================================================

// ============================================================================
// PAYMENT METHOD SERVICE MESSAGES
// ============================================================================

// Request message for tokenizing a payment method
message PaymentMethodServiceTokenizeRequest {
  // Identification
  optional string merchant_payment_method_id = 1;

  // Payment Information
  Money amount = 2;
  PaymentMethod payment_method = 3;

  // Customer Information
  optional Customer customer = 4;

  // Address Information
  optional PaymentAddress address = 5;

  optional SecretString metadata = 6;
  optional SecretString connector_feature_data =
      7; // Connector-specific metadata for the transaction

  // URLs for Redirection
  optional string return_url = 8;

  // Environment Configuration
  optional bool test_mode = 9;

  // State Information
  optional ConnectorState state = 10;

  // Split payment configuration (platform fees, transfers, etc.)
  optional SplitPaymentsDetails split_payments = 11;
}

// Response message for tokenizing a payment method
message PaymentMethodServiceTokenizeResponse {
  // Token Information
  string payment_method_token = 1;

  // Error Information
  optional ErrorInfo error = 2;
  uint32 status_code = 3;
  map<string, string> response_headers = 4;

  // Reference
  optional string merchant_payment_method_id = 5;

  // State Information
  optional ConnectorState state = 6;

  optional string connector_payment_method_id = 7; // Connector-issued payment method ID
}

message PaymentMethodServiceCreateRequest {
  optional string merchant_payment_method_id = 1; // Merchant's reference ID for the payment method
  optional Customer customer = 2; // Customer information
  optional string description = 3; // Human-readable description of the payment method
  PaymentMethodType payment_method_type = 4; // PaymentMethodType enum (CARD, WALLET, UPI, etc.)
  optional ConnectorState state = 5;   // State Information (for access token)
  optional string product_id = 6; // Product or program under which the payment method exists

  optional SecretString metadata = 7; // Additional metadata for the connector
  optional SecretString connector_feature_data = 8; // Connector-specific metadata for the transaction
  optional bool test_mode = 9;
}

message PaymentMethodServiceCreateResponse {
  optional string merchant_payment_method_id = 1; // Merchant's reference ID for the payment method
  optional string connector_payment_method_id = 2; // Connector-issued payment method ID (incase of wallet_detail it is connector_wallet_id)
  
  PaymentMethodDetails payment_method_details = 3; // details of the Payment method created

  // Customer Information
  optional Customer customer = 4;
  optional Address address = 5;

  // Error Information
  optional ErrorInfo error = 6;
  uint32 status_code = 7;
  map<string, string> response_headers = 8;

  // Raw Response/Request for debugging
  optional SecretString raw_connector_response = 9;
  optional SecretString raw_connector_request = 10;
}

message PaymentMethodServiceGetRequest {
  optional string merchant_payment_method_id = 1; // Merchant's reference ID for the payment method
  optional string connector_payment_method_id = 2; // Connector-issued payment method ID (incase of wallet_detail it is connector_wallet_id)
  
  // Customer Information
  optional Customer customer = 3;
  optional ConnectorState state = 4;   // State Information (for access token)
  optional SecretString connector_feature_data = 5; // Connector-specific metadata for the transaction
  optional SecretString metadata = 6; // Additional metadata for the connector
  optional bool test_mode = 7;
  PaymentMethodType payment_method_type = 8; // PaymentMethodType enum (CARD, WALLET, UPI, etc.)
  optional string payment_method_token = 9;  // PaymentMethod Token Information
}

message PaymentMethodServiceGetResponse {
  optional string merchant_payment_method_id = 1; // Merchant's reference ID for the payment method
  optional string connector_payment_method_id = 2; // Connector-issued payment method ID (incase of wallet_detail it is connector_wallet_id)
  
  PaymentMethodDetails payment_method_details = 3; // details of the Payment method

  // Customer Information
  optional Customer customer = 4;
  optional Address address = 5;

  // Error Information
  optional ErrorInfo error = 6;
  uint32 status_code = 7;
  map<string, string> response_headers = 8;

  // Raw Response/Request for debugging
  optional SecretString raw_connector_response = 9;
  optional SecretString raw_connector_request = 10;
}

// Refresh a stored card against the network updater.
message PaymentMethodServiceRefreshRequest {
  PaymentMethod payment_method = 1;
}

message PaymentMethodServiceRefreshResponse {
  RefreshResult result = 1;
  uint32 status_code = 2;                   // HTTP status code from the connector
  optional ErrorInfo error = 3;             // Error details if the call failed
  map<string, string> response_headers = 4; // Response headers from the connector

  // Raw Response/Request for debugging
  optional SecretString raw_connector_response = 5;
  optional SecretString raw_connector_request = 6;
}

// One arm per instrument; each carries its own outcome type.
message RefreshResult {
  oneof result {
    CardRefreshResult card = 1;
  }
}

message CardRefreshResult {
  CardRefreshOutcome outcome = 1;
  CardDetailsWithNoCvc card = 2;
}

enum CardRefreshOutcome {
  // Unmapped network code, or a failure when `error` is set. Branch on `error`.
  CARD_REFRESH_OUTCOME_UNSPECIFIED = 0;
  CARD_REFRESH_ACCOUNT_UPDATED = 1;     // Card reissued; the returned card is the new one
  CARD_REFRESH_EXPIRY_UPDATED = 2;      // Same card number, new expiry
  CARD_REFRESH_NO_CHANGE = 3;           // Stored card is current
  CARD_REFRESH_CLOSED = 4;              // Account closed; stop using the card
  CARD_REFRESH_NOT_FOUND = 5;           // No update available; card not found, or the BIN is not participating
  CARD_REFRESH_CONTACT_ISSUER = 6;      // Issuer advises contacting the cardholder
}

// Status of a recharge operation
enum RechargeStatus {
  RECHARGE_STATUS_UNSPECIFIED = 0; // Default unspecified status
  RECHARGE_SUCCESS = 1;             // Recharge completed successfully
  RECHARGE_FAILURE = 2;             // Recharge failed
  RECHARGE_PENDING = 3;             // Recharge is being processed
}

enum WalletStatus {
  WALLET_STATUS_UNSPECIFIED = 0;
  ACTIVE_WALLET = 1; // Wallet is operational and can process transactions
  INACTIVE_WALLET = 2; // Wallet is suspended or closed
}

message PaymentMethodDetails {
  oneof details {
    WalletDetails wallet = 1; // Wallet-specific details (stored value, container, or hybrid)
    BankAccountDetails bank_account = 2; // Bank account details (ACH, BACS, SEPA, EFT)
  }
}

message WalletDetails {
  string wallet_account_id = 1; // Unique wallet identifier from connector (e.g., QwikWallet number)
  optional SecretString wallet_pin = 2; // wallet PIN for authentication
  optional WalletStatus wallet_status = 3; // Current operational status (ACTIVE/INACTIVE)
  optional string wallet_holder_name = 4; // Name registered on the wallet account
  optional int64 balance = 5; // Current wallet balance in minor currency units (for stored value wallets)
  optional string product_id = 6; // Product or program identifier under which the wallet exists
  repeated WalletItem items = 7; // Payment method items stored in this wallet (for container/hybrid wallets)
}

// Status of a wallet item (payment method within a container/hybrid wallet)
enum WalletItemStatus {
  WALLET_ITEM_STATUS_UNSPECIFIED = 0; // Default unspecified status
  WALLET_ITEM_ACTIVE = 1;              // Item is active and can be used
  WALLET_ITEM_INACTIVE = 2;            // Item is inactive or suspended
  WALLET_ITEM_DEPLETED = 3;            // Item balance is fully used (for balance-bearing items)
  WALLET_ITEM_EXPIRED = 4;             // Item has expired
}

// Represents a payment method item within a container or hybrid wallet
// Examples: gift card in Amazon Pay, prepaid card in Apple Wallet, loyalty card, etc.
message WalletItem {
  // Instance-specific metadata for this item within the wallet
  string wallet_item_id = 1;                      // Unique identifier for this item within the wallet
  string product_id = 2;                   // Product or program identifier under which this item exists
  WalletItemStatus status = 3;             // Current status of this item (ACTIVE, INACTIVE, DEPLETED, EXPIRED)
  optional Money available_balance = 4;    // Remaining balance if this item is balance-bearing
  optional string expiry_date = 5;         // Expiry date in ISO 8601 format (e.g., "2026-12-31")
}

// Bank account details containing one or more accounts
message BankAccountDetails {
  repeated BankAccount accounts = 1;
}

// Individual bank account credential with routing details
message BankAccount {
  SecretString account_name = 1;                 // Account display name
  SecretString account_id = 2;                   // Unique account identifier
  optional BankType bank_type = 3;               // Account type: checking, savings
  optional BankHolderType bank_holder_type = 4;  // Bank holder type
  optional Money balance = 5;                    // Current balance
  optional Money available_balance = 6;          // Available balance
  oneof account_details {                        // Account details discriminated by region
    BankAccountDetailsAch ach = 7;               // US ACH
    BankAccountDetailsBacs bacs = 8;             // UK BACS
    BankAccountDetailsSepa sepa = 9;             // EU SEPA
  }
  optional string bank_name = 10;                // Name of the financial institution
}

// ACH bank account details (United States)
message BankAccountDetailsAch {
  SecretString account_number = 1;
  SecretString routing_number = 2;
}

// BACS bank account details (United Kingdom)
message BankAccountDetailsBacs {
  SecretString account_number = 1;
  SecretString sort_code = 2;
}

// SEPA bank account details (European Union)
message BankAccountDetailsSepa {
  SecretString iban = 1;
  SecretString bic = 2;
}

// Request message for recharging a payment method
message PaymentMethodServiceRechargeRequest {
  // Identifiers
  optional string merchant_payment_method_id = 1;  // Merchant's payment method ID (e.g., wallet number)
  optional string connector_payment_method_id = 2; // Connector's payment method ID (wallet number at connector's end)
  optional string merchant_request_id = 3;         // Request ID generated by the caller system
  optional string merchant_recharge_id = 4;        // Merchant's recharge tracking ID (invoice number or reference)
  
  // Recharge Details
  string product_id = 5;                           // Product or program under which the payment method exists
  Money amount = 6;                                // Recharge amount in minor currency units
  optional string description = 7;                 // Human-readable description or notes about the recharge
  PaymentMethodType payment_method_type = 8;       // Type of payment method (WALLET, GIFT_CARD, PREPAID_CARD, etc.)
  
  // Configuration
  optional ConnectorState state = 9;               // State information for multi-step flows (access token, session data)
  optional SecretString metadata = 10; // Additional metadata for the connector
  optional SecretString connector_feature_data = 11; // Connector-specific metadata for the transaction
  optional bool test_mode = 12;                    // Sandbox/test mode flag (true for test environment)
}

// Response message for recharging a payment method
message PaymentMethodServiceRechargeResponse {
  // Identifiers
  optional string merchant_payment_method_id = 1;  // Merchant's payment method ID
  optional string connector_payment_method_id = 2; // Connector's payment method ID
  optional string merchant_recharge_id = 3;        // Merchant's recharge tracking ID
  optional string connector_recharge_id = 4;       // Connector's recharge tracking ID (invoice number or reference)
  
  // Recharge Result
  RechargeStatus status = 5;                       // Status of the recharge operation (SUCCESS, FAILURE, PENDING)
  PaymentMethodDetails payment_method_details = 6; // Updated payment method details after recharge
  
  // Error and Debugging Information
  optional ErrorInfo error = 7;                    // Error details if the recharge failed
  uint32 status_code = 8;                          // HTTP status code from the connector
  map<string, string> response_headers = 9;        // Response headers from the connector
  optional SecretString raw_connector_response = 10; // Raw response from the connector for debugging
  optional SecretString raw_connector_request = 11;  // Raw request sent to the connector for debugging
}

// ============================================================================
// CUSTOMER SERVICE MESSAGES
// ============================================================================

// Request message for creating a customer
message CustomerServiceCreateRequest {
  // Identification
  optional string merchant_customer_id = 1;

  // Customer Information
  optional string customer_name = 2; // Name of the customer
  optional SecretString email = 3;   // Email address of the customer
  optional SecretString phone_number = 4;  // Phone number of the customer

  // Address Information
  optional PaymentAddress address = 5;

  // Additional Metadata
  optional SecretString metadata = 6; // Additional metadata for the connector
  optional SecretString connector_feature_data =
      7; // Connector-specific metadata for the transaction

  // Environment Configuration
  optional bool test_mode = 8;

  // Split payment configuration (platform fees, transfers, etc.)
  optional SplitPaymentsDetails split_payments = 9;
}

// Response message for creating a customer
message CustomerServiceCreateResponse {
  // Reference
  optional string merchant_customer_id = 1;

  // Customer Information
  string connector_customer_id = 2;

  // Error Information
  optional ErrorInfo error = 3;
  uint32 status_code = 4;
  map<string, string> response_headers = 5;
}

// Request message for getting a customer
message CustomerServiceGetRequest {
  // Identification
  optional string merchant_customer_id = 1;

  // Customer Information
  optional string connector_customer_id = 2;
  optional SecretString email = 3;         // Email address of the customer
  optional SecretString phone_number = 4;  // Phone number of the customer

  // Connector-specific metadata for the transaction (required by the generic
  // flow runner in field-probe, which injects `connector_feature_data` into
  // every probe request regardless of flow shape).
  optional SecretString connector_feature_data = 5;
}

// Outcome of a connector-side customer lookup. Explicit signal so callers
// don't have to infer presence-of-id vs absent as found-vs-not-found, which
// would silently misroute malformed responses into a duplicate CREATE.
enum CustomerLookupStatus {
  CUSTOMER_LOOKUP_STATUS_UNSPECIFIED = 0;
  CUSTOMER_LOOKUP_STATUS_FOUND = 1;
  CUSTOMER_LOOKUP_STATUS_NOT_FOUND = 2;
}

// Response message for getting a customer
message CustomerServiceGetResponse {
  // Customer Information. Absent when lookup_status is CUSTOMER_NOT_FOUND;
  // populated when lookup_status is CUSTOMER_FOUND.
  optional Customer customer = 1;

  // Error Information
  optional ErrorInfo error = 2;
  uint32 status_code = 3;
  map<string, string> response_headers = 4;

  // Reference
  optional string merchant_customer_id = 5;

  // Lookup outcome. Connectors implementing GetConnectorCustomer must set
  // this so the caller can distinguish "not found" from partially populated
  // or malformed responses.
  CustomerLookupStatus lookup_status = 6;
}

// Request message for updating a customer
message CustomerServiceUpdateRequest {
  // Identification
  optional string merchant_customer_id = 1;

  // Customer Information
  string connector_customer_id = 2;
  optional string customer_name = 3; // Name of the customer
  optional SecretString email = 4;   // Email address of the customer
  optional SecretString phone_number = 5;  // Phone number of the customer

  // Address Information
  optional PaymentAddress address = 6;

  optional SecretString metadata = 7; // Additional metadata for the connector
  optional SecretString connector_feature_data =
      8; // Connector-specific metadata for the transaction
}

// Response message for updating a customer
message CustomerServiceUpdateResponse {
  // Customer Information
  Customer customer = 1;

  // Error Information
  optional ErrorInfo error = 2;
  uint32 status_code = 3;
  map<string, string> response_headers = 4;

  // Reference
  optional string merchant_customer_id = 5;
}

// Request message for deleting a customer
message CustomerServiceDeleteRequest {
  // Identification
  optional string merchant_customer_id = 1;

  // Customer Information
  string connector_customer_id = 2;
}

// Response message for deleting a customer
message CustomerServiceDeleteResponse {
  // Error Information
  optional ErrorInfo error = 1;
  uint32 status_code = 2;
  map<string, string> response_headers = 3;

  // Reference
  optional string merchant_customer_id = 4;
}

// ============================================================================
// CONNECTOR CONFIGURATION MESSAGES
// ============================================================================

// Single field auth types
message StripeConfig {
  SecretString api_key = 1;
  optional string base_url = 50;
}

message AciConfig {
  SecretString api_key = 1;
  SecretString entity_id = 2;
  optional string base_url = 50;
}

message BamboraConfig {
  SecretString merchant_id = 1;
  SecretString api_key = 2;
  optional string base_url = 50;
}

message BamboraapacConfig {
  SecretString username = 1;
  SecretString password = 2;
  SecretString account_number = 3;
  optional string base_url = 50;
}

message CalidaConfig {
  SecretString api_key = 1;
  optional string base_url = 50;
}

message CeleroConfig {
  SecretString api_key = 1;
  optional string base_url = 50;
}

message NexinetsConfig {
  SecretString merchant_id = 1;
  SecretString api_key = 2;
  optional string base_url = 50;
}

message NexixpayConfig {
  SecretString api_key = 1;
  optional string base_url = 50;
}

message RevolutConfig {
  SecretString secret_api_key = 1;
  optional SecretString signing_secret = 2;
  optional string base_url = 50;
}

message Revolv3Config {
  SecretString api_key = 1;
  optional string base_url = 50;
}

message Shift4Config {
  SecretString api_key = 1;
  optional string base_url = 50;
}

message StaxConfig {
  SecretString api_key = 1;
  optional string base_url = 50;
}

message XenditConfig {
  SecretString api_key = 1;
  optional string base_url = 50;
}

message HelcimConfig {
  SecretString api_key = 1;
  optional string base_url = 50;
}

message MifinityConfig {
  SecretString key = 1;
  optional string base_url = 50;
  optional SecretString brand_id = 51;
  optional SecretString destination_account_number = 52;
}

message MultisafepayConfig {
  SecretString api_key = 1;
  optional string base_url = 50;
}

message ScreenstreamConfig {
  SecretString api_key = 1;
  optional string base_url = 50;
}

message AuthorizedotnetConfig {
  SecretString name = 1;
  SecretString transaction_key = 2;
  optional string base_url = 50;
}

// Two field auth types
message BraintreeConfig {
  SecretString public_key = 1;
  SecretString private_key = 2;
  optional string base_url = 50;
  optional SecretString merchant_account_id = 51;
  optional string merchant_config_currency = 52;
  repeated string apple_pay_supported_networks = 53;
  repeated string apple_pay_merchant_capabilities = 54;
  optional string apple_pay_label = 55;
  optional string gpay_merchant_name = 56;
  optional string gpay_merchant_id = 57;
  repeated string gpay_allowed_auth_methods = 58;
  repeated string gpay_allowed_card_networks = 59;
  optional string paypal_client_id = 60;
  optional string gpay_gateway_merchant_id = 61;
}

message AirwallexConfig {
  SecretString api_key = 1;
  SecretString client_id = 2;
  optional string base_url = 50;
}

message AuthipayConfig {
  SecretString api_key = 1;
  SecretString api_secret = 2;
  optional string base_url = 50;
}

message BillwerkConfig {
  SecretString api_key = 1;
  SecretString public_api_key = 2;
  optional string base_url = 50;
  optional string secondary_base_url = 51;
}

message BluesnapConfig {
  SecretString username = 1;
  SecretString password = 2;
  optional string base_url = 50;
}

message CashfreeConfig {
  SecretString app_id = 1;
  SecretString secret_key = 2;
  optional string base_url = 50;
}

message CheckoutConfig {
  SecretString api_key = 1;
  SecretString api_secret = 2;
  SecretString processing_channel_id = 3;
  optional string base_url = 50;
}

message CryptopayConfig {
  SecretString api_key = 1;
  SecretString api_secret = 2;
  optional string base_url = 50;
}

message DatatransConfig {
  SecretString merchant_id = 1;
  SecretString password = 2;
  optional string base_url = 50;
}

message FiservemeaConfig {
  SecretString api_key = 1;
  SecretString api_secret = 2;
  optional string base_url = 50;
}

message FinixConfig {
  SecretString finix_user_name = 1;
  SecretString finix_password = 2;
  SecretString merchant_identity_id = 3;
  SecretString merchant_id = 4;
  optional string base_url = 50;
}

message GlobalpayConfig {
  SecretString app_id = 1;
  SecretString app_key = 2;
  optional string base_url = 50;
}

message HipayConfig {
  SecretString api_key = 1;
  SecretString api_secret = 2;
  optional string base_url = 50;
  optional string secondary_base_url = 51;
  optional string third_base_url = 52;
}

message JpmorganConfig {
  SecretString client_id = 1;
  SecretString client_secret = 2;
  optional string base_url = 50;
  optional SecretString company_name = 51;
  optional SecretString product_name = 52;
  optional SecretString merchant_purchase_description = 53;
  optional SecretString statement_descriptor = 54;
  optional string secondary_base_url = 55;
}

message PaysafeCardAccountId {
  optional SecretString no_three_ds = 1;
  optional SecretString three_ds = 2;
}

message PaysafeAchAccountId { optional SecretString account_id = 1; }

// Dedicated Apple Pay processing account, split by token flow.
// Mirrors hyperswitch's `ApplePayAccountDetails`: `encrypt` is used for the
// encrypted PKPaymentToken flow, `decrypt` for the decrypted-token flow.
message PaysafeApplePayAccountId {
  optional SecretString encrypt = 1;
  optional SecretString decrypt = 2;
}

// Interac e-Transfer processing account. Native metadata key `three_ds`
// (mirrors hyperswitch `RedirectAccountId`) so the same MCA metadata is portable
// between the native and UCS paths.
message PaysafeInteracAccountId { optional SecretString three_ds = 1; }

// Redirect-APM processing account (Skrill, paysafecard). Native metadata key
// `three_ds` (mirrors hyperswitch `RedirectAccountId`).
message PaysafeRedirectAccountId { optional SecretString three_ds = 1; }

message PaysafePaymentMethodDetails {
  map<string, PaysafeCardAccountId> card = 1;
  map<string, PaysafeAchAccountId> ach = 2;
  // Dedicated Apple Pay processing accounts, keyed by currency.
  map<string, PaysafeApplePayAccountId> apple_pay = 3;
  // Interac e-Transfer processing accounts, keyed by currency.
  map<string, PaysafeInteracAccountId> interac = 4;
  // Skrill wallet processing accounts, keyed by currency.
  map<string, PaysafeRedirectAccountId> skrill = 5;
  // paysafecard processing accounts, keyed by currency.
  map<string, PaysafeRedirectAccountId> pay_safe_card = 6;
}

message LoonioConfig {
  SecretString merchant_id = 1;
  SecretString merchant_token = 2;
  optional string base_url = 50;
}

message DeutschebankConfig {
  SecretString customer_identifier = 1;
  SecretString key_id = 2;
  SecretString signing_private_key = 3;
  SecretString client_certificate_bundle = 4;
  optional string base_url = 50;
}

message PaysafeConfig {
  SecretString username = 1;
  SecretString password = 2;
  optional string base_url = 50;
  // Per-currency processing account IDs for card, ACH, Apple Pay, Interac,
  // Skrill and paysafecard.
  optional PaysafePaymentMethodDetails account_id = 51;
}

message PayuConfig {
  SecretString api_key = 1;
  SecretString api_secret = 2;
  optional string base_url = 50;
}

message PowertranzConfig {
  SecretString power_tranz_id = 1;
  SecretString power_tranz_password = 2;
  optional string base_url = 50;
}

message RapydConfig {
  SecretString access_key = 1;
  SecretString secret_key = 2;
  optional string base_url = 50;
}

message WorldpayConfig {
  SecretString username = 1;
  SecretString password = 2;
  SecretString entity_id = 3;
  optional string base_url = 50;
  optional SecretString merchant_name = 51;
}

// Three field auth types
message AdyenConfig {
  SecretString api_key = 1;
  SecretString merchant_account = 2;
  optional SecretString review_key = 3;
  optional string base_url = 50;
  optional string dispute_base_url = 51;
  optional string endpoint_prefix = 52;
}

message BankOfAmericaConfig {
  SecretString api_key = 1;
  SecretString merchant_account = 2;
  SecretString api_secret = 3;
  optional string base_url = 50;
}

message BarclaycardConfig {
  SecretString api_key = 1;
  SecretString merchant_account = 2;
  SecretString api_secret = 3;
  optional string base_url = 50;
}

message CybersourceConfig {
  SecretString api_key = 1;
  SecretString merchant_account = 2;
  SecretString api_secret = 3;
  optional string base_url = 50;
  optional bool disable_avs = 51;
  optional bool disable_cvn = 52;
}

message DlocalConfig {
  SecretString x_login = 1;
  SecretString x_trans_key = 2;
  SecretString secret = 3;
  optional string base_url = 50;
}

message ElavonConfig {
  SecretString ssl_merchant_id = 1;
  SecretString ssl_user_id = 2;
  SecretString ssl_pin = 3;
  optional string base_url = 50;
}

message FiservConfig {
  SecretString api_key = 1;
  SecretString merchant_account = 2;
  SecretString api_secret = 3;
  optional string base_url = 50;
  optional SecretString terminal_id = 51;
}

message GetnetConfig {
  SecretString api_key = 1;
  SecretString api_secret = 2;
  SecretString seller_id = 3;
  optional string base_url = 50;
}

message HyperpgConfig {
  SecretString username = 1;
  SecretString password = 2;
  SecretString merchant_id = 3;
  optional string base_url = 50;
}

message IatapayConfig {
  SecretString client_id = 1;
  SecretString merchant_id = 2;
  SecretString client_secret = 3;
  optional string base_url = 50;
}

message NuveiConfig {
  SecretString merchant_id = 1;
  SecretString merchant_site_id = 2;
  SecretString merchant_secret = 3;
  optional string base_url = 50;
}

message NovalnetConfig {
  SecretString product_activation_key = 1;
  SecretString payment_access_key = 2;
  SecretString tariff_id = 3;
  optional string base_url = 50;
}

message NoonConfig {
  SecretString api_key = 1;
  SecretString application_identifier = 2;
  SecretString business_identifier = 3;
  optional string base_url = 50;
}

message RedsysConfig {
  SecretString merchant_id = 1;
  SecretString terminal_id = 2;
  SecretString sha256_pwd = 3;
  optional string base_url = 50;
}

message SilverflowConfig {
  SecretString api_key = 1;
  SecretString api_secret = 2;
  SecretString merchant_acceptor_key = 3;
  optional string base_url = 50;
}

message TrustpayConfig {
  SecretString api_key = 1;
  SecretString project_id = 2;
  SecretString secret_key = 3;
  optional string base_url = 50;
  optional string base_url_bank_redirects = 51;
}

message TrustpaymentsConfig {
  SecretString username = 1;
  SecretString password = 2;
  SecretString site_reference = 3;
  optional string base_url = 50;
}

message TsysConfig {
  SecretString device_id = 1;
  SecretString transaction_key = 2;
  SecretString developer_id = 3;
  optional string base_url = 50;
}

message WellsfargoConfig {
  SecretString api_key = 1;
  SecretString merchant_account = 2;
  SecretString api_secret = 3;
  optional string base_url = 50;
}

message WorldpayvantivConfig {
  SecretString user = 1;
  SecretString password = 2;
  SecretString merchant_id = 3;
  optional string base_url = 50;
  optional string report_group = 51;
  optional string merchant_config_currency = 52;
  optional string secondary_base_url = 53;
}

message WorldpayxmlConfig {
  SecretString api_username = 1;
  SecretString api_password = 2;
  SecretString merchant_code = 3;
  optional string base_url = 50;
}

message ZiftConfig {
  SecretString user_name = 1;
  SecretString password = 2;
  SecretString account_id = 3;
  optional string base_url = 50;
}

message FiservcommercehubConfig {
  SecretString api_key = 1;
  SecretString secret = 2;
  SecretString merchant_id = 3;
  SecretString terminal_id = 4;
  optional string base_url = 50;
}

message AbsaSanlamConfig {
  SecretString api_key = 1;
  SecretString merchant_id = 2;
  optional string base_url = 50;
}

message ItaubankConfig {
  SecretString client_secret = 1;
  SecretString client_id = 2;
  optional SecretString certificates = 3;
  optional SecretString private_key = 4;
  optional string base_url = 50;
  optional string secondary_base_url = 51;
}

message SantanderConfig {
  SecretString client_id = 1;
  SecretString client_secret = 2;
  string workspace_id = 3;
  optional SecretString certificates = 4;
  optional SecretString private_key = 5;
  optional string base_url = 50;
}

message GigadatConfig {
  SecretString campaign_id = 1;
  SecretString access_token = 2;
  SecretString security_token = 3;
  optional string base_url = 50;
  optional string site = 51;
}

message PhonepeConfig {
  SecretString merchant_id = 1;
  SecretString salt_key = 2;
  SecretString salt_index = 3;
  optional string base_url = 50;
}

// Four field auth types
message ForteConfig {
  SecretString api_access_id = 1;
  SecretString organization_id = 2;
  SecretString location_id = 3;
  SecretString api_secret_key = 4;
  optional string base_url = 50;
}

message VoltConfig {
  SecretString username = 1;
  SecretString password = 2;
  SecretString client_id = 3;
  SecretString client_secret = 4;
  optional string base_url = 50;
  optional string secondary_base_url = 51;
}

message PayboxConfig {
  SecretString site = 1;
  SecretString rank = 2;
  SecretString key = 3;
  SecretString merchant_id = 4;
  optional string base_url = 50;
}

message PaytmConfig {
  SecretString merchant_id = 1;
  SecretString merchant_key = 2;
  SecretString website = 3;
  optional SecretString client_id = 4;
  optional string base_url = 50;
}

message CashtocodeCurrencyAuthData {
  optional SecretString password_classic = 1;
  optional SecretString password_evoucher = 2;
  optional SecretString username_classic = 3;
  optional SecretString username_evoucher = 4;
  optional SecretString merchant_id_classic = 5;
  optional SecretString merchant_id_evoucher = 6;
}

// Complex auth types with optional fields
message CashtocodeConfig {
  map<string, CashtocodeCurrencyAuthData> auth_key_map = 1;
  optional string base_url = 50;
}

message MollieConfig {
  SecretString api_key = 1;
  optional SecretString profile_token = 2;
  optional string base_url = 50;
  optional string secondary_base_url = 51;
}

message NmiConfig {
  SecretString api_key = 1;
  optional SecretString public_key = 2;
  optional string base_url = 50;
}

message PaymeConfig {
  SecretString seller_payme_id = 1;
  optional SecretString payme_client_key = 2;
  optional string base_url = 50;
}

message PayloadCurrencyAuthData {
  SecretString api_key = 1;
  optional SecretString processing_account_id = 2;
}

message PayloadConfig {
  map<string, PayloadCurrencyAuthData> auth_key_map = 1;
  optional string base_url = 50;
}

message PlacetopayConfig {
  SecretString login = 1;
  SecretString tran_key = 2;
  optional string base_url = 50;
}

message EbanxConfig {
  SecretString api_key = 1;
  optional string base_url = 50;
}

message FiuuConfig {
  SecretString merchant_id = 1;
  SecretString verify_key = 2;
  SecretString secret_key = 3;
  optional string base_url = 50;
  optional string secondary_base_url = 51;
}

message GlobepayConfig {
  SecretString api_key = 1;
  optional string base_url = 50;
}

message CoinbaseConfig {
  SecretString api_key = 1;
  optional string base_url = 50;
}

message CoingateConfig {
  SecretString api_key = 1;
  optional string base_url = 50;
}

message PeachpaymentsConfig {
  SecretString api_key = 1;
  SecretString tenant_id = 2;
  optional string base_url = 50;
  optional SecretString client_merchant_reference_id = 51;
  optional SecretString merchant_payment_method_route_id = 52;
}

message PproConfig {
  SecretString api_key = 1;
  SecretString merchant_id = 2;
  optional string base_url = 50;
}

message PaypalConfig {
  SecretString client_id = 1;
  SecretString client_secret = 2;
  optional SecretString payer_id = 3;
  optional string base_url = 50;
}

message TrustlyConfig {
  SecretString username = 1;
  SecretString password = 2;
  SecretString private_key = 3;
  optional string base_url = 50;
}

message EasebuzzConfig {
  SecretString api_key = 1;
  SecretString api_salt = 2;
  optional string base_url = 50;
  optional string secondary_base_url = 51;
}

message TruelayerConfig {
  SecretString client_id = 1;
  SecretString client_secret = 2;
  SecretString merchant_account_id = 3;
  SecretString account_holder_name = 4;
  SecretString private_key = 5;
  SecretString kid = 6;
  optional string base_url = 50;
  optional string secondary_base_url = 51;
}

message PinelabsOnlineConfig {
  SecretString client_id = 1;
  SecretString client_secret = 2;
  optional string base_url = 50;
}

message ImerchantsolutionsConfig {
  SecretString api_key = 1;
  optional SecretString merchant_id = 2;
  optional string base_url = 3;
}

message GivepaymentsConfig {
  SecretString api_key = 1;
  optional string base_url = 2;
}

message AxisbankConfig {
  SecretString merchant_kid = 3;
  SecretString juspay_kid = 4;
  SecretString merchant_private_key = 5;
  SecretString juspay_public_key = 6;
  optional string base_url = 50;
}

message MayaConfig {
  SecretString public_key = 1;
  SecretString secret_key = 2;
  optional string base_url = 50;
}

message TsysTransitConfig {
  SecretString device_id = 1;
  SecretString transaction_key = 2;
  SecretString developer_id = 3;
  optional SecretString merchant_street_address = 4;
  optional SecretString customer_service_phone_number = 5;
  optional string merchant_url = 6;
  optional string base_url = 50;
}

message FlywireConfig {
  // Flywire Payments Platform API key (X-Authentication-Key header).
  SecretString api_key = 1;
  // HMAC SHA-256 shared secret for inbound webhook signature verification.
  // Optional in sandbox; required for production.
  optional SecretString shared_secret = 2;
  // Flywire recipient code (3-letter or 5-alphanumeric, e.g. "ZENDD").
  // Drives currency, payout target, required institutional fields.
  string recipient_id = 3;
  optional string base_url = 50;
}

message PlaidConfig {
  // Plaid client_id — used as `client_id` in every API request body.
  SecretString client_id = 1;
  // Plaid secret — used as `secret` in every API request body.
  SecretString secret = 2;
  // Application name displayed to users in the Plaid Link UI.
  optional string client_name = 3;
  optional string base_url = 50;
}

message AffirmConfig {
  // Affirm public API key — used as the HTTP Basic auth username.
  SecretString public_key = 1;
  // Affirm private API key — used as the HTTP Basic auth password.
  SecretString private_key = 2;
  optional string base_url = 50;
}

message TwocTwopPacoConfig {
  // Company access token, used as both the `token`/`apikey` HTTP header and
  // as the `iss` / `CompanyApiKey` JWT claim.
  SecretString access_token = 1;
  // PACO multi-merchant scoping key, present in every JOSE request body.
  SecretString office_id = 2;
  // 32-hex-char JWE key id, environment-specific (UAT vs PRD).
  SecretString paco_kid = 3;
  // Merchant RSA private key (PEM) — signs the request JWS (PS256).
  SecretString merchant_signing_private_key = 4;
  // Merchant RSA private key (PEM) — decrypts the response JWE (RSA-OAEP).
  SecretString merchant_encryption_private_key = 5;
  // PACO RSA public key (PEM) — verifies the response JWS.
  SecretString paco_signing_public_key = 6;
  // PACO RSA public key (PEM) — encrypts the request JWE.
  SecretString paco_encryption_public_key = 7;
  // Expected `aud` claim on JOSE response JWTs. Defaults to the access_token
  // when None. Set if PACO emits a different aud on a specific office.
  optional SecretString response_audience = 8;
  optional string base_url = 50;
}

message TamaraConfig {
  SecretString api_key = 1;
  optional string base_url = 50;
}

// Single field auth types
message InterpaymentsConfig {
  SecretString api_key = 1;
  optional string base_url = 50;
}

message JuspayConfig {
  SecretString api_key = 1;
  SecretString merchant_id = 2;

  optional SecretString juspay_encryption_public_key = 3;
  optional SecretString response_decryption_private_key = 4;
  optional SecretString card_sync_key_id = 5;

  optional string base_url = 50;
}

// Qwikcilver (Pine Labs stored-value wallet) credentials.
message QwikcilverConfig {
  // Long-lived Bearer token used only on the /authorize bootstrap call.
  SecretString bootstrap_bearer_token = 1;
  SecretString terminal_id = 2;
  SecretString username = 3;
  SecretString password = 4;
  optional string base_url = 50;
}

message PayconexConfig {
  SecretString api_key = 1;
  SecretString account_id = 2;
  optional string base_url = 50;
}

message KountConfig {
  SecretString api_key = 1;
  // Kount OAuth authorization-server id for the token endpoint
  // (`login.kount.com/oauth2/{auth_server_id}/v1/token`). Account/environment
  // specific; falls back to the sandbox auth server when unset.
  optional string auth_server_id = 2;
  optional string base_url = 50;
}

message HyperswitchConfig {
  SecretString api_key = 1;
  optional string base_url = 50;
}

message GlomopayConfig {
  SecretString api_key = 1;
  optional string base_url = 50;
}

message TesouroConfig {
  SecretString api_key = 1;
  SecretString key1 = 2;
  SecretString api_secret = 3;
  optional string base_url = 50;
}

// ConnectorSpecificConfig message with oneof containing all connector
// configurations. Comment above each field (e.g. "// PAYPAL = 62") is the
// Connector enum value from this file;
message ConnectorSpecificConfig {
  oneof config {
    // ADYEN = 3
    AdyenConfig adyen = 1;

    // AIRWALLEX = 4
    AirwallexConfig airwallex = 2;

    // BAMBORA = 6
    BamboraConfig bambora = 3;

    // BANKOFAMERICA = 8
    BankOfAmericaConfig bankofamerica = 4;

    // BILLWERK = 9
    BillwerkConfig billwerk = 5;

    // BLUESNAP = 11
    BluesnapConfig bluesnap = 6;

    // BRAINTREE = 13
    BraintreeConfig braintree = 7;

    // CASHTOCODE = 14
    CashtocodeConfig cashtocode = 8;

    // CRYPTOPAY = 19
    CryptopayConfig cryptopay = 9;

    // CYBERSOURCE = 22
    CybersourceConfig cybersource = 10;

    // DATATRANS = 23
    DatatransConfig datatrans = 11;

    // DLOCAL = 26
    DlocalConfig dlocal = 12;

    // ELAVON = 28
    ElavonConfig elavon = 13;

    // FISERV = 29
    FiservConfig fiserv = 14;

    // FISERVEMEA = 30
    FiservemeaConfig fiservemea = 15;

    // FORTE = 32
    ForteConfig forte = 16;

    // GETNET = 33
    GetnetConfig getnet = 17;

    // GLOBALPAY = 34
    GlobalpayConfig globalpay = 18;

    // HIPAY = 38
    HipayConfig hipay = 19;

    // HELCIM = 39
    HelcimConfig helcim = 20;

    // IATAPAY = 41
    IatapayConfig iatapay = 21;

    // JPMORGAN = 43
    JpmorganConfig jpmorgan = 22;

    // MIFINITY = 46
    MifinityConfig mifinity = 23;

    // MOLLIE = 47
    MollieConfig mollie = 24;

    // MULTISAFEPAY = 49
    MultisafepayConfig multisafepay = 25;

    // NEXINETS = 51
    NexinetsConfig nexinets = 26;

    // NEXIXPAY = 52
    NexixpayConfig nexixpay = 27;

    // NMI = 53
    NmiConfig nmi = 28;

    // NOON = 55
    NoonConfig noon = 29;

    // NOVALNET = 56
    NovalnetConfig novalnet = 30;

    // NUVEI = 57
    NuveiConfig nuvei = 31;

    // PAYBOX = 59
    PayboxConfig paybox = 32;

    // PAYME = 60
    PaymeConfig payme = 33;

    // PAYU = 64
    PayuConfig payu = 34;

    // POWERTRANZ = 66
    PowertranzConfig powertranz = 35;

    // RAPYD = 68
    RapydConfig rapyd = 36;

    // REDSYS = 71
    RedsysConfig redsys = 37;

    // SHIFT4 = 72
    Shift4Config shift4 = 38;

    // STAX = 74
    StaxConfig stax = 39;

    // STRIPE = 75
    StripeConfig stripe = 40;

    // TRUSTPAY = 78
    TrustpayConfig trustpay = 41;

    // TSYS = 79
    TsysConfig tsys = 42;

    // VOLT = 80
    VoltConfig volt = 43;

    // WELLSFARGO = 81
    WellsfargoConfig wellsfargo = 44;

    // WORLDPAY = 84
    WorldpayConfig worldpay = 45;

    // WORLDPAYVANTIV = 85
    WorldpayvantivConfig worldpayvantiv = 46;

    // XENDIT = 89
    XenditConfig xendit = 47;

    // PHONEPE = 92
    PhonepeConfig phonepe = 48;

    // CASHFREE = 93
    CashfreeConfig cashfree = 49;

    // PAYTM = 94
    PaytmConfig paytm = 50;

    // CALIDA = 95
    CalidaConfig calida = 51;

    // PAYLOAD = 96
    PayloadConfig payload = 52;

    // AUTHIPAY = 97
    AuthipayConfig authipay = 53;

    // SILVERFLOW = 98
    SilverflowConfig silverflow = 54;

    // CELERO = 99
    CeleroConfig celero = 55;

    // TRUSTPAYMENTS = 100
    TrustpaymentsConfig trustpayments = 56;

    // PAYSAFE = 101
    PaysafeConfig paysafe = 57;

    // BARCLAYCARD = 102
    BarclaycardConfig barclaycard = 58;

    // WORLDPAYXML = 103
    WorldpayxmlConfig worldpayxml = 59;

    // REVOLUT = 104
    RevolutConfig revolut = 60;

    // LOONIO = 105
    LoonioConfig loonio = 61;

    // GIGADAT = 106
    GigadatConfig gigadat = 62;

    // HYPERPG = 107
    HyperpgConfig hyperpg = 63;

    // ZIFT = 108
    ZiftConfig zift = 64;

    // SCREENSTREAM (not in enum, added at end)
    ScreenstreamConfig screenstream = 65;

    // EBANX = 27
    EbanxConfig ebanx = 66;

    // FIUU = 31
    FiuuConfig fiuu = 67;

    // GLOBEPAY = 35
    GlobepayConfig globepay = 68;

    // COINBASE = 17
    CoinbaseConfig coinbase = 69;

    // COINGATE = 18
    CoingateConfig coingate = 70;

    // REVOLV3 = 109
    Revolv3Config revolv3 = 71;

    // AUTHORIZEDOTNET = 5
    AuthorizedotnetConfig authorizedotnet = 72;

    // PEACHPAYMENTS = 112
    PeachpaymentsConfig peachpayments = 73;

    // PAYPAL = 62
    PaypalConfig paypal = 110;

    // TRUELAYER = 110
    TruelayerConfig truelayer = 111;

    // FISERVCOMMERCEHUB = 114
    FiservcommercehubConfig fiservcommercehub = 112;

    // ITAUBANKCONFIG = 115
    ItaubankConfig itaubank = 113;

    // PPRO = 113
    PproConfig ppro = 114;

    // TRUSTLY = 116
    TrustlyConfig trustly = 115;

    // ABSA_SANLAM = 116
    AbsaSanlamConfig absa_sanlam = 116;

    // PINELABS_ONLINE = 117
    PinelabsOnlineConfig pinelabs_online = 117;

    // IMERCHANTSOLUTIONS = 118
    ImerchantsolutionsConfig imerchantsolutions = 118;

    // AXISBANK = 119
    AxisbankConfig axisbank = 119;

    // EASEBUZZ = 120
    EasebuzzConfig easebuzz = 120;

    // TWOC_TWOP_PACO = 121
    TwocTwopPacoConfig twoc_twop_paco = 121;

    // BAMBORAAPAC = 7
    BamboraapacConfig bamboraapac = 122;

    // PLACETOPAY = 65
    PlacetopayConfig placetopay = 123;

    // FINIX = 111
    FinixConfig finix = 124;

    // ACI = 125
    AciConfig aci = 125;

    // INTERPAYMENTS = 126
    InterpaymentsConfig interpayments = 126;

    // JUSPAY = 122
    JuspayConfig juspay = 127;
    // TAMARA = 123
    TamaraConfig tamara = 128;

    // PAYCONEX = 124
    PayconexConfig payconex = 129;

    // QWIKCILVER = 125
    QwikcilverConfig qwikcilver = 130;
    // CHECKOUT = 126
    CheckoutConfig checkout = 131;
    // HYPERSWITCH = 126
    HyperswitchConfig hyperswitch = 132;
    // TSYS_TRANSIT = 127
    TsysTransitConfig tsys_transit = 133;
    // KOUNT = 128
    KountConfig kount = 134;
    // AFFIRM = 135
    AffirmConfig affirm = 135;
    // FLYWIRE = 129
    FlywireConfig flywire = 136;
    // GLOMOPAY = 137
    GlomopayConfig glomopay = 137;
    // GIVEPAYMENTS = 138
    GivepaymentsConfig givepayments = 138;

    // TESOURO = 139
    TesouroConfig tesouro = 139;
    // DEUTSCHEBANK = 140
    DeutschebankConfig deutschebank = 140;
    // PLAID = 141
    PlaidConfig plaid = 141;
    // SANTANDER = 142
    SantanderConfig santander = 142;
    // MAYA = 143
    MayaConfig maya = 143;
  }
}

// ============================================================================
// NON-PCI SDK CLIENTS - TOKENIZED AND PROXY PAYMENT MESSAGES
// ============================================================================
// These messages are used for tokenized and proxied payment methods
// for merchants who do not hold raw card data.
// ============================================================================

message PaymentServiceTokenAuthorizeRequest {
  optional string merchant_transaction_id = 1;
  Money amount = 2;
  // Connector-issued token. Replaces PaymentMethod entirely.
  // Examples: Stripe pm_xxx, Adyen recurringDetailReference, Braintree nonce.
  SecretString connector_token = 3;
  optional Customer customer = 4;
  PaymentAddress address = 5;
  optional CaptureMethod capture_method = 6;
  optional string return_url = 7;
  optional string webhook_url = 8;
  optional SecretString metadata = 9;
  optional SecretString connector_feature_data = 10;
  optional FutureUsage setup_future_usage = 11;
  optional BrowserInformation browser_info = 12;
  optional ConnectorState state = 13;
  optional BillingDescriptor billing_descriptor = 14;
  optional string merchant_order_id = 15;
  optional L2L3Data l2_l3_data = 16;
  optional CustomerAcceptance customer_acceptance = 17;
  optional PaymentExperience payment_experience = 18;
  optional string description = 19;
  optional PaymentChannel payment_channel = 20;
  optional bool test_mode = 21;
  // auth_type intentionally absent: PSP tokens cannot drive external 3DS.
  // Use connector_feature_data to pass connector-specific delegated-3DS flags.

  // Send the connector order identifier here if an order was created before
  // authorize
  optional string connector_order_id = 22;
  optional int64 shipping_cost = 23;    // Cost of shipping for the order
}

message PaymentServiceTokenSetupRecurringRequest {
  string merchant_recurring_payment_id = 1;
  Money amount = 2;
  SecretString connector_token = 3;
  optional Customer customer = 4;
  PaymentAddress address = 5;
  optional string return_url = 6;
  optional string webhook_url = 7;
  optional SecretString metadata = 8;
  optional SecretString connector_feature_data = 9;
  optional ConnectorState state = 10;
  optional CustomerAcceptance customer_acceptance = 11;
  optional SetupMandateDetails setup_mandate_details = 12;
  optional BillingDescriptor billing_descriptor = 13;
  optional string locale = 14;
  optional FutureUsage setup_future_usage = 15;
}

// ── ProxiedPaymentService messages ──────────────────────────────────────────────

message PaymentServiceProxyAuthorizeRequest {
  optional string merchant_transaction_id = 1;
  Money amount = 2;
  // Card proxy for vault-aliased payments (VGS, Basis Theory, Spreedly).
  // Real card values are substituted by the proxy before reaching the connector.
  ProxyCardDetails card_proxy = 3;
  optional Customer customer = 4;
  PaymentAddress address = 5;
  optional CaptureMethod capture_method = 6;
  AuthenticationType auth_type = 7;
  optional AuthenticationData authentication_data = 8;
  optional string return_url = 9;
  optional string webhook_url = 10;
  optional SecretString metadata = 11;
  optional SecretString connector_feature_data = 12;
  optional FutureUsage setup_future_usage = 13;
  optional BrowserInformation browser_info = 14;
  optional ConnectorState state = 15;
  optional SetupMandateDetails setup_mandate_details = 16;
  optional BillingDescriptor billing_descriptor = 17;
  optional ThreeDsCompletionIndicator threeds_completion_indicator = 18;
  optional RedirectionResponse redirection_response = 19;
  optional L2L3Data l2_l3_data = 20;
  optional CustomerAcceptance customer_acceptance = 21;
  optional string merchant_order_id = 22;
  optional bool test_mode = 23;
  // Order Details
  optional string order_category = 24; // Category of the order/service
  optional string description = 25; // Description of the transaction

  // Send the connector order identifier here if an order was created before
  // authorize
  optional string connector_order_id = 26;
  optional int64 shipping_cost = 27;    // Cost of shipping for the order

  // Domain-specific data (e.g. airline itinerary) for connectors that need it.
  optional DomainData domain_data = 28;
}

message PaymentServiceProxySetupRecurringRequest {
  string merchant_recurring_payment_id = 1;
  Money amount = 2;
  // Card proxy for vault-aliased payments.
  ProxyCardDetails card_proxy = 3;
  optional Customer customer = 4;
  PaymentAddress address = 5;
  optional string return_url = 6;
  optional string webhook_url = 7;
  optional SecretString metadata = 8;
  optional ConnectorState state = 9;
  optional SetupMandateDetails setup_mandate_details = 10;
  optional CustomerAcceptance customer_acceptance = 11;
  AuthenticationType auth_type = 12;
  optional AuthenticationData authentication_data = 13;
  optional FutureUsage setup_future_usage = 14;
  optional BrowserInformation browser_info = 15;
  // Order Details
  optional string order_category = 16; // Category of the order/service
  optional string description = 17; // Description of the mandate setup
}

// ============================================================================
// SPLIT REFUND TYPES
// ============================================================================

// Request for split refunds (platform fee reversals, transfers, etc.)
message SplitRefundsDetails {
  oneof split_refund_type {
    StripeSplitRefundData stripe_split_refund = 1;
    AdyenSplitData adyen_split_refund = 2;
  }
}

// Stripe-specific split refund data
message StripeSplitRefundData {
  string charge_id = 1;
  string transfer_account_id = 2;
  PaymentChargeType charge_type = 3;
  ChargeRefundsOptions options = 4;
}

// Type of charge for Stripe split refunds
enum PaymentChargeType {
  PAYMENT_CHARGE_TYPE_UNSPECIFIED = 0;
  STRIPE_DIRECT = 1;
  STRIPE_DESTINATION = 2;
}

// Options for charge refunds (destination vs direct)
message ChargeRefundsOptions {
  oneof charge_option {
    DestinationChargeRefund destination = 1;
    DirectChargeRefund direct = 2;
  }
}

// Destination charge refund options
message DestinationChargeRefund {
  bool revert_platform_fee = 1;
  bool revert_transfer = 2;
}

// Direct charge refund options
message DirectChargeRefund {
  bool revert_platform_fee = 1;
}

// Adyen-specific split refund data
message AdyenSplitData {
  optional string store = 1;
  repeated AdyenSplitItem split_items = 2;
}

// Individual split item for Adyen
message AdyenSplitItem {
  optional int64 amount = 1;
  AdyenSplitType split_type = 2;
  optional string account = 3;
  string reference = 4;
  optional string description = 5;
}

// Adyen split type enumeration
enum AdyenSplitType {
  ADYEN_SPLIT_TYPE_UNSPECIFIED = 0;
  BALANCE_ACCOUNT = 1;
  ACQUIRING_FEES = 2;
  PAYMENT_FEE = 3;
  ADYEN_FEES = 4;
  ADYEN_COMMISSION = 5;
  ADYEN_MARKUP = 6;
  INTERCHANGE = 7;
  SCHEME_FEE = 8;
  COMMISSION = 9;
  TOP_UP = 10;
  VAT = 11;
}

// ============================================================================
// SPLIT PAYMENT TYPES
// ============================================================================

// Request for split payments (platform fees, transfers, etc.)
message SplitPaymentsDetails {
  oneof split_payment_type {
    StripeSplitPaymentData stripe_split_payment = 1;
    AdyenSplitData adyen_split_payment = 2;
  }
}

// Stripe-specific split payment data
message StripeSplitPaymentData {
  PaymentChargeType charge_type = 1;
  optional int64 application_fees = 2;
  string transfer_account_id = 3;
  optional string on_behalf_of = 4;
}

// ============================================================================
// ELIGIBILITY — Pre-checkout eligibility for payment methods requiring
//                customer/order details before authorization (e.g. BNPL).
// ============================================================================

// Eligibility status reason codes returned by the connector.
enum EligibilityStatus {
  ELIGIBILITY_STATUS_UNSPECIFIED = 0; // Default, status not specified
  INELIGIBLE = 1;                     // Customer is ineligible
  ELIGIBLE = 2;                       // Customer is eligible
}

// Request to check pre-checkout eligibility for a payment method.
// Used by PaymentMethodService.Eligibility (e.g. BNPL connectors like Tamara).
message PaymentMethodServiceEligibilityRequest {
  // Order amount and currency using the shared Money message.
  Money amount = 1;

  // Customer details (phone, email, name, etc.).
  // At a minimum the connector requires phone_number and/or email.
  optional Customer customer = 2;

  // Billing and shipping address. Many BNPL connectors gate eligibility on
  // the billing country and use the address for risk scoring.
  optional PaymentAddress address = 3;

  // Order line items. BNPL eligibility frequently depends on the cart
  // contents (category, quantity, per-item amount).
  repeated OrderDetailsWithAmount order_details = 4;

  // Market/country the eligibility check is for. BNPL availability is
  // country-gated; set this when it cannot be derived from the address.
  optional CountryAlpha2 country = 5;

  // The specific payment method (e.g. a BNPL variant) eligibility is being
  // checked for, when the caller wants to scope the check.
  optional PaymentMethodType payment_method_type = 6;

  // Description for connector-rendered eligibility messaging.
  optional string description = 7;

  // Additional metadata for the connector
  optional SecretString metadata = 8;

  // Connector-specific feature data for the transaction.
  optional SecretString connector_feature_data = 9;

  // Sandbox/test mode flag (true for test environment).
  optional bool test_mode = 10;
}

// Response from a pre-checkout eligibility check.
message PaymentMethodServiceEligibilityResponse {
  EligibilityStatus eligibility = 1;

  // HTTP status code returned by the upstream connector.
  uint32 status_code = 2;

  // Structured error details (only present on failure).
  optional ErrorInfo error_info = 3;

  // Raw request sent to the connector (for debugging).
  optional SecretString raw_connector_request = 4;

  // Raw response received from the connector (for debugging).
  optional SecretString raw_connector_response = 5;

  // Response headers from the connector.
  map<string, string> response_headers = 6;
}

// ============================================================================
// SPLIT RESPONSE TYPES
// ============================================================================

// Stripe-specific split response data (includes charge_id)
message StripeSplitResponseData {
  optional string charge_id = 1;
  PaymentChargeType charge_type = 2;
  optional int64 application_fees = 3;
  string transfer_account_id = 4;
  optional string on_behalf_of = 5;
}

// Response data for connector split payments
message ConnectorSplitResponseData {
  oneof split_response_type {
    StripeSplitResponseData stripe_split_response = 1;
    AdyenSplitData adyen_split_response = 2;
  }
}
