129 lines
4.0 KiB
Protocol Buffer
129 lines
4.0 KiB
Protocol Buffer
syntax = "proto3";
|
|
|
|
package payments.quotation.v2;
|
|
|
|
option go_package = "github.com/tech/sendico/pkg/proto/payments/quotation/v2;quotationv2";
|
|
|
|
import "google/protobuf/timestamp.proto";
|
|
import "api/proto/common/storable/v1/storable.proto";
|
|
import "api/proto/common/money/v1/money.proto";
|
|
import "api/proto/common/payment/v1/asset.proto";
|
|
import "api/proto/common/payment/v1/settlement.proto";
|
|
import "api/proto/billing/fees/v1/fees.proto";
|
|
import "api/proto/oracle/v1/oracle.proto";
|
|
|
|
// QuoteState tracks the lifecycle of a payment quote.
|
|
enum QuoteState {
|
|
QUOTE_STATE_UNSPECIFIED = 0;
|
|
QUOTE_STATE_INDICATIVE = 1;
|
|
QUOTE_STATE_EXECUTABLE = 2;
|
|
QUOTE_STATE_BLOCKED = 3;
|
|
QUOTE_STATE_EXPIRED = 4;
|
|
}
|
|
|
|
// QuoteBlockReason explains why a quote cannot be executed.
|
|
enum QuoteBlockReason {
|
|
QUOTE_BLOCK_REASON_UNSPECIFIED = 0;
|
|
QUOTE_BLOCK_REASON_ROUTE_UNAVAILABLE = 1;
|
|
QUOTE_BLOCK_REASON_LIMIT_BLOCKED = 2;
|
|
QUOTE_BLOCK_REASON_RISK_BLOCKED = 3;
|
|
QUOTE_BLOCK_REASON_INSUFFICIENT_LIQUIDITY = 4;
|
|
QUOTE_BLOCK_REASON_PRICE_STALE = 5;
|
|
QUOTE_BLOCK_REASON_AMOUNT_TOO_SMALL = 6;
|
|
QUOTE_BLOCK_REASON_AMOUNT_TOO_LARGE = 7;
|
|
}
|
|
|
|
// QuoteExecutionReadiness indicates how readily a quote can be executed.
|
|
enum QuoteExecutionReadiness {
|
|
QUOTE_EXECUTION_READINESS_UNSPECIFIED = 0;
|
|
QUOTE_EXECUTION_READINESS_LIQUIDITY_READY = 1;
|
|
QUOTE_EXECUTION_READINESS_LIQUIDITY_OBTAINABLE = 2;
|
|
QUOTE_EXECUTION_READINESS_INDICATIVE = 3;
|
|
}
|
|
|
|
// RouteHopRole classifies a hop's position in the payment route.
|
|
enum RouteHopRole {
|
|
ROUTE_HOP_ROLE_UNSPECIFIED = 0;
|
|
ROUTE_HOP_ROLE_SOURCE = 1;
|
|
ROUTE_HOP_ROLE_TRANSIT = 2;
|
|
ROUTE_HOP_ROLE_DESTINATION = 3;
|
|
}
|
|
|
|
// FeeTreatment determines how fees are applied to the transfer amount.
|
|
enum FeeTreatment {
|
|
FEE_TREATMENT_UNSPECIFIED = 0;
|
|
FEE_TREATMENT_ADD_TO_SOURCE = 1;
|
|
FEE_TREATMENT_DEDUCT_FROM_DESTINATION = 2;
|
|
}
|
|
|
|
// RouteHop represents a single step in the payment route topology.
|
|
message RouteHop {
|
|
uint32 index = 1;
|
|
string rail = 2;
|
|
string gateway = 3;
|
|
string instance_id = 4;
|
|
string network = 5;
|
|
RouteHopRole role = 6;
|
|
}
|
|
|
|
// RouteSettlement describes the settlement asset and model for a route.
|
|
message RouteSettlement {
|
|
common.payment.v1.ChainAsset asset = 1;
|
|
string model = 2;
|
|
}
|
|
|
|
// Abstract execution route selected during quotation.
|
|
// This is not an execution plan and must not contain operational steps.
|
|
message RouteSpecification {
|
|
// Optional summary fields. Topology is represented by hops + route_ref.
|
|
string rail = 1;
|
|
string provider = 2;
|
|
string payout_method = 3;
|
|
string network = 4;
|
|
string route_ref = 5;
|
|
string pricing_profile_ref = 6;
|
|
repeated RouteHop hops = 7;
|
|
RouteSettlement settlement = 8;
|
|
}
|
|
|
|
// Execution assumptions and constraints evaluated at quotation time.
|
|
// Operational planning is performed by the execution layer later.
|
|
message ExecutionConditions {
|
|
QuoteExecutionReadiness readiness = 1;
|
|
bool batching_eligible = 2;
|
|
bool prefunding_required = 3;
|
|
bool prefunding_cost_included = 4;
|
|
bool liquidity_check_required_at_execution = 5;
|
|
string latency_hint = 6;
|
|
repeated string assumptions = 7;
|
|
}
|
|
|
|
// PaymentQuote is a priced, time-bound quote for a single payment intent.
|
|
message PaymentQuote {
|
|
common.storable.v1.Storable storable = 1;
|
|
QuoteState state = 2;
|
|
QuoteBlockReason block_reason = 3;
|
|
|
|
// Transfer principal amount before fees.
|
|
common.money.v1.Money transfer_principal_amount = 4;
|
|
// Expected destination settlement amount.
|
|
common.money.v1.Money destination_amount = 5;
|
|
|
|
repeated fees.v1.DerivedPostingLine fee_lines = 6;
|
|
repeated fees.v1.AppliedRule fee_rules = 7;
|
|
|
|
oracle.v1.Quote fx_quote = 8;
|
|
|
|
string quote_ref = 9;
|
|
|
|
google.protobuf.Timestamp expires_at = 10;
|
|
google.protobuf.Timestamp priced_at = 11;
|
|
|
|
RouteSpecification route = 12;
|
|
ExecutionConditions execution_conditions = 13;
|
|
// Total amount expected to be debited from payer side (principal +/- fee lines in source currency).
|
|
common.money.v1.Money payer_total_debit_amount = 14;
|
|
common.payment.v1.SettlementMode resolved_settlement_mode = 15;
|
|
FeeTreatment resolved_fee_treatment = 16;
|
|
}
|