sendico/api/proto/gateway/mntx/v1/mntx.proto

syntax = "proto3";

package mntx.gateway.v1;

option go_package = "github.com/tech/sendico/pkg/proto/gateway/mntx/v1;mntxv1";

import "google/protobuf/timestamp.proto";
import "common/money/v1/money.proto";

// Status of a payout request handled by Monetix.
enum PayoutStatus {
  PAYOUT_STATUS_UNSPECIFIED = 0;
  PAYOUT_STATUS_PENDING = 1;
  PAYOUT_STATUS_PROCESSED = 2;
  PAYOUT_STATUS_FAILED = 3;
}

// Basic destination data for the payout.
message BankAccount {
  string iban = 1;
  string bic = 2;
  string account_holder = 3;
  string country = 4;
}

// Card destination for payouts (PAN-based or tokenized).
message CardDestination {
  oneof card {
    string pan = 1;   // raw primary account number
    string token = 2; // network or gateway-issued token
  }
  string cardholder_name = 3;
  string exp_month = 4;
  string exp_year = 5;
  string country = 6;
}

// Wrapper allowing multiple payout destination types.
message PayoutDestination {
  oneof destination {
    BankAccount bank_account = 1;
    CardDestination card = 2;
  }
}

message Payout {
  string payout_ref = 1;
  string idempotency_key = 2;
  string organization_ref = 3;
  PayoutDestination destination = 4;
  common.money.v1.Money amount = 5;
  string description = 6;
  map<string, string> metadata = 7;
  PayoutStatus status = 8;
  string failure_reason = 9;
  google.protobuf.Timestamp created_at = 10;
  google.protobuf.Timestamp updated_at = 11;
}

message SubmitPayoutRequest {
  string idempotency_key = 1;
  string organization_ref = 2;
  PayoutDestination destination = 3;
  common.money.v1.Money amount = 4;
  string description = 5;
  map<string, string> metadata = 6;
  string simulated_failure_reason = 7; // optional trigger to force a failed payout for testing
}

message SubmitPayoutResponse {
  Payout payout = 1;
}

message GetPayoutRequest {
  string payout_ref = 1;
}

message GetPayoutResponse {
  Payout payout = 1;
}

// Event emitted over messaging when payout status changes.
message PayoutStatusChangedEvent {
  Payout payout = 1;
}

// Request to initiate a Monetix card payout.
message CardPayoutRequest {
  string payout_id = 1;              // internal payout id, mapped to Monetix payment_id
  int64 project_id = 2;              // optional override; defaults to configured project id
  string customer_id = 3;
  string customer_first_name = 4;
  string customer_middle_name = 5;
  string customer_last_name = 6;
  string customer_ip = 7;
  string customer_zip = 8;
  string customer_country = 9;
  string customer_state = 10;
  string customer_city = 11;
  string customer_address = 12;
  int64 amount_minor = 13;           // amount in minor units
  string currency = 14;              // ISO-4217 alpha-3
  string card_pan = 15;
  uint32 card_exp_year = 16;
  uint32 card_exp_month = 17;
  string card_holder = 18;
  map<string, string> metadata = 30;
}

// Persisted payout state for retrieval and status updates.
message CardPayoutState {
  string payout_id = 1;
  int64 project_id = 2;
  string customer_id = 3;
  int64 amount_minor = 4;
  string currency = 5;
  PayoutStatus status = 6;
  string provider_code = 7;
  string provider_message = 8;
  string provider_payment_id = 9;
  google.protobuf.Timestamp created_at = 10;
  google.protobuf.Timestamp updated_at = 11;
}

// Response returned immediately after submitting a payout to Monetix.
message CardPayoutResponse {
  CardPayoutState payout = 1;
  bool accepted = 2;
  string provider_request_id = 3;
  string error_code = 4;
  string error_message = 5;
}

message GetCardPayoutStatusRequest {
  string payout_id = 1;
}

message GetCardPayoutStatusResponse {
  CardPayoutState payout = 1;
}

// Event emitted when Monetix callback updates payout status.
message CardPayoutStatusChangedEvent {
  CardPayoutState payout = 1;
}

// Request to initiate a token-based card payout.
message CardTokenPayoutRequest {
  string payout_id = 1;
  int64 project_id = 2;
  string customer_id = 3;

  string customer_first_name = 4;
  string customer_middle_name = 5;
  string customer_last_name = 6;
  string customer_ip = 7;

  string customer_zip = 8;
  string customer_country = 9;
  string customer_state = 10;
  string customer_city = 11;
  string customer_address = 12;

  int64 amount_minor = 13;
  string currency = 14;

  string card_token = 15;
  string card_holder = 16;
  string masked_pan = 17;
  map<string, string> metadata = 30;
}

// Response returned immediately after submitting a token payout to Monetix.
message CardTokenPayoutResponse {
  CardPayoutState payout = 1;
  bool accepted = 2;
  string provider_request_id = 3;
  string error_code = 4;
  string error_message = 5;
}

// Raw card details used for tokenization.
message CardDetails {
  string pan = 1;
  uint32 exp_month = 2;
  uint32 exp_year = 3;
  string card_holder = 4;
  string cvv = 5;
}

// Request to tokenize a card with Monetix.
message CardTokenizeRequest {
  string request_id = 1;
  int64 project_id = 2;
  string customer_id = 3;

  string customer_first_name = 4;
  string customer_middle_name = 5;
  string customer_last_name = 6;
  string customer_ip = 7;

  string customer_zip = 8;
  string customer_country = 9;
  string customer_state = 10;
  string customer_city = 11;
  string customer_address = 12;

  string card_pan = 13;
  uint32 card_exp_month = 14;
  uint32 card_exp_year = 15;
  string card_holder = 16;
  string card_cvv = 17;

  // Preferred new card container for tokenization requests.
  CardDetails card = 30;
}

// Response from Monetix tokenization.
message CardTokenizeResponse {
  string request_id = 1;
  bool success = 2;
  string token = 3;
  string masked_pan = 4;
  string expiry_month = 5;
  string expiry_year = 6;
  string card_brand = 7;
  string error_code = 8;
  string error_message = 9;
}

service MntxGatewayService {
  rpc SubmitPayout(SubmitPayoutRequest) returns (SubmitPayoutResponse);
  rpc GetPayout(GetPayoutRequest) returns (GetPayoutResponse);
  rpc CreateCardPayout(CardPayoutRequest) returns (CardPayoutResponse);
  rpc GetCardPayoutStatus(GetCardPayoutStatusRequest) returns (GetCardPayoutStatusResponse);
  rpc CreateCardTokenPayout(CardTokenPayoutRequest) returns (CardTokenPayoutResponse);
  rpc CreateCardToken(CardTokenizeRequest) returns (CardTokenizeResponse);
}