sendico/api/proto/payments/shared/v1/shared.proto

syntax = "proto3";

package payments.shared.v1;

option go_package = "github.com/tech/sendico/pkg/proto/payments/shared/v1;sharedv1";

import "google/protobuf/timestamp.proto";
import "api/proto/common/money/v1/money.proto";
import "api/proto/common/fx/v1/fx.proto";
import "api/proto/common/gateway/v1/gateway.proto";
import "api/proto/common/payment/v1/settlement.proto";
import "api/proto/common/trace/v1/trace.proto";
import "api/proto/billing/fees/v1/fees.proto";
import "api/proto/gateway/chain/v1/chain.proto";
import "api/proto/oracle/v1/oracle.proto";

// PaymentKind classifies the type of payment operation.
enum PaymentKind {
  PAYMENT_KIND_UNSPECIFIED = 0;
  PAYMENT_KIND_PAYOUT = 1;
  PAYMENT_KIND_INTERNAL_TRANSFER = 2;
  PAYMENT_KIND_FX_CONVERSION = 3;
}

// PaymentState tracks the lifecycle of a payment.
enum PaymentState {
  PAYMENT_STATE_UNSPECIFIED = 0;
  PAYMENT_STATE_ACCEPTED = 1;
  PAYMENT_STATE_FUNDS_RESERVED = 2;
  PAYMENT_STATE_SUBMITTED = 3;
  PAYMENT_STATE_SETTLED = 4;
  PAYMENT_STATE_FAILED = 5;
  PAYMENT_STATE_CANCELLED = 6;
}

// PaymentFailureCode categorises the reason for a payment failure.
enum PaymentFailureCode {
  FAILURE_UNSPECIFIED = 0;
  FAILURE_BALANCE = 1;
  FAILURE_LEDGER = 2;
  FAILURE_FX = 3;
  FAILURE_CHAIN = 4;
  FAILURE_FEES = 5;
  FAILURE_POLICY = 6;
}

// RequestMeta carries organisation context and tracing information for
// every payment service request.
message RequestMeta {
  string organization_ref = 1;
  common.trace.v1.TraceContext trace = 2;
}

// LedgerEndpoint identifies a source or destination on the internal ledger.
message LedgerEndpoint {
  string ledger_account_ref = 1;
  string contra_ledger_account_ref = 2;
}

// ManagedWalletEndpoint identifies a platform-managed blockchain wallet.
message ManagedWalletEndpoint {
  string managed_wallet_ref = 1;
  chain.gateway.v1.Asset asset = 2;
}

// ExternalChainEndpoint identifies an external blockchain address.
message ExternalChainEndpoint {
  chain.gateway.v1.Asset asset = 1;
  string address = 2;
  string memo = 3;
}

// Card payout destination.
message CardEndpoint {
  oneof card {
    string pan = 1; // raw PAN
    string token = 2; // network or gateway-issued token
  }
  string cardholder_name = 3;
  string cardholder_surname = 4;
  uint32 exp_month = 5;
  uint32 exp_year = 6;
  string country = 7;
  string masked_pan = 8;
}

// PaymentEndpoint is a polymorphic endpoint that can target any supported rail.
message PaymentEndpoint {
  oneof endpoint {
    LedgerEndpoint ledger = 1;
    ManagedWalletEndpoint managed_wallet = 2;
    ExternalChainEndpoint external_chain = 3;
    CardEndpoint card = 4;
  }
  map<string, string> metadata = 10;
  string instance_id = 11;
}

// FXIntent describes the foreign-exchange requirements for a payment.
message FXIntent {
  common.fx.v1.CurrencyPair pair = 1;
  common.fx.v1.Side side = 2;
  bool firm = 3;
  int64 ttl_ms = 4;
  string preferred_provider = 5;
  int32 max_age_ms = 6;
}

// PaymentIntent fully describes a payment to be executed, including source,
// destination, amount, FX, fee policy, and settlement preferences.
message PaymentIntent {
  PaymentKind kind = 1;
  PaymentEndpoint source = 2;
  PaymentEndpoint destination = 3;
  common.money.v1.Money amount = 4;
  bool requires_fx = 5;
  FXIntent fx = 6;
  fees.v1.PolicyOverrides fee_policy = 7;
  map<string, string> attributes = 8;
  common.payment.v1.SettlementMode settlement_mode = 9;
  Customer customer = 10;
  string settlement_currency = 11;
  string ref = 12;
}

// Customer holds payer identity and address details for compliance and
// routing purposes.
message Customer {
  string id = 1;
  string first_name = 2;
  string middle_name = 3;
  string last_name = 4;
  string ip = 5;
  string zip = 6;
  string country = 7;
  string state = 8;
  string city = 9;
  string address = 10;
}

// PaymentQuote captures the pricing snapshot for a payment including
// debit amount, expected settlement, fees, and FX details.
message PaymentQuote {
  common.money.v1.Money debit_amount = 1;
  common.money.v1.Money expected_settlement_amount = 2;
  common.money.v1.Money expected_fee_total = 3;
  repeated fees.v1.DerivedPostingLine fee_lines = 4;
  repeated fees.v1.AppliedRule fee_rules = 5;
  oracle.v1.Quote fx_quote = 6;
  chain.gateway.v1.EstimateTransferFeeResponse network_fee = 7;
  string quote_ref = 8;
  common.money.v1.Money debit_settlement_amount = 9;
}

// PaymentQuoteAggregate summarises totals across multiple payment quotes.
message PaymentQuoteAggregate {
  repeated common.money.v1.Money debit_amounts = 1;
  repeated common.money.v1.Money expected_settlement_amounts = 2;
  repeated common.money.v1.Money expected_fee_totals = 3;
  repeated common.money.v1.Money network_fee_totals = 4;
}

// ExecutionRefs collects cross-service references created during payment
// execution (ledger entries, chain transfers, card payouts).
message ExecutionRefs {
  string debit_entry_ref = 1;
  string credit_entry_ref = 2;
  string fx_entry_ref = 3;
  string chain_transfer_ref = 4;
  string card_payout_ref = 5;
  string fee_transfer_ref = 6;
}

// ExecutionStep describes a single operational step in the legacy execution plan.
message ExecutionStep {
  string code = 1;
  string description = 2;
  common.money.v1.Money amount = 3;
  common.money.v1.Money network_fee = 4;
  string source_wallet_ref = 5;
  string destination_ref = 6;
  string transfer_ref = 7;
  map<string, string> metadata = 8;
  string operation_ref = 9;
}

// ExecutionPlan is the legacy ordered list of steps for fulfilling a payment.
message ExecutionPlan {
  repeated ExecutionStep steps = 1;
  common.money.v1.Money total_network_fee = 2;
}

// PaymentStep is a single rail-level operation within a PaymentPlan.
message PaymentStep {
  common.gateway.v1.Rail rail = 1;
  string gateway_id = 2; // required for external rails
  common.gateway.v1.RailOperation action = 3;
  common.money.v1.Money amount = 4;
  string step_id = 5;
  string instance_id = 6;
  repeated string depends_on = 7;
  string commit_policy = 8;
  repeated string commit_after = 9;
}

// PaymentPlan is the orchestrated sequence of rail-level steps that fulfil
// a payment, including FX and fee lines.
message PaymentPlan {
  string id = 1;
  repeated PaymentStep steps = 2;
  string idempotency_key = 3;
  google.protobuf.Timestamp created_at = 4;
  oracle.v1.Quote fx_quote = 5;
  repeated fees.v1.DerivedPostingLine fees = 6;
}

// Card payout gateway tracking info.
message CardPayout {
  string payout_ref = 1;
  string provider_payment_id = 2;
  string status = 3;
  string failure_reason = 4;
  string card_country = 5;
  string masked_pan = 6;
  string provider_code = 7;
  string gateway_reference = 8;
}

// Payment is the top-level aggregate representing a payment throughout its
// lifecycle, from initiation through settlement or failure.
message Payment {
  string payment_ref = 1;
  string idempotency_key = 2;
  PaymentIntent intent = 3;
  PaymentState state = 4;
  PaymentFailureCode failure_code = 5;
  string failure_reason = 6;
  PaymentQuote last_quote = 7;
  ExecutionRefs execution = 8;
  map<string, string> metadata = 9;
  google.protobuf.Timestamp created_at = 10;
  google.protobuf.Timestamp updated_at = 11;
  CardPayout card_payout = 12;
  ExecutionPlan execution_plan = 13;
  PaymentPlan payment_plan = 14;
}