sendico/api/proto/payments/orchestration/v1/orchestration.proto

syntax = "proto3";

package payments.orchestration.v1;

option go_package = "github.com/tech/sendico/pkg/proto/payments/orchestration/v1;orchestrationv1";

import "api/proto/common/pagination/v1/cursor.proto";
import "api/proto/billing/fees/v1/fees.proto";
import "api/proto/gateway/chain/v1/chain.proto";
import "api/proto/gateway/mntx/v1/mntx.proto";
import "api/proto/payments/shared/v1/shared.proto";

// InitiatePaymentsRequest triggers execution of all payment intents within
// a previously accepted quote.
message InitiatePaymentsRequest {
  payments.shared.v1.RequestMeta meta = 1;
  string idempotency_key = 2;
  string quote_ref = 3;
  map<string, string> metadata = 4;
}

// InitiatePaymentsResponse returns the created payments.
message InitiatePaymentsResponse {
  repeated payments.shared.v1.Payment payments = 1;
}

// InitiatePaymentRequest creates a single payment from a standalone intent.
message InitiatePaymentRequest {
  payments.shared.v1.RequestMeta meta = 1;
  string idempotency_key = 2;
  payments.shared.v1.PaymentIntent intent = 3;
  map<string, string> metadata = 4;
  string quote_ref = 5;
}

// InitiatePaymentResponse returns the created payment.
message InitiatePaymentResponse {
  payments.shared.v1.Payment payment = 1;
}

// GetPaymentRequest fetches a payment by its reference.
message GetPaymentRequest {
  payments.shared.v1.RequestMeta meta = 1;
  string payment_ref = 2;
}

// GetPaymentResponse returns the requested payment.
message GetPaymentResponse {
  payments.shared.v1.Payment payment = 1;
}

// ListPaymentsRequest queries payments with optional state and endpoint filters.
message ListPaymentsRequest {
  payments.shared.v1.RequestMeta meta = 1;
  repeated payments.shared.v1.PaymentState filter_states = 2;
  string source_ref = 3;
  string destination_ref = 4;
  common.pagination.v1.CursorPageRequest page = 5;
  string organization_ref = 6;
}

// ListPaymentsResponse returns a page of matching payments.
message ListPaymentsResponse {
  repeated payments.shared.v1.Payment payments = 1;
  common.pagination.v1.CursorPageResponse page = 2;
}

// CancelPaymentRequest requests cancellation of a payment that has not yet
// been settled.
message CancelPaymentRequest {
  payments.shared.v1.RequestMeta meta = 1;
  string payment_ref = 2;
  string reason = 3;
}

// CancelPaymentResponse returns the updated payment after cancellation.
message CancelPaymentResponse {
  payments.shared.v1.Payment payment = 1;
}

// ProcessTransferUpdateRequest handles a blockchain transfer status change
// event from the chain gateway.
message ProcessTransferUpdateRequest {
  payments.shared.v1.RequestMeta meta = 1;
  chain.gateway.v1.TransferStatusChangedEvent event = 2;
}

// ProcessTransferUpdateResponse returns the payment after processing.
message ProcessTransferUpdateResponse {
  payments.shared.v1.Payment payment = 1;
}

// ProcessDepositObservedRequest handles a wallet deposit observation event
// from the chain gateway.
message ProcessDepositObservedRequest {
  payments.shared.v1.RequestMeta meta = 1;
  chain.gateway.v1.WalletDepositObservedEvent event = 2;
}

// ProcessDepositObservedResponse returns the payment after processing.
message ProcessDepositObservedResponse {
  payments.shared.v1.Payment payment = 1;
}

// ProcessCardPayoutUpdateRequest handles a card payout status change event
// from the card gateway.
message ProcessCardPayoutUpdateRequest {
  payments.shared.v1.RequestMeta meta = 1;
  mntx.gateway.v1.CardPayoutStatusChangedEvent event = 2;
}

// ProcessCardPayoutUpdateResponse returns the payment after processing.
message ProcessCardPayoutUpdateResponse {
  payments.shared.v1.Payment payment = 1;
}

// InitiateConversionRequest creates an FX conversion payment between two
// ledger endpoints.
message InitiateConversionRequest {
  payments.shared.v1.RequestMeta meta = 1;
  string idempotency_key = 2;
  payments.shared.v1.PaymentEndpoint source = 3;
  payments.shared.v1.PaymentEndpoint destination = 4;
  payments.shared.v1.FXIntent fx = 5;
  fees.v1.PolicyOverrides fee_policy = 6;
  map<string, string> metadata = 7;
}

// InitiateConversionResponse returns the created conversion payment.
message InitiateConversionResponse {
  payments.shared.v1.Payment conversion = 1;
}

// PaymentExecutionService orchestrates payment lifecycle operations across
// ledger, blockchain, card, and FX rails.
service PaymentExecutionService {
  // InitiatePayments executes all intents within a quote.
  rpc InitiatePayments(InitiatePaymentsRequest) returns (InitiatePaymentsResponse);
  // InitiatePayment creates and executes a single payment.
  rpc InitiatePayment(InitiatePaymentRequest) returns (InitiatePaymentResponse);
  // CancelPayment cancels a pending payment.
  rpc CancelPayment(CancelPaymentRequest) returns (CancelPaymentResponse);
  // GetPayment retrieves a payment by reference.
  rpc GetPayment(GetPaymentRequest) returns (GetPaymentResponse);
  // ListPayments queries payments with filters and pagination.
  rpc ListPayments(ListPaymentsRequest) returns (ListPaymentsResponse);
  // InitiateConversion creates an FX conversion payment.
  rpc InitiateConversion(InitiateConversionRequest) returns (InitiateConversionResponse);
  // ProcessTransferUpdate handles blockchain transfer status callbacks.
  rpc ProcessTransferUpdate(ProcessTransferUpdateRequest) returns (ProcessTransferUpdateResponse);
  // ProcessDepositObserved handles deposit observation callbacks.
  rpc ProcessDepositObserved(ProcessDepositObservedRequest) returns (ProcessDepositObservedResponse);
  // ProcessCardPayoutUpdate handles card payout status callbacks.
  rpc ProcessCardPayoutUpdate(ProcessCardPayoutUpdateRequest) returns (ProcessCardPayoutUpdateResponse);
}