tech/sendico
2
0
Fork 0
Code Issues 32 Pull Requests 2 Actions Packages Projects Releases Wiki Activity

refactored notificatoin / tgsettle responsibility boundaries

Browse Source
This commit is contained in:
Stephan D
2026-02-19 18:56:59 +01:00
parent 47f0a3d890
commit 2fd8a6ebb7
73 changed files with 3705 additions and 681 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
api/proto/payments/endpoint/v1/endpoint.proto
View File

@@ -7,6 +7,7 @@ option go_package = "github.com/tech/sendico/pkg/proto/payments/endpoint/v1;endp
import "api/proto/common/describable/v1/describable.proto";
import "api/proto/common/permission_bound/v1/pbound.proto";
// PaymentMethodType classifies the kind of payment instrument.
enum PaymentMethodType {
PAYMENT_METHOD_TYPE_UNSPECIFIED = 0;
PAYMENT_METHOD_TYPE_IBAN = 1;
@@ -19,6 +20,7 @@ enum PaymentMethodType {
PAYMENT_METHOD_TYPE_ACCOUNT = 8;
}
// PaymentMethod represents a stored payment instrument (card, IBAN, wallet, etc.).
message PaymentMethod {
common.describable.v1.Describable describable = 1;
string recipient_ref = 2;
@@ -27,6 +29,8 @@ message PaymentMethod {
bool is_main = 5;
}
// PaymentEndpoint resolves a payment destination by reference, inline method,
// or payee lookup.
message PaymentEndpoint {
oneof source {
string payment_method_ref = 1;
@@ -35,6 +39,8 @@ message PaymentEndpoint {
}
}
// PaymentMethodRecord wraps a PaymentMethod with its permission and
// persistence metadata.
message PaymentMethodRecord {
common.pbound.v1.PermissionBound permission_bound = 1;
PaymentMethod payment_method = 2;

20
api/proto/payments/methods/v1/methods.proto
View File

@@ -7,25 +7,30 @@ option go_package = "github.com/tech/sendico/pkg/proto/payments/methods/v1;metho
import "api/proto/common/pagination/v2/cursor.proto";
import "api/proto/payments/endpoint/v1/endpoint.proto";
// CreatePaymentMethodRequest is the request to create a new payment method.
message CreatePaymentMethodRequest {
string account_ref = 1;
string organization_ref = 2;
payments.endpoint.v1.PaymentMethod payment_method = 3;
}
// CreatePaymentMethodResponse is the response for CreatePaymentMethod.
message CreatePaymentMethodResponse {
payments.endpoint.v1.PaymentMethodRecord payment_method_record = 1;
}
// GetPaymentMethodRequest is the request to retrieve a payment method.
message GetPaymentMethodRequest {
string account_ref = 1;
string payment_method_ref = 2;
}
// GetPaymentMethodResponse is the response for GetPaymentMethod.
message GetPaymentMethodResponse {
payments.endpoint.v1.PaymentMethodRecord payment_method_record = 1;
}
// GetPaymentMethodPrivateRequest retrieves a payment method without permission checks.
message GetPaymentMethodPrivateRequest {
string organization_ref = 1;
oneof selector {
@@ -35,33 +40,43 @@ message GetPaymentMethodPrivateRequest {
PrivateEndpoint endpoint = 4;
}
// PrivateEndpoint specifies which side of a payment method to retrieve.
enum PrivateEndpoint {
// PRIVATE_ENDPOINT_UNSPECIFIED is the default zero value.
PRIVATE_ENDPOINT_UNSPECIFIED = 0;
// PRIVATE_ENDPOINT_SOURCE retrieves the source endpoint.
PRIVATE_ENDPOINT_SOURCE = 1;
// PRIVATE_ENDPOINT_DESTINATION retrieves the destination endpoint.
PRIVATE_ENDPOINT_DESTINATION = 2;
}
// GetPaymentMethodPrivateResponse is the response for GetPaymentMethodPrivate.
message GetPaymentMethodPrivateResponse {
payments.endpoint.v1.PaymentMethodRecord payment_method_record = 1;
}
// UpdatePaymentMethodRequest is the request to update an existing payment method.
message UpdatePaymentMethodRequest {
string account_ref = 1;
payments.endpoint.v1.PaymentMethodRecord payment_method_record = 2;
}
// UpdatePaymentMethodResponse is the response for UpdatePaymentMethod.
message UpdatePaymentMethodResponse {
payments.endpoint.v1.PaymentMethodRecord payment_method_record = 1;
}
// DeletePaymentMethodRequest is the request to delete a payment method.
message DeletePaymentMethodRequest {
string account_ref = 1;
string payment_method_ref = 2;
bool cascade = 3;
}
// DeletePaymentMethodResponse is the response for DeletePaymentMethod.
message DeletePaymentMethodResponse {}
// SetPaymentMethodArchivedRequest is the request to archive or unarchive a payment method.
message SetPaymentMethodArchivedRequest {
string account_ref = 1;
string organization_ref = 2;
@@ -70,8 +85,10 @@ message SetPaymentMethodArchivedRequest {
bool cascade = 5;
}
// SetPaymentMethodArchivedResponse is the response for SetPaymentMethodArchived.
message SetPaymentMethodArchivedResponse {}
// ListPaymentMethodsRequest is the request to list payment methods with optional filters.
message ListPaymentMethodsRequest {
string account_ref = 1;
string organization_ref = 2;
@@ -79,6 +96,7 @@ message ListPaymentMethodsRequest {
common.pagination.v2.ViewCursor cursor = 4;
}
// ListPaymentMethodsResponse is the response for ListPaymentMethods.
message ListPaymentMethodsResponse {
repeated payments.endpoint.v1.PaymentMethodRecord payment_methods = 1;
}
@@ -91,7 +109,7 @@ service PaymentMethodsService {
rpc GetPaymentMethod(GetPaymentMethodRequest) returns (GetPaymentMethodResponse);
// UpdatePaymentMethod updates an existing payment method.
rpc UpdatePaymentMethod(UpdatePaymentMethodRequest) returns (UpdatePaymentMethodResponse);
// Delete exising payment method
// DeletePaymentMethod deletes an existing payment method.
rpc DeletePaymentMethod(DeletePaymentMethodRequest) returns (DeletePaymentMethodResponse);
// SetPaymentMethodArchived sets the archived status of a payment method.
rpc SetPaymentMethodArchived(SetPaymentMethodArchivedRequest) returns (SetPaymentMethodArchivedResponse);

35
api/proto/payments/orchestration/v1/orchestration.proto
View File

@@ -10,6 +10,8 @@ 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;
@@ -17,10 +19,12 @@ message InitiatePaymentsRequest {
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;
@@ -29,19 +33,23 @@ message InitiatePaymentRequest {
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;
@@ -51,48 +59,63 @@ message ListPaymentsRequest {
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;
@@ -103,18 +126,30 @@ message InitiateConversionRequest {
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);
}

193
api/proto/payments/orchestration/v2/orchestration.proto Normal file
View File

@@ -0,0 +1,193 @@
syntax = "proto3";
package payments.orchestration.v2;
option go_package = "github.com/tech/sendico/pkg/proto/payments/orchestration/v2;orchestrationv2";
import "google/protobuf/timestamp.proto";
import "api/proto/common/gateway/v1/gateway.proto";
import "api/proto/common/pagination/v1/cursor.proto";
import "api/proto/payments/shared/v1/shared.proto";
import "api/proto/payments/quotation/v2/quotation.proto";
import "api/proto/payments/quotation/v2/interface.proto";
// PaymentOrchestratorService executes quotation-backed payments and exposes
// orchestration-focused read APIs.
//
// Notes:
// - Execution input is quotation_ref (not an execution plan).
// - Returned Payment contains immutable quote/intent snapshots, so reads remain
// meaningful after quote storage TTL expiry.
service PaymentOrchestratorService {
// ExecutePayment creates/starts payment execution from an accepted quote.
rpc ExecutePayment(ExecutePaymentRequest) returns (ExecutePaymentResponse);
// GetPayment returns one payment by reference.
rpc GetPayment(GetPaymentRequest) returns (GetPaymentResponse);
// ListPayments returns payments filtered by orchestration lifecycle.
rpc ListPayments(ListPaymentsRequest) returns (ListPaymentsResponse);
}
// ExecutePaymentRequest starts orchestration for one accepted quote.
message ExecutePaymentRequest {
// Organization and trace context; idempotency should be supplied via
// meta.trace.idempotency_key.
payments.shared.v1.RequestMeta meta = 1;
// Required accepted quotation reference.
string quotation_ref = 2;
// Optional caller-side correlation key.
string client_payment_ref = 3;
}
// ExecutePaymentResponse returns the created or deduplicated payment.
message ExecutePaymentResponse {
Payment payment = 1;
}
// GetPaymentRequest fetches one payment by payment_ref.
message GetPaymentRequest {
payments.shared.v1.RequestMeta meta = 1;
string payment_ref = 2;
}
// GetPaymentResponse returns one orchestration payment aggregate.
message GetPaymentResponse {
Payment payment = 1;
}
// ListPaymentsRequest lists payments within the caller organization scope.
message ListPaymentsRequest {
payments.shared.v1.RequestMeta meta = 1;
// Optional state filter. Empty means all states.
repeated OrchestrationState states = 2;
// Optional filter by source quotation.
string quotation_ref = 3;
// Optional creation-time range filter.
// Semantics: created_from is inclusive, created_to is exclusive.
google.protobuf.Timestamp created_from = 4;
google.protobuf.Timestamp created_to = 5;
// Cursor pagination controls.
common.pagination.v1.CursorPageRequest page = 6;
}
// ListPaymentsResponse returns one cursor page of payments.
message ListPaymentsResponse {
repeated Payment payments = 1;
common.pagination.v1.CursorPageResponse page = 2;
}
// Payment is the orchestration runtime aggregate.
// It is designed to be self-contained for post-factum analysis and support.
message Payment {
// Stable payment reference.
string payment_ref = 1;
// Quote used to initiate the payment.
string quotation_ref = 2;
// Immutable snapshot of the execution intent used to create this payment.
payments.quotation.v2.QuoteIntent intent_snapshot = 3;
// Immutable quote snapshot used for execution pricing/route context.
payments.quotation.v2.PaymentQuote quote_snapshot = 4;
string client_payment_ref = 5;
// Current orchestration runtime state.
OrchestrationState state = 6;
// Monotonic aggregate version for optimistic concurrency control.
uint64 version = 7;
// Step-level execution telemetry.
repeated StepExecution step_executions = 8;
// Aggregate timestamps.
google.protobuf.Timestamp created_at = 9;
google.protobuf.Timestamp updated_at = 10;
}
// Kept local on purpose: payments.shared.v1.PaymentState models product-level
// payment lifecycle and does not cover orchestration runtime states.
enum OrchestrationState {
// Default zero value.
ORCHESTRATION_STATE_UNSPECIFIED = 0;
// Payment record created, execution not started yet.
ORCHESTRATION_STATE_CREATED = 1;
// Runtime is actively executing steps.
ORCHESTRATION_STATE_EXECUTING = 2;
// Runtime requires operator/system attention.
ORCHESTRATION_STATE_NEEDS_ATTENTION = 3;
// Execution finished successfully.
ORCHESTRATION_STATE_SETTLED = 4;
// Execution reached terminal failure.
ORCHESTRATION_STATE_FAILED = 5;
}
// StepExecution is telemetry for one orchestration step attempt stream.
message StepExecution {
// Stable step reference inside orchestration runtime.
string step_ref = 1;
// Logical step code/type label (planner/executor-defined).
string step_code = 2;
// Current state of this step.
StepExecutionState state = 3;
// Monotonic attempt number, starts at 1.
uint32 attempt = 4;
// Step timing.
google.protobuf.Timestamp started_at = 5;
google.protobuf.Timestamp completed_at = 6;
// Failure details when state is FAILED/NEEDS_ATTENTION.
Failure failure = 7;
// External references produced by the step.
repeated ExternalReference refs = 8;
}
// Kept local on purpose: no shared enum exists for orchestration step runtime.
enum StepExecutionState {
// Default zero value.
STEP_EXECUTION_STATE_UNSPECIFIED = 0;
// Not started yet.
STEP_EXECUTION_STATE_PENDING = 1;
// Currently running.
STEP_EXECUTION_STATE_RUNNING = 2;
// Finished successfully.
STEP_EXECUTION_STATE_COMPLETED = 3;
// Finished with terminal error.
STEP_EXECUTION_STATE_FAILED = 4;
// Blocked and requires attention/intervention.
STEP_EXECUTION_STATE_NEEDS_ATTENTION = 5;
// Not executed because it became irrelevant/unreachable.
STEP_EXECUTION_STATE_SKIPPED = 6;
}
// Failure describes a normalized step failure.
message Failure {
// Broad, shared failure category.
payments.shared.v1.PaymentFailureCode category = 1;
// Machine-readable, executor-specific code.
string code = 2;
// Human-readable message.
string message = 3;
}
// ExternalReference links step execution to external systems/operations.
message ExternalReference {
// Rail where external side effect happened.
common.gateway.v1.Rail rail = 1;
// Gateway instance that owns the referenced operation/entity.
// This is the discovery key for fetching details on demand.
string gateway_instance_id = 2;
// Reference classifier. Keep values stable and namespaced:
// e.g. "ledger.journal", "ledger.hold", "chain.tx", "provider.payout".
string kind = 3;
// External operation/entity reference id in the owner system.
string ref = 4;
}

12
api/proto/payments/payment/v1/payment.proto
View File

@@ -6,15 +6,15 @@ option go_package = "github.com/tech/sendico/pkg/proto/payments/payment/v1;payme
import "api/proto/payments/transfer/v1/transfer.proto";
// -------------------------
// External payment semantics
// -------------------------
// PaymentIntent describes the full intent for an external payment,
// wrapping a transfer with payer/payee identity and purpose.
message PaymentIntent {
// transfer is the underlying value movement.
payments.transfer.v1.TransferIntent transfer = 1;
// payer_ref identifies the entity funding the payment.
string payer_ref = 2;
// payee_ref identifies the payment beneficiary.
string payee_ref = 3;
// purpose is a human-readable description of the payment reason.
string purpose = 4;
}

6
api/proto/payments/quotation/v1/quotation.proto
View File

@@ -6,7 +6,7 @@ option go_package = "github.com/tech/sendico/pkg/proto/payments/quotation/v1;quo
import "api/proto/payments/shared/v1/shared.proto";
// QuotePaymentRequest is the request to quote a single payment.
message QuotePaymentRequest {
payments.shared.v1.RequestMeta meta = 1;
string idempotency_key = 2;
@@ -14,6 +14,7 @@ message QuotePaymentRequest {
bool preview_only = 4;
}
// QuotePaymentResponse is the response for QuotePayment.
message QuotePaymentResponse {
payments.shared.v1.PaymentQuote quote = 1;
string idempotency_key = 2;
@@ -21,6 +22,7 @@ message QuotePaymentResponse {
string execution_note = 3;
}
// QuotePaymentsRequest is the request to quote multiple payments in a batch.
message QuotePaymentsRequest {
payments.shared.v1.RequestMeta meta = 1;
string idempotency_key = 2;
@@ -28,6 +30,7 @@ message QuotePaymentsRequest {
bool preview_only = 4;
}
// QuotePaymentsResponse is the response for QuotePayments.
message QuotePaymentsResponse {
string quote_ref = 1;
payments.shared.v1.PaymentQuoteAggregate aggregate = 2;
@@ -35,6 +38,7 @@ message QuotePaymentsResponse {
string idempotency_key = 4;
}
// QuotationService provides payment quoting capabilities.
service QuotationService {
// QuotePayment returns a quote for a single payment request.
rpc QuotePayment(QuotePaymentRequest) returns (QuotePaymentResponse);

8
api/proto/payments/quotation/v2/interface.proto
View File

@@ -12,6 +12,7 @@ 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;
@@ -20,6 +21,7 @@ enum QuoteState {
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;
@@ -31,6 +33,7 @@ enum QuoteBlockReason {
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;
@@ -38,6 +41,7 @@ enum QuoteExecutionReadiness {
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;
@@ -45,12 +49,14 @@ enum RouteHopRole {
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;
@@ -60,6 +66,7 @@ message RouteHop {
RouteHopRole role = 6;
}
// RouteSettlement describes the settlement asset and model for a route.
message RouteSettlement {
common.payment.v1.ChainAsset asset = 1;
string model = 2;
@@ -91,6 +98,7 @@ message ExecutionConditions {
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;

11
api/proto/payments/quotation/v2/quotation.proto
View File

@@ -10,6 +10,7 @@ import "api/proto/common/payment/v1/settlement.proto";
import "api/proto/payments/endpoint/v1/endpoint.proto";
import "api/proto/payments/quotation/v2/interface.proto";
// QuoteIntent describes the intent behind a v2 quote request.
message QuoteIntent {
payments.endpoint.v1.PaymentEndpoint source = 1;
payments.endpoint.v1.PaymentEndpoint destination = 2;
@@ -20,34 +21,38 @@ message QuoteIntent {
string comment = 7;
}
// QuotePaymentRequest is the request to quote a single v2 payment.
message QuotePaymentRequest {
payments.shared.v1.RequestMeta meta = 1;
string idempotency_key = 2;
payments.quotation.v2.QuoteIntent intent = 3;
bool preview_only = 4;
string initiator_ref = 5;
string initiator_ref = 5;
}
// QuotePaymentResponse is the response for QuotePayment.
message QuotePaymentResponse {
payments.quotation.v2.PaymentQuote quote = 1;
string idempotency_key = 2;
}
// QuotePaymentsRequest is the request to quote multiple v2 payments in a batch.
message QuotePaymentsRequest {
payments.shared.v1.RequestMeta meta = 1;
string idempotency_key = 2;
repeated payments.quotation.v2.QuoteIntent intents = 3;
bool preview_only = 4;
string initiator_ref = 5;
string initiator_ref = 5;
}
// QuotePaymentsResponse is the response for QuotePayments.
message QuotePaymentsResponse {
string quote_ref = 1;
repeated payments.quotation.v2.PaymentQuote quotes = 3;
string idempotency_key = 4;
}
// Quotation service interface
// QuotationService provides v2 payment quoting capabilities.
service QuotationService {
// QuotePayment returns a quote for a single payment request.
rpc QuotePayment(QuotePaymentRequest) returns (QuotePaymentResponse);

26
api/proto/payments/shared/v1/shared.proto
View File

@@ -14,6 +14,7 @@ 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;
@@ -21,6 +22,7 @@ enum PaymentKind {
PAYMENT_KIND_FX_CONVERSION = 3;
}
// PaymentState tracks the lifecycle of a payment.
enum PaymentState {
PAYMENT_STATE_UNSPECIFIED = 0;
PAYMENT_STATE_ACCEPTED = 1;
@@ -31,6 +33,7 @@ enum PaymentState {
PAYMENT_STATE_CANCELLED = 6;
}
// PaymentFailureCode categorises the reason for a payment failure.
enum PaymentFailureCode {
FAILURE_UNSPECIFIED = 0;
FAILURE_BALANCE = 1;
@@ -41,21 +44,26 @@ enum PaymentFailureCode {
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;
@@ -76,6 +84,7 @@ message CardEndpoint {
string masked_pan = 8;
}
// PaymentEndpoint is a polymorphic endpoint that can target any supported rail.
message PaymentEndpoint {
oneof endpoint {
LedgerEndpoint ledger = 1;
@@ -87,6 +96,7 @@ message PaymentEndpoint {
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;
@@ -96,6 +106,8 @@ message FXIntent {
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;
@@ -111,6 +123,8 @@ message PaymentIntent {
string ref = 12;
}
// Customer holds payer identity and address details for compliance and
// routing purposes.
message Customer {
string id = 1;
string first_name = 2;
@@ -124,6 +138,8 @@ message Customer {
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;
@@ -136,6 +152,7 @@ message PaymentQuote {
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;
@@ -143,6 +160,8 @@ message PaymentQuoteAggregate {
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;
@@ -152,6 +171,7 @@ message ExecutionRefs {
string fee_transfer_ref = 6;
}
// ExecutionStep describes a single operational step in the legacy execution plan.
message ExecutionStep {
string code = 1;
string description = 2;
@@ -164,11 +184,13 @@ message ExecutionStep {
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
@@ -181,6 +203,8 @@ message PaymentStep {
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;
@@ -202,6 +226,8 @@ message CardPayout {
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;

10
api/proto/payments/transfer/v1/transfer.proto
View File

@@ -7,14 +7,14 @@ option go_package = "github.com/tech/sendico/pkg/proto/payments/transfer/v1;tran
import "api/proto/common/money/v1/money.proto";
import "api/proto/payments/endpoint/v1/endpoint.proto";
// -------------------------
// Base value movement
// -------------------------
// TransferIntent describes a value movement between two payment endpoints.
message TransferIntent {
// source is the originating payment endpoint.
payments.endpoint.v1.PaymentEndpoint source = 1;
// destination is the receiving payment endpoint.
payments.endpoint.v1.PaymentEndpoint destination = 2;
// amount is the monetary value to transfer.
common.money.v1.Money amount = 3;
// comment is an optional human-readable note for the transfer.
string comment = 4;
}