common.v2.payout

syntax = "proto3";
package io.token.proto.common.v2.payout;

option java_outer_classname = "PayoutProtos";

import "money.proto";
import "v2/common.proto";
import "extensions/field.proto";
import "extensions/message.proto";

////////////////////////////////////////////////////////////////////////////////////////////////////
// Registration objects for different providers
//TODO: START deprecated by PLT-4728. moved registration to virtualaccount.proto

enum Product {
  UNKNOWN = 0;
  REFUND = 1;
  PAYOUT = 2;
}

message BnppRegistrationPayload {
  string app_id = 1;
  string app_secret = 2 [(io.token.proto.extensions.field.redact) = true];
  v2.common.DebtorInformation debtor = 3; // deprecated. Keeping for backward compatibility.  use debtors for new registrations
  string signing_key_id = 4;  // key id provided by bnpp
  string token_signing_key_id = 5; // id of the signing key in token HSM
  repeated v2.common.DebtorInformation debtors = 6;
}

message HsbcRegistrationPayload {
  string client_id = 1;
  string client_secret = 2 [(io.token.proto.extensions.field.redact) = true];
  string profile_id = 3;
  v2.common.DebtorInformation debtor = 4; // deprecated. Keeping for backward compatibility.  use debtors for new registrations
  string pgp_private_key = 5 [(io.token.proto.extensions.field.redact) = true]; // Our HSM don't support pgp signing and encryption. So we have to store it in secret server directly.
  string pgp_public_key = 6 [(io.token.proto.extensions.field.redact) = true];
  string pgp_private_key_passphrase = 7 [(io.token.proto.extensions.field.redact) = true];
  repeated v2.common.DebtorInformation debtors = 8;
}

message FankRegistrationPayload {
}

message CorporateApiRegistrationPayload {
  string member_id = 1;
  string on_behalf_of_id = 2;
  repeated CorporateApiDebtorInformation debtors = 3;
}

message Registration {
  string id = 1;
  string created_date_time = 2;
  Product product = 3;
  oneof registration {
      BnppRegistrationPayload bnpp = 4;
      HsbcRegistrationPayload hsbc = 5;
      FankRegistrationPayload fank = 6;
      CorporateApiRegistrationPayload corporate_api = 7;
  }
}
//TODO: END deprecated by PLT-4728

////////////////////////////////////////////////////////////////////////////////////////////////////
// Refund specific messages

message RefundInitiation {
  string description = 1; // Description for the refund
  string ref_id = 2; // The reference id from the customer
  io.token.proto.common.money.Money amount = 3;
  string original_payment_id = 4; // The original payment id from Token payments/transfers. This is required to initiate a refund. Token will check the original payment for the refund validation.
  string registration_id = 6;
  v2.common.LocalInstrument local_instrument = 7;
  v2.common.DebtorInformation debtor = 8;
  v2.common.CreditorInformation creditor = 9;
  CorporateApiDebtorInformation corporate_api_debtor = 10;
  string on_behalf_of_id = 11; // Optional on behalf of id
}

message Refund {
  string id = 1; // Token generated refund id
  string bank_transaction_id = 2; // Transaction id from the bank side. Can be empty if it is not available from the bank side
  string member_id = 3; // Token member id of the customer initiating this refund
  string created_date_time = 4; // The time when this refund object was created (in ISO 8601 format)
  string updated_date_time = 5; // The last update time for the current status, sub status, status reason information and authentication (in ISO 8601 format)
  Status status = 6; // Token refund status
  string bank_payment_status = 7; // The raw bank status. Can be empty if no payment status is available on bank side
  string status_reason_information = 8; // A human-readable description of the reason behind the status
  RefundInitiation initiation = 9;
}

enum Status {
  reserved 7;
  INVALID_STATUS = 0;
  INITIATION_PENDING = 1; // Token has received the payment initiation and the initiation passed Token validation.
  INITIATION_PROCESSING = 2; // The payment is processing on the bank side. Status can be updated to one of INITIATION_COMPLETED, INITIATION_REJECTED or INITIATION_FAILED or stay INITIATION_PROCESSING forever.
  INITIATION_COMPLETED = 3; // The payment initiation is successful. This does not guarantee the refund is settled.
  INITIATION_REJECTED = 4; // The payment is rejected by the bank. More details are shared in the corresponding status reason information.
  INITIATION_FAILED = 5; // Token failed to create the initiation due to failures on the bank side, e.g. the bank is not available at the moment.
  INITIATION_NO_FINAL_STATUS_AVAILABLE = 6; // This happens when we stop polling the status.
}

enum TransferRefundStatus {
  option deprecated = true; // TODO (PLT-2749): use v2.common.PaymentRefundStatus instead
  NONE = 0;
  PARTIAL = 1;
  FULL = 2;
}

////////////////////////////////////////////////////////////////////////////////////////////////////
// Payout specific messages

message IbanCreditor {
  string name = 1;
  string ultimate_creditor_name = 2;
  string bank_name = 3;
  string iban = 4;
  string bic = 5;
}

message ScanCreditor {
  string name = 1;
  string ultimate_creditor_name = 2;
  string bank_name = 3;
  string account_number = 4;
  string sort_code = 5;
}

message CorporateApiDebtorInformation {
  string account_id = 1; // token virtual account id
}

message Payout {
  string id = 1;
  string bank_transaction_id = 2;
  string member_id =3;
  string created_date_time = 4;
  string updated_date_time = 5;
  Status status = 6;
  string bank_payment_status = 7;
  string status_reason_information = 8;
  Initiation initiation = 9;
  string reference = 10;
  string description = 11;
}

message Initiation {
  string description = 1;
  io.token.proto.common.money.Money amount = 2;
  string reference = 3;
  Debtor debtor = 4;
  Creditor creditor = 5;
  string ref_id = 6;
  string on_behalf_of_id = 7;
}

message Debtor {
  // for corporate api debtor
  string account_id = 1;
}

// We wrote this way instead of oneOf because as requirements the key should be always creditor.
message Creditor {
  // common fields
  string name = 1;
  string ultimate_creditor_name = 2;
  string bank_name = 3;
  // iban
  string iban = 4;
  string bic = 5;
  // scan
  string account_number = 6;
  string sort_code = 7;
}

enum PayoutType {
  SCAN = 0;
  IBAN = 1;
}

message PayoutFilter {
  string start_date = 1; // startDate 'YYYY-MM-DD' UTC timezone (Optional)
  string end_date = 2; // endDate 'YYYY-MM-DD' UTC timezone (Optional)
  repeated string ids = 3; // payout ids for search (Optional)
  bool invert_ids = 4; // bool should we revert ids, default false (Optional)
  repeated string statuses = 5; // statuses of payout (Optional)
  bool invert_statuses = 6; // revert status, default false (Optional)
  repeated string ref_ids = 7; // refIds (Optional)
  string on_behalf_of_id = 8; // onBehalfOfId (Optional)
}

////////////////////////////////////////////////////////////////////////////////////////////////////
// Settlement rule specific messages

message SettlementRule {
  string id = 1; //UUID
  string payer_account_id = 2; // virtual account id
  Creditor payee_account_details = 3 [(io.token.proto.extensions.field.redact) = true];
  AmountType amount_type = 4;
  string amount_value = 5;
  string effective_from = 6;
  string effective_to = 7;
  TimeInterval time_interval = 8;
  int32 intraday_interval_hours = 9;
  int32 intraday_interval_minutes = 10;

  enum SettlementRuleStatus {
    INVALID_STATUS = 0;
    ACTIVE = 1;
    INACTIVE = 2;
  }

  SettlementRuleStatus status = 11;
}

message SettlementRulePayout {
  string id = 1;
  string bank_transaction_id = 2;
  string member_id =3;
  string created_date_time = 4;
  string updated_date_time = 5;
  Status status = 6;
  string bank_payment_status = 7;
  string status_reason_information = 8;
  Initiation initiation = 9;
  string reference = 10;
  string description = 11;
  string settlement_rule_id = 12;
}

enum AmountType {
  INVALID_AMOUNT_TYPE = 0;
  FIXED_VALUE = 1;
  PERCENTAGE = 2;
}

enum TimeInterval {
  INVALID_INTERVAL = 0;
  INTRADAY = 1;
  DAILY = 2;
  WEEKLY = 3;
  MONTHLY = 4;
  QUARTERLY = 5;
  HALF_YEARLY = 6;
  YEARLY = 7;
}