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/gateway/v1/gateway.proto";

// Lifecycle status of a payout handled by Monetix.
enum PayoutStatus {
  PAYOUT_STATUS_UNSPECIFIED = 0;

  PAYOUT_STATUS_CREATED    = 1; // request created, not sent
  PAYOUT_STATUS_WAITING    = 2; // waiting provider processing
  PAYOUT_STATUS_SUCCESS    = 3; // final success
  PAYOUT_STATUS_FAILED     = 4; // final failure
  PAYOUT_STATUS_CANCELLED  = 5; // final cancelled
}


// 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;
  string operation_ref = 31;
  string idempotency_key = 32;
  string intent_ref = 33;
}

// 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;
  string operation_ref = 12;
  string idempotency_key = 13;
  string intent_ref = 14;
}

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

message ListGatewayInstancesRequest {}

message ListGatewayInstancesResponse {
  repeated common.gateway.v1.GatewayInstanceDescriptor items = 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;
  string operation_ref = 31;
  string idempotency_key = 32;
  string intent_ref = 33;
}

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