tech/sendico
2
0
Fork 0
Code Issues 30 Pull Requests 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

3
api/proto/account_created.proto
View File

@@ -2,7 +2,10 @@ syntax = "proto3";
option go_package = "github.com/tech/sendico/pkg/generated/gmessaging";
// AccountCreatedEvent is published when a new user account is registered.
message AccountCreatedEvent {
// account_ref is the unique reference of the newly created account.
string account_ref = 1;
// verification_token is the one-time token used to verify the email address.
string verification_token = 2;
}

4
api/proto/billing/fees/v1/fees.proto
View File

@@ -43,6 +43,7 @@ message RequestMeta {
common.trace.v1.TraceContext trace = 2;
}
// ResponseMeta carries tracing context for fee engine responses.
message ResponseMeta {
common.trace.v1.TraceContext trace = 1;
}
@@ -101,6 +102,7 @@ message QuoteFeesRequest {
PolicyOverrides policy = 3;
}
// QuoteFeesResponse returns derived fee lines and the rules that produced them.
message QuoteFeesResponse {
ResponseMeta meta = 1;
repeated DerivedPostingLine lines = 2; // derived fee/tax/spread lines
@@ -117,6 +119,7 @@ message PrecomputeFeesRequest {
int64 ttl_ms = 3; // token validity window
}
// PrecomputeFeesResponse returns a signed fee token and optional preview lines.
message PrecomputeFeesResponse {
ResponseMeta meta = 1;
string fee_quote_token = 2; // opaque, signed
@@ -135,6 +138,7 @@ message ValidateFeeTokenRequest {
string fee_quote_token = 2;
}
// ValidateFeeTokenResponse returns the validation result and embedded fee data.
message ValidateFeeTokenResponse {
ResponseMeta meta = 1;
bool valid = 2;

7
api/proto/common/gateway/v1/gateway.proto
View File

@@ -7,7 +7,8 @@ option go_package = "github.com/tech/sendico/pkg/proto/common/gateway/v1;gateway
import "api/proto/common/money/v1/money.proto";
import "api/proto/payments/endpoint/v1/endpoint.proto";
// Operation enumerates gateway-level operations that can be performed on a
// payment method.
enum Operation {
OPERATION_UNSPECIFIED = 0;
OPERATION_AUTHORIZE = 1;
@@ -126,6 +127,7 @@ message RailCapabilities {
bool can_release = 7;
}
// LimitsOverride provides per-currency overrides for global limit settings.
message LimitsOverride {
string max_volume = 1;
string min_amount = 2;
@@ -166,6 +168,7 @@ enum OperationResult {
OPERATION_RESULT_CANCELLED = 3;
}
// OperationError describes a failure returned by a gateway operation.
message OperationError {
string code = 1;
string message = 2;
@@ -173,6 +176,8 @@ message OperationError {
bool should_rollback = 4;
}
// OperationExecutionStatus reports the result of executing a single gateway
// operation, including the settled amount and any error.
message OperationExecutionStatus {
string idempotency_key = 1;
string operation_ref = 2;

27
api/proto/common/payment/v1/card.proto
View File

@@ -4,10 +4,7 @@ package common.payment.v1;
option go_package = "github.com/tech/sendico/pkg/proto/common/payment/v1;paymentv1";
// -------------------------
// Card network (payment system)
// -------------------------
// CardNetwork identifies a card payment network (scheme).
enum CardNetwork {
CARD_NETWORK_UNSPECIFIED = 0;
CARD_NETWORK_VISA = 1;
@@ -19,6 +16,7 @@ enum CardNetwork {
CARD_NETWORK_DISCOVER = 7;
}
// CardFundingType classifies the funding source behind a card.
enum CardFundingType {
CARD_FUNDING_UNSPECIFIED = 0;
CARD_FUNDING_DEBIT = 1;
@@ -26,10 +24,8 @@ enum CardFundingType {
CARD_FUNDING_PREPAID = 3;
}
// -------------------------
// PCI scope: raw card details
// -------------------------
// RawCardData carries PCI-scope card credentials for tokenisation or
// direct processing.
message RawCardData {
string pan = 1;
uint32 exp_month = 2; // 1–12
@@ -37,10 +33,8 @@ message RawCardData {
string cvv = 4; // optional; often omitted for payouts
}
// -------------------------
// Safe metadata (display / routing hints)
// -------------------------
// CardMetadata holds non-sensitive display and routing hints derived from
// card details.
message CardMetadata {
string masked_pan = 1; // e.g. 411111******1111
CardNetwork network = 2; // Visa/Mastercard/Mir/...
@@ -49,11 +43,8 @@ message CardMetadata {
string issuer_name = 5; // display only (if known)
}
// -------------------------
// Card details
// Either inline credentials OR reference to stored payment method
// -------------------------
// CardDetails provides card credentials for a payment operation, either
// as inline raw data or a reference to a stored payment method.
message CardDetails {
string id = 1;
@@ -67,5 +58,3 @@ message CardDetails {
string billing_country = 6; // ISO 3166-1 alpha-2, if you need it per operation
}

7
api/proto/common/payment/v1/custom.proto
View File

@@ -4,8 +4,11 @@ package common.payment.v1;
option go_package = "github.com/tech/sendico/pkg/proto/common/payment/v1;paymentv1";
// CustomPaymentDetails carries an opaque, gateway-specific payment method
// encoded as JSON bytes.
message CustomPaymentDetails {
// id is the unique identifier for this payment method instance.
string id = 1;
// payment_method_json is the raw JSON payload understood by the target gateway.
bytes payment_method_json = 2;
}
}

8
api/proto/common/payment/v1/external_chain.proto
View File

@@ -6,11 +6,15 @@ option go_package = "github.com/tech/sendico/pkg/proto/common/payment/v1;payment
import "api/proto/gateway/chain/v1/chain.proto";
// ExternalChainDetails describes an external blockchain address as a
// payment endpoint.
message ExternalChainDetails {
// id is the unique identifier for this endpoint instance.
string id = 1;
// asset identifies the on-chain token (network + symbol + contract).
chain.gateway.v1.Asset asset = 2;
// address is the destination blockchain address.
string address = 3;
// memo is an optional transfer memo or tag required by some chains.
string memo = 4;
}

5
api/proto/common/payment/v1/ledger.proto
View File

@@ -4,11 +4,14 @@ package common.payment.v1;
option go_package = "github.com/tech/sendico/pkg/proto/common/payment/v1;paymentv1";
// LedgerDetails identifies an internal ledger account as a payment endpoint.
message LedgerDetails {
// id is the unique identifier for this endpoint instance.
string id = 1;
oneof source {
// ledger_account_ref is the direct ledger account reference.
string ledger_account_ref = 2;
// account_code is a human-readable account code resolved at runtime.
string account_code = 3;
}
}

7
api/proto/common/payment/v1/managed_wallet.proto
View File

@@ -4,8 +4,11 @@ package common.payment.v1;
option go_package = "github.com/tech/sendico/pkg/proto/common/payment/v1;paymentv1";
// ManagedWalletDetails identifies a platform-managed blockchain wallet as a
// payment endpoint.
message ManagedWalletDetails {
// id is the unique identifier for this endpoint instance.
string id = 1;
// managed_wallet_ref is the reference to the managed wallet record.
string managed_wallet_ref = 2;
}
}

14
api/proto/common/payment/v1/rba.proto
View File

@@ -4,13 +4,15 @@ package common.payment.v1;
option go_package = "github.com/tech/sendico/pkg/proto/common/payment/v1;paymentv1";
// -------------------------
// Russian bank account details
// -------------------------
// RussianBankDetails carries Russian domestic bank account information for
// RUB payouts.
message RussianBankDetails {
// id is the unique identifier for this endpoint instance.
string id = 1;
string account_number = 2; // 20 digits
string bik = 3; // 9 digits
// account_number is the 20-digit Russian bank account number.
string account_number = 2;
// bik is the 9-digit Russian bank identification code.
string bik = 3;
// account_holder_name is the full name of the account holder.
string account_holder_name = 4;
}

14
api/proto/common/payment/v1/sepa.proto
View File

@@ -4,14 +4,14 @@ package common.payment.v1;
option go_package = "github.com/tech/sendico/pkg/proto/common/payment/v1;paymentv1";
// -------------------------
// SEPA bank account details
// -------------------------
// SepaBankDetails carries SEPA bank account information for EUR transfers.
message SepaBankDetails {
// id is the unique identifier for this endpoint instance.
string id = 1;
string iban = 2; // IBAN
string bic = 3; // optional (BIC/SWIFT)
// iban is the International Bank Account Number.
string iban = 2;
// bic is the optional BIC/SWIFT code.
string bic = 3;
// account_holder_name is the full name of the account holder.
string account_holder_name = 4;
}

1
api/proto/common/storable/v1/storable.proto
View File

@@ -7,6 +7,7 @@ option go_package = "github.com/tech/sendico/pkg/proto/common/storable/v1;storab
import "google/protobuf/timestamp.proto";
// Storable carries common persistence metadata (ID and timestamps).
message Storable {
string id = 1;
google.protobuf.Timestamp created_at = 10;

23
api/proto/envelope.proto
View File

@@ -4,19 +4,30 @@ import "google/protobuf/timestamp.proto";
option go_package = "github.com/tech/sendico/pkg/generated/gmessaging";
// NotificationEvent identifies the type and action of an event for routing.
message NotificationEvent {
string type = 1; // NotificationType
string action = 2; // NotificationAction
// type is the notification category (e.g. "payment", "account").
string type = 1;
// action is the specific event action (e.g. "created", "settled").
string action = 2;
}
// EventMetadata carries provenance information for a published event.
message EventMetadata {
// sender identifies the originating service.
string sender = 1;
string message_id = 2;
// message_id is the unique identifier of this event message.
string message_id = 2;
// timestamp is the time the event was published.
google.protobuf.Timestamp timestamp = 3;
}
// Envelope wraps a serialised event payload with routing and metadata.
message Envelope {
NotificationEvent event = 2; // Notification event with type and action
bytes message_data = 3; // Serialized Protobuf message data
EventMetadata metadata = 4; // Metadata about the event
// event describes the notification type and action for routing.
NotificationEvent event = 2;
// message_data is the serialised protobuf payload.
bytes message_data = 3;
// metadata carries provenance information about the event.
EventMetadata metadata = 4;
}

47
api/proto/gateway/chain/v1/chain.proto
View File

@@ -12,29 +12,47 @@ import "api/proto/common/describable/v1/describable.proto";
// Supported blockchain networks for the managed wallets.
enum ChainNetwork {
// CHAIN_NETWORK_UNSPECIFIED is the default zero value.
CHAIN_NETWORK_UNSPECIFIED = 0;
// CHAIN_NETWORK_ETHEREUM_MAINNET is Ethereum layer-1 mainnet.
CHAIN_NETWORK_ETHEREUM_MAINNET = 1;
// CHAIN_NETWORK_ARBITRUM_ONE is the Arbitrum One rollup.
CHAIN_NETWORK_ARBITRUM_ONE = 2;
// CHAIN_NETWORK_TRON_MAINNET is the TRON mainnet.
CHAIN_NETWORK_TRON_MAINNET = 4;
// CHAIN_NETWORK_TRON_NILE is the TRON Nile testnet.
CHAIN_NETWORK_TRON_NILE = 5;
// CHAIN_NETWORK_ARBITRUM_SEPOLIA is the Arbitrum Sepolia testnet.
CHAIN_NETWORK_ARBITRUM_SEPOLIA = 6;
}
// ManagedWalletStatus represents the lifecycle state of a managed wallet.
enum ManagedWalletStatus {
// MANAGED_WALLET_STATUS_UNSPECIFIED is the default zero value.
MANAGED_WALLET_STATUS_UNSPECIFIED = 0;
// MANAGED_WALLET_ACTIVE means the wallet is open and operational.
MANAGED_WALLET_ACTIVE = 1;
// MANAGED_WALLET_SUSPENDED means the wallet is temporarily disabled.
MANAGED_WALLET_SUSPENDED = 2;
// MANAGED_WALLET_CLOSED means the wallet is permanently closed.
MANAGED_WALLET_CLOSED = 3;
}
// DepositStatus tracks the confirmation state of an inbound deposit.
enum DepositStatus {
// DEPOSIT_STATUS_UNSPECIFIED is the default zero value.
DEPOSIT_STATUS_UNSPECIFIED = 0;
// DEPOSIT_PENDING means the deposit has been observed but not yet confirmed.
DEPOSIT_PENDING = 1;
// DEPOSIT_CONFIRMED means the deposit has been confirmed on-chain.
DEPOSIT_CONFIRMED = 2;
// DEPOSIT_FAILED means the deposit could not be confirmed.
DEPOSIT_FAILED = 3;
}
// TransferStatus tracks the lifecycle of an outbound transfer.
enum TransferStatus {
// TRANSFER_STATUS_UNSPECIFIED is the default zero value.
TRANSFER_STATUS_UNSPECIFIED = 0;
TRANSFER_CREATED = 1; // record exists, not started
@@ -54,6 +72,7 @@ message Asset {
string contract_address = 3; // optional override when multiple contracts exist per chain
}
// ManagedWallet represents a platform-managed blockchain wallet.
message ManagedWallet {
string wallet_ref = 1;
string organization_ref = 2;
@@ -67,6 +86,7 @@ message ManagedWallet {
common.describable.v1.Describable describable = 10;
}
// CreateManagedWalletRequest is the request to create a new managed wallet.
message CreateManagedWalletRequest {
string idempotency_key = 1;
string organization_ref = 2;
@@ -76,18 +96,22 @@ message CreateManagedWalletRequest {
common.describable.v1.Describable describable = 6;
}
// CreateManagedWalletResponse is the response for CreateManagedWallet.
message CreateManagedWalletResponse {
ManagedWallet wallet = 1;
}
// GetManagedWalletRequest is the request to retrieve a wallet by reference.
message GetManagedWalletRequest {
string wallet_ref = 1;
}
// GetManagedWalletResponse is the response for GetManagedWallet.
message GetManagedWalletResponse {
ManagedWallet wallet = 1;
}
// ListManagedWalletsRequest is the request to list wallets with optional filters.
message ListManagedWalletsRequest {
string organization_ref = 1;
reserved 2;
@@ -101,11 +125,13 @@ message ListManagedWalletsRequest {
google.protobuf.StringValue owner_ref_filter = 5;
}
// ListManagedWalletsResponse is the response for ListManagedWallets.
message ListManagedWalletsResponse {
repeated ManagedWallet wallets = 1;
common.pagination.v1.CursorPageResponse page = 2;
}
// WalletBalance holds the balance breakdown for a managed wallet.
message WalletBalance {
common.money.v1.Money available = 1;
common.money.v1.Money pending_inbound = 2;
@@ -114,20 +140,24 @@ message WalletBalance {
common.money.v1.Money native_available = 5;
}
// GetWalletBalanceRequest is the request to retrieve a wallet's balance.
message GetWalletBalanceRequest {
string wallet_ref = 1;
}
// GetWalletBalanceResponse is the response for GetWalletBalance.
message GetWalletBalanceResponse {
WalletBalance balance = 1;
}
// ServiceFeeBreakdown describes a single fee line item applied to a transfer.
message ServiceFeeBreakdown {
string fee_code = 1;
common.money.v1.Money amount = 2;
string description = 3;
}
// TransferDestination identifies where a transfer should be sent.
message TransferDestination {
oneof destination {
string managed_wallet_ref = 1;
@@ -136,6 +166,7 @@ message TransferDestination {
string memo = 3; // chain-specific memo/tag when required by the destination
}
// Transfer represents an outbound blockchain transfer.
message Transfer {
string transfer_ref = 1;
string idempotency_key = 2;
@@ -156,6 +187,7 @@ message Transfer {
string operation_ref = 17;
}
// SubmitTransferRequest is the request to submit an outbound transfer.
message SubmitTransferRequest {
string idempotency_key = 1;
string organization_ref = 2;
@@ -169,18 +201,22 @@ message SubmitTransferRequest {
string payment_ref = 10;
}
// SubmitTransferResponse is the response for SubmitTransfer.
message SubmitTransferResponse {
Transfer transfer = 1;
}
// GetTransferRequest is the request to retrieve a transfer by reference.
message GetTransferRequest {
string transfer_ref = 1;
}
// GetTransferResponse is the response for GetTransfer.
message GetTransferResponse {
Transfer transfer = 1;
}
// ListTransfersRequest is the request to list transfers with optional filters.
message ListTransfersRequest {
string source_wallet_ref = 1;
string destination_wallet_ref = 2;
@@ -188,11 +224,13 @@ message ListTransfersRequest {
common.pagination.v1.CursorPageRequest page = 4;
}
// ListTransfersResponse is the response for ListTransfers.
message ListTransfersResponse {
repeated Transfer transfers = 1;
common.pagination.v1.CursorPageResponse page = 2;
}
// EstimateTransferFeeRequest is the request to estimate network fees for a transfer.
message EstimateTransferFeeRequest {
string source_wallet_ref = 1;
TransferDestination destination = 2;
@@ -200,21 +238,25 @@ message EstimateTransferFeeRequest {
Asset asset = 4;
}
// EstimateTransferFeeResponse is the response for EstimateTransferFee.
message EstimateTransferFeeResponse {
common.money.v1.Money network_fee = 1;
string estimation_context = 2;
}
// ComputeGasTopUpRequest is the request to calculate the gas top-up needed.
message ComputeGasTopUpRequest {
string wallet_ref = 1;
common.money.v1.Money estimated_total_fee = 2;
}
// ComputeGasTopUpResponse is the response for ComputeGasTopUp.
message ComputeGasTopUpResponse {
common.money.v1.Money topup_amount = 1;
bool cap_hit = 2;
}
// EnsureGasTopUpRequest is the request to top up gas for a wallet if needed.
message EnsureGasTopUpRequest {
string idempotency_key = 1;
string organization_ref = 2;
@@ -227,12 +269,14 @@ message EnsureGasTopUpRequest {
string operation_ref = 9;
}
// EnsureGasTopUpResponse is the response for EnsureGasTopUp.
message EnsureGasTopUpResponse {
common.money.v1.Money topup_amount = 1;
bool cap_hit = 2;
Transfer transfer = 3;
}
// WalletDepositObservedEvent is emitted when a deposit is detected on-chain.
message WalletDepositObservedEvent {
string deposit_ref = 1;
string wallet_ref = 2;
@@ -245,7 +289,8 @@ message WalletDepositObservedEvent {
google.protobuf.Timestamp observed_at = 9;
}
// TransferStatusChangedEvent is emitted when a transfer changes status.
message TransferStatusChangedEvent {
Transfer transfer = 1;
string reason = 2;
string reason = 2;
}

4
api/proto/gateway/mntx/v1/mntx.proto
View File

@@ -72,10 +72,12 @@ message CardPayoutResponse {
string error_message = 5;
}
// GetCardPayoutStatusRequest fetches the current status of a payout.
message GetCardPayoutStatusRequest {
string payout_id = 1;
}
// GetCardPayoutStatusResponse returns the current payout state.
message GetCardPayoutStatusResponse {
CardPayoutState payout = 1;
}
@@ -85,8 +87,10 @@ message CardPayoutStatusChangedEvent {
CardPayoutState payout = 1;
}
// ListGatewayInstancesRequest requests all registered gateway instances.
message ListGatewayInstancesRequest {}
// ListGatewayInstancesResponse returns the available gateway instances.
message ListGatewayInstancesResponse {
repeated common.gateway.v1.GatewayInstanceDescriptor items = 1;
}

56
api/proto/ledger/v1/ledger.proto
View File

@@ -11,51 +11,89 @@ import "api/proto/common/money/v1/money.proto";
// ===== Enums =====
// EntryType classifies the kind of journal entry.
enum EntryType {
// ENTRY_TYPE_UNSPECIFIED is the default zero value.
ENTRY_TYPE_UNSPECIFIED = 0;
// ENTRY_CREDIT records an inbound credit.
ENTRY_CREDIT = 1;
// ENTRY_DEBIT records an outbound debit.
ENTRY_DEBIT = 2;
// ENTRY_TRANSFER records a transfer between accounts.
ENTRY_TRANSFER = 3;
// ENTRY_FX records a foreign-exchange conversion.
ENTRY_FX = 4;
// ENTRY_FEE records a fee charge.
ENTRY_FEE = 5;
// ENTRY_ADJUST records a manual adjustment.
ENTRY_ADJUST = 6;
// ENTRY_REVERSE records a reversal of a prior entry.
ENTRY_REVERSE = 7;
}
// LineType classifies the purpose of a posting line within an entry.
enum LineType {
// LINE_TYPE_UNSPECIFIED is the default zero value.
LINE_TYPE_UNSPECIFIED = 0;
// LINE_MAIN is the primary posting line.
LINE_MAIN = 1;
// LINE_FEE is a fee posting line.
LINE_FEE = 2;
// LINE_SPREAD is an FX spread posting line.
LINE_SPREAD = 3;
// LINE_REVERSAL is a reversal posting line.
LINE_REVERSAL = 4;
}
// AccountType classifies the fundamental accounting type of an account.
enum AccountType {
// ACCOUNT_TYPE_UNSPECIFIED is the default zero value.
ACCOUNT_TYPE_UNSPECIFIED = 0;
// ACCOUNT_TYPE_ASSET represents an asset account.
ACCOUNT_TYPE_ASSET = 1;
// ACCOUNT_TYPE_LIABILITY represents a liability account.
ACCOUNT_TYPE_LIABILITY = 2;
// ACCOUNT_TYPE_REVENUE represents a revenue account.
ACCOUNT_TYPE_REVENUE = 3;
// ACCOUNT_TYPE_EXPENSE represents an expense account.
ACCOUNT_TYPE_EXPENSE = 4;
}
// AccountStatus indicates whether an account is active or frozen.
enum AccountStatus {
// ACCOUNT_STATUS_UNSPECIFIED is the default zero value.
ACCOUNT_STATUS_UNSPECIFIED = 0;
// ACCOUNT_STATUS_ACTIVE means the account accepts postings.
ACCOUNT_STATUS_ACTIVE = 1;
// ACCOUNT_STATUS_FROZEN means the account is blocked from new postings.
ACCOUNT_STATUS_FROZEN = 2;
}
// AccountRole defines the functional role of an account within an organization.
enum AccountRole {
// ACCOUNT_ROLE_UNSPECIFIED is the default zero value.
ACCOUNT_ROLE_UNSPECIFIED = 0;
// ACCOUNT_ROLE_OPERATING is the main operating account.
ACCOUNT_ROLE_OPERATING = 1;
// ACCOUNT_ROLE_HOLD is a temporary hold account.
ACCOUNT_ROLE_HOLD = 2;
// ACCOUNT_ROLE_TRANSIT is an in-transit account.
ACCOUNT_ROLE_TRANSIT = 3;
// ACCOUNT_ROLE_SETTLEMENT is a settlement account.
ACCOUNT_ROLE_SETTLEMENT = 4;
// ACCOUNT_ROLE_CLEARING is a clearing account.
ACCOUNT_ROLE_CLEARING = 5;
// ACCOUNT_ROLE_PENDING is a pending-settlement account.
ACCOUNT_ROLE_PENDING = 6;
// ACCOUNT_ROLE_RESERVE is a reserve account.
ACCOUNT_ROLE_RESERVE = 7;
// ACCOUNT_ROLE_LIQUIDITY is a liquidity pool account.
ACCOUNT_ROLE_LIQUIDITY = 8;
// ACCOUNT_ROLE_FEE is a fee collection account.
ACCOUNT_ROLE_FEE = 9;
// ACCOUNT_ROLE_CHARGEBACK is a chargeback account.
ACCOUNT_ROLE_CHARGEBACK = 10;
// ACCOUNT_ROLE_ADJUSTMENT is an adjustment account.
ACCOUNT_ROLE_ADJUSTMENT = 11;
}
@@ -87,6 +125,7 @@ message PostingLine {
// ===== Requests/Responses =====
// CreateAccountRequest is the request to create a new ledger account.
message CreateAccountRequest {
string organization_ref = 1;
string owner_ref = 2;
@@ -103,6 +142,7 @@ message CreateAccountRequest {
AccountRole role = 11;
}
// CreateAccountResponse is the response for CreateAccount.
message CreateAccountResponse {
LedgerAccount account = 1;
}
@@ -121,6 +161,7 @@ message PostCreditRequest {
AccountRole role = 10; // optional: assert target account has this role
}
// PostDebitRequest is the request to post a debit entry.
message PostDebitRequest {
string idempotency_key = 1;
string organization_ref = 2;
@@ -134,6 +175,7 @@ message PostDebitRequest {
AccountRole role = 10; // optional: assert target account has this role
}
// TransferRequest is the request to transfer funds between two ledger accounts.
message TransferRequest {
string idempotency_key = 1;
string organization_ref = 2;
@@ -148,6 +190,7 @@ message TransferRequest {
AccountRole to_role = 11;
}
// FXRequest is the request to post a foreign-exchange conversion entry.
message FXRequest {
string idempotency_key = 1;
string organization_ref = 2;
@@ -164,6 +207,7 @@ message FXRequest {
google.protobuf.Timestamp event_time = 11;
}
// PostResponse is the common response returned after any posting operation.
message PostResponse {
string journal_entry_ref = 1;
int64 version = 2; // ledger's entry version (monotonic per scope)
@@ -172,10 +216,12 @@ message PostResponse {
// ---- Balances & Entries ----
// GetBalanceRequest is the request to retrieve an account balance.
message GetBalanceRequest {
string ledger_account_ref = 1;
}
// BalanceResponse holds the current balance of a ledger account.
message BalanceResponse {
string ledger_account_ref = 1;
common.money.v1.Money balance = 2;
@@ -183,10 +229,12 @@ message BalanceResponse {
google.protobuf.Timestamp last_updated = 4;
}
// GetEntryRequest is the request to retrieve a journal entry by reference.
message GetEntryRequest {
string entry_ref = 1;
}
// JournalEntryResponse represents a complete journal entry with all posting lines.
message JournalEntryResponse {
string entry_ref = 1;
string idempotency_key = 2;
@@ -199,17 +247,20 @@ message JournalEntryResponse {
repeated string ledger_account_refs = 9; // denormalized set for client-side filtering
}
// GetStatementRequest is the request to retrieve paginated journal entries for an account.
message GetStatementRequest {
string ledger_account_ref = 1;
string cursor = 2; // opaque
int32 limit = 3; // page size
}
// StatementResponse is a paginated list of journal entries.
message StatementResponse {
repeated JournalEntryResponse entries = 1;
string next_cursor = 2;
}
// ListAccountsRequest is the request to list ledger accounts with optional filters.
message ListAccountsRequest {
string organization_ref = 1;
// Optional owner filter with 3-state semantics:
@@ -219,28 +270,33 @@ message ListAccountsRequest {
google.protobuf.StringValue owner_ref_filter = 2;
}
// ListAccountsResponse is the response for ListAccounts.
message ListAccountsResponse {
repeated LedgerAccount accounts = 1;
}
// ---- Account status mutations ----
// BlockAccountRequest is the request to freeze (block) a ledger account.
message BlockAccountRequest {
string ledger_account_ref = 1;
string organization_ref = 2;
AccountRole role = 3; // optional: assert account has this role before blocking
}
// BlockAccountResponse is the response for BlockAccount.
message BlockAccountResponse {
LedgerAccount account = 1;
}
// UnblockAccountRequest is the request to unfreeze (unblock) a ledger account.
message UnblockAccountRequest {
string ledger_account_ref = 1;
string organization_ref = 2;
AccountRole role = 3; // optional: assert account has this role before unblocking
}
// UnblockAccountResponse is the response for UnblockAccount.
message UnblockAccountResponse {
LedgerAccount account = 1;
}

7
api/proto/notification_sent.proto
View File

@@ -4,10 +4,17 @@ option go_package = "github.com/tech/sendico/pkg/generated/gmessaging";
import "operation_result.proto";
// NotificationSentEvent is published after a notification has been delivered
// (or delivery has failed) to a user.
message NotificationSentEvent {
// user_id identifies the recipient.
string user_id = 1;
// template_id is the notification template that was rendered.
string template_id = 2;
// channel is the delivery channel (e.g. "email", "sms", "push").
string channel = 3;
// locale is the language/region used for rendering (e.g. "en", "ru").
string locale = 4;
// status reports whether the delivery succeeded.
OperationResult status = 5;
}

4
api/proto/object_updated.proto
View File

@@ -2,7 +2,11 @@ syntax = "proto3";
option go_package = "github.com/tech/sendico/pkg/generated/gmessaging";
// ObjectUpdatedEvent is a generic event published when any domain object is
// modified, carrying the object reference and the acting user.
message ObjectUpdatedEvent {
// object_ref is the unique reference of the updated object.
string object_ref = 1;
// actor_account_ref identifies the account that performed the update.
string actor_account_ref = 2;
}

6
api/proto/operation_result.proto
View File

@@ -2,7 +2,11 @@ syntax = "proto3";
option go_package = "github.com/tech/sendico/pkg/generated/gmessaging";
// OperationResult reports the success or failure of an asynchronous operation.
message OperationResult {
// is_successful is true when the operation completed without errors.
bool is_successful = 1;
// error_description contains a human-readable error message when
// is_successful is false.
string error_description = 2;
}
}

22
api/proto/oracle/v1/oracle.proto
View File

@@ -9,7 +9,7 @@ import "api/proto/common/money/v1/money.proto";
import "api/proto/common/fx/v1/fx.proto";
import "api/proto/common/trace/v1/trace.proto";
// RateSnapshot holds a point-in-time rate observation from a provider.
message RateSnapshot {
common.fx.v1.CurrencyPair pair = 1;
common.money.v1.Decimal mid = 2;
@@ -21,6 +21,7 @@ message RateSnapshot {
common.money.v1.Decimal spread_bps = 8;
}
// RequestMeta carries caller identity and tracing context for oracle requests.
message RequestMeta {
reserved 1, 4, 5;
reserved "request_ref", "idempotency_key", "trace_ref";
@@ -30,6 +31,7 @@ message RequestMeta {
common.trace.v1.TraceContext trace = 6;
}
// ResponseMeta carries tracing context for oracle responses.
message ResponseMeta {
reserved 1, 2;
reserved "request_ref", "trace_ref";
@@ -37,6 +39,7 @@ message ResponseMeta {
common.trace.v1.TraceContext trace = 3;
}
// Quote represents a priced FX quote with an expiry window.
message Quote {
string quote_ref = 1;
common.fx.v1.CurrencyPair pair = 2;
@@ -51,6 +54,7 @@ message Quote {
google.protobuf.Timestamp priced_at = 11;
}
// GetQuoteRequest is the request to obtain an FX quote.
message GetQuoteRequest {
RequestMeta meta = 1;
common.fx.v1.CurrencyPair pair = 2;
@@ -65,16 +69,19 @@ message GetQuoteRequest {
int32 max_age_ms = 9;
}
// GetQuoteResponse is the response for GetQuote.
message GetQuoteResponse {
ResponseMeta meta = 1;
Quote quote = 2;
}
// ValidateQuoteRequest is the request to check whether a quote is still valid.
message ValidateQuoteRequest {
RequestMeta meta = 1;
string quote_ref = 2;
}
// ValidateQuoteResponse is the response for ValidateQuote.
message ValidateQuoteResponse {
ResponseMeta meta = 1;
Quote quote = 2;
@@ -82,48 +89,61 @@ message ValidateQuoteResponse {
string reason = 4;
}
// ConsumeQuoteRequest marks a quote as used, linking it to a ledger transaction.
message ConsumeQuoteRequest {
RequestMeta meta = 1;
string quote_ref = 2;
string ledger_txn_ref = 3;
}
// ConsumeQuoteResponse is the response for ConsumeQuote.
message ConsumeQuoteResponse {
ResponseMeta meta = 1;
bool consumed = 2;
string reason = 3;
}
// LatestRateRequest is the request to fetch the most recent rate for a pair.
message LatestRateRequest {
RequestMeta meta = 1;
common.fx.v1.CurrencyPair pair = 2;
string provider = 3;
}
// LatestRateResponse is the response for LatestRate.
message LatestRateResponse {
ResponseMeta meta = 1;
RateSnapshot rate = 2;
}
// ListPairsRequest is the request to list all supported currency pairs.
message ListPairsRequest {
RequestMeta meta = 1;
}
// PairMeta holds metadata for a supported currency pair.
message PairMeta {
common.fx.v1.CurrencyPair pair = 1;
common.money.v1.CurrencyMeta base_meta = 2;
common.money.v1.CurrencyMeta quote_meta = 3;
}
// ListPairsResponse is the response for ListPairs.
message ListPairsResponse {
ResponseMeta meta = 1;
repeated PairMeta pairs = 2;
}
// Oracle provides FX rate quoting, validation, and consumption.
service Oracle {
// GetQuote returns a priced FX quote for a currency pair.
rpc GetQuote(GetQuoteRequest) returns (GetQuoteResponse);
// ValidateQuote checks whether an existing quote is still valid.
rpc ValidateQuote(ValidateQuoteRequest) returns (ValidateQuoteResponse);
// ConsumeQuote marks a quote as consumed and links it to a ledger transaction.
rpc ConsumeQuote(ConsumeQuoteRequest) returns (ConsumeQuoteResponse);
// LatestRate returns the most recent rate snapshot for a currency pair.
rpc LatestRate(LatestRateRequest) returns (LatestRateResponse);
// ListPairs returns all supported currency pairs.
rpc ListPairs(ListPairsRequest) returns (ListPairsResponse);
}

6
api/proto/password_reset.proto
View File

@@ -2,7 +2,11 @@ syntax = "proto3";
option go_package = "github.com/tech/sendico/pkg/generated/gmessaging";
// PasswordResetEvent is published when a user requests a password reset.
message PasswordResetEvent {
// account_ref is the unique reference of the account requesting the reset.
string account_ref = 1;
// reset_token is the one-time token the user must present to set a new
// password.
string reset_token = 2;
}
}

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;
}

10
api/proto/site_request.proto
View File

@@ -2,7 +2,10 @@ syntax = "proto3";
option go_package = "github.com/tech/sendico/pkg/generated/gmessaging";
// SiteRequestEvent is published when a visitor submits a request through the
// public website (demo, contact, or callback).
message SiteRequestEvent {
// RequestType classifies the kind of site request.
enum RequestType {
REQUEST_TYPE_UNSPECIFIED = 0;
REQUEST_TYPE_DEMO = 1;
@@ -10,15 +13,20 @@ message SiteRequestEvent {
REQUEST_TYPE_CALL = 3;
}
// type identifies which kind of request was submitted.
RequestType type = 1;
oneof payload {
// demo is the payload for a product demo request.
SiteDemoRequest demo = 2;
// contact is the payload for a general contact inquiry.
SiteContactRequest contact = 3;
// call is the payload for a callback request.
SiteCallRequest call = 4;
}
}
// SiteDemoRequest carries details for a product demo request.
message SiteDemoRequest {
string name = 1;
string organization_name = 2;
@@ -28,6 +36,7 @@ message SiteDemoRequest {
string comment = 6;
}
// SiteContactRequest carries details for a general contact inquiry.
message SiteContactRequest {
string name = 1;
string email = 2;
@@ -37,6 +46,7 @@ message SiteContactRequest {
string message = 6;
}
// SiteCallRequest carries details for a callback request.
message SiteCallRequest {
string name = 1;
string phone = 2;