service backend

api/proto/payments/orchestrator/v1/orchestrator.proto

@@ -0,0 +1,222 @@
+syntax = "proto3";
+
+package payments.orchestrator.v1;
+
+option go_package = "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1;orchestratorv1";
+
+import "google/protobuf/timestamp.proto";
+import "common/money/v1/money.proto";
+import "common/fx/v1/fx.proto";
+import "common/trace/v1/trace.proto";
+import "common/pagination/v1/cursor.proto";
+import "billing/fees/v1/fees.proto";
+import "chain/gateway/v1/gateway.proto";
+import "oracle/v1/oracle.proto";
+
+enum PaymentKind {
+  PAYMENT_KIND_UNSPECIFIED = 0;
+  PAYMENT_KIND_PAYOUT = 1;
+  PAYMENT_KIND_INTERNAL_TRANSFER = 2;
+  PAYMENT_KIND_FX_CONVERSION = 3;
+}
+
+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;
+}
+
+enum PaymentFailureCode {
+  PAYMENT_FAILURE_CODE_UNSPECIFIED = 0;
+  PAYMENT_FAILURE_CODE_BALANCE = 1;
+  PAYMENT_FAILURE_CODE_LEDGER = 2;
+  PAYMENT_FAILURE_CODE_FX = 3;
+  PAYMENT_FAILURE_CODE_CHAIN = 4;
+  PAYMENT_FAILURE_CODE_FEES = 5;
+  PAYMENT_FAILURE_CODE_POLICY = 6;
+}
+
+message RequestMeta {
+  string organization_ref = 1;
+  common.trace.v1.TraceContext trace = 2;
+}
+
+message LedgerEndpoint {
+  string ledger_account_ref = 1;
+  string contra_ledger_account_ref = 2;
+}
+
+message ManagedWalletEndpoint {
+  string managed_wallet_ref = 1;
+  chain.gateway.v1.Asset asset = 2;
+}
+
+message ExternalChainEndpoint {
+  chain.gateway.v1.Asset asset = 1;
+  string address = 2;
+  string memo = 3;
+}
+
+message PaymentEndpoint {
+  oneof endpoint {
+    LedgerEndpoint ledger = 1;
+    ManagedWalletEndpoint managed_wallet = 2;
+    ExternalChainEndpoint external_chain = 3;
+  }
+  map<string, string> metadata = 10;
+}
+
+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;
+}
+
+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;
+}
+
+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 fee_quote_token = 8;
+}
+
+message ExecutionRefs {
+  string debit_entry_ref = 1;
+  string credit_entry_ref = 2;
+  string fx_entry_ref = 3;
+  string chain_transfer_ref = 4;
+}
+
+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;
+}
+
+message QuotePaymentRequest {
+  RequestMeta meta = 1;
+  string idempotency_key = 2;
+  PaymentIntent intent = 3;
+  bool preview_only = 4;
+}
+
+message QuotePaymentResponse {
+  PaymentQuote quote = 1;
+}
+
+message InitiatePaymentRequest {
+  RequestMeta meta = 1;
+  string idempotency_key = 2;
+  PaymentIntent intent = 3;
+  string fee_quote_token = 4;
+  string fx_quote_ref = 5;
+  map<string, string> metadata = 6;
+}
+
+message InitiatePaymentResponse {
+  Payment payment = 1;
+}
+
+message GetPaymentRequest {
+  RequestMeta meta = 1;
+  string payment_ref = 2;
+}
+
+message GetPaymentResponse {
+  Payment payment = 1;
+}
+
+message ListPaymentsRequest {
+  RequestMeta meta = 1;
+  repeated PaymentState filter_states = 2;
+  string source_ref = 3;
+  string destination_ref = 4;
+  common.pagination.v1.CursorPageRequest page = 5;
+}
+
+message ListPaymentsResponse {
+  repeated Payment payments = 1;
+  common.pagination.v1.CursorPageResponse page = 2;
+}
+
+message CancelPaymentRequest {
+  RequestMeta meta = 1;
+  string payment_ref = 2;
+  string reason = 3;
+}
+
+message CancelPaymentResponse {
+  Payment payment = 1;
+}
+
+message ProcessTransferUpdateRequest {
+  RequestMeta meta = 1;
+  chain.gateway.v1.TransferStatusChangedEvent event = 2;
+}
+
+message ProcessTransferUpdateResponse {
+  Payment payment = 1;
+}
+
+message ProcessDepositObservedRequest {
+  RequestMeta meta = 1;
+  chain.gateway.v1.WalletDepositObservedEvent event = 2;
+}
+
+message ProcessDepositObservedResponse {
+  Payment payment = 1;
+}
+
+message InitiateConversionRequest {
+  RequestMeta meta = 1;
+  string idempotency_key = 2;
+  PaymentEndpoint source = 3;
+  PaymentEndpoint destination = 4;
+  FXIntent fx = 5;
+  fees.v1.PolicyOverrides fee_policy = 6;
+  map<string, string> metadata = 7;
+}
+
+message InitiateConversionResponse {
+  Payment conversion = 1;
+}
+
+service PaymentOrchestrator {
+  rpc QuotePayment(QuotePaymentRequest) returns (QuotePaymentResponse);
+  rpc InitiatePayment(InitiatePaymentRequest) returns (InitiatePaymentResponse);
+  rpc CancelPayment(CancelPaymentRequest) returns (CancelPaymentResponse);
+  rpc GetPayment(GetPaymentRequest) returns (GetPaymentResponse);
+  rpc ListPayments(ListPaymentsRequest) returns (ListPaymentsResponse);
+  rpc InitiateConversion(InitiateConversionRequest) returns (InitiateConversionResponse);
+  rpc ProcessTransferUpdate(ProcessTransferUpdateRequest) returns (ProcessTransferUpdateResponse);
+  rpc ProcessDepositObserved(ProcessDepositObservedRequest) returns (ProcessDepositObservedResponse);
+}