common.transferinstructions

io.token.proto.common.transferinstructions /common/src/main/proto/transferinstructions.proto


syntax = "proto3";
package io.token.proto.common.transferinstructions;

option java_outer_classname = "TransferInstructionsProtos";
option csharp_namespace = "Tokenio.Proto.Common.TransferInstructionsProtos";

import "account.proto";
import "address.proto";
import "banklink.proto";
import "security.proto";
import "extensions/message.proto";

// A bank might require a Purpose of Payment for some transfers.
enum PurposeOfPayment {
  INVALID = 0;
  OTHER = 1;
  PERSONAL_EXPENSES = 2;
  PURCHASE_OF_SHARES = 3;
  TRANSFER_TO_YOUR_OWN_ACCOUNT = 4;
  PURCHASE_OF_PROPERTY = 5;
  FAMILY_MAINTENANCE = 6;
  SAVINGS = 7;
}

// A bank might require a context code for some transfers.
enum PaymentContext {
  INVALID_CONTEXT = 0;
  OTHER_CONTEXT = 1;
  BILL_PAYMENT = 2;
  ECOMMERCE_GOODS = 3;
  ECOMMERCE_SERVICES = 4;
  PERSON_TO_PERSON = 5;
}

message CustomerData {
  option (io.token.proto.extensions.message.redact) = true;
  repeated string legal_names = 1;                   // Repeated in case of joint account holders.
  io.token.proto.common.address.Address address = 2; // Physical address
}

// Money transfer source or destination account.
message TransferEndpoint {
  io.token.proto.common.account.BankAccount account = 1; // Account identifier, e.g., SWIFT transfer info
  CustomerData customer_data = 2;                        // Customer data: name and address
}

message TransferDestination {
  // Token account Destination. Useful as source or destination
  // for a transfer; doesn't make sense for a bank to "link" this.
  message Token {
    string member_id = 1;
    string account_id = 2;
  }

  // SEPA transfer
  message Sepa {
    option (io.token.proto.extensions.message.redact) = true;
    string bic = 1; // Optional
    string iban = 2;
  }

  message SepaInstant {
    option (io.token.proto.extensions.message.redact) = true;
    string iban = 1;
  }

  // Faster Payments Service transfer (UK)
  message FasterPayments {
    option (io.token.proto.extensions.message.redact) = true;
    string sort_code = 1;
    string account_number = 2;
  }

  // ACH transfer
  message Ach {
    option (io.token.proto.extensions.message.redact) = true;
    string routing = 1; // Routing number
    string account = 2;
  }

  message Swift {
    option (io.token.proto.extensions.message.redact) = true;
    string bic = 1;     // BIC code AAAABBCCDD
    string account = 2;
  }

  // Polish domestic
  message Elixir {
    option (io.token.proto.extensions.message.redact) = true;
    string account_number = 1;
  }

  // Polish domestic
  message ExpressElixir {
    option (io.token.proto.extensions.message.redact) = true;
    string account_number = 1;
  }

  // Polish domestic
  message BlueCash {
    option (io.token.proto.extensions.message.redact) = true;
    string account_number = 1;
  }

  // Polish domestic
  message Sorbnet {
    option (io.token.proto.extensions.message.redact) = true;
    string account_number = 1;
  }

  oneof destination {
    Token token = 1;
    Sepa sepa = 2;
    SepaInstant sepa_instant = 3;
    FasterPayments faster_payments = 4;
    Ach ach = 5;
    Swift swift = 6;
    Elixir elixir = 7;
    ExpressElixir express_elixir = 8;
    BlueCash blue_cash = 9;
    Sorbnet sorbnet = 10;
  }

  CustomerData customer_data = 11;
}

// Money transfer instructions.
message TransferInstructions {
  TransferEndpoint source = 1;                   // Transfer source.
  repeated TransferEndpoint destinations = 2 [deprecated = true];    // Transfer destinations.
  Metadata metadata = 3;
  repeated TransferDestination transfer_destinations = 4;

  message Metadata {
    PurposeOfPayment transfer_purpose = 1;       // Purpose of payment
    PaymentContext payment_context = 2;          // Optional payment context
    string merchant_category_code = 3;           // Optional ISO 18245 Merchant Category Code (MCC)
    string merchant_customer_id = 4;             // Optional Unique merchant customer identifier
    io.token.proto.common.address.Address delivery_address = 5; // Optional delivery address
    ProviderSpecificMetadata provider_metadata = 6;

    message ProviderSpecificMetadata {
      oneof provider_metadata {
        PolishApiMetadata polish_api_metadata = 1;
      }

      message PolishApiMetadata {
        DeliveryMode delivery_mode = 1;
        bool hold = 2; // indicates that the funds should be reserved until the payment is executable (e.g. for Bank holidays)

        enum DeliveryMode {
          INVALID = 0;
          STANDARD_D2 = 1; // only applies to non-EEA destinations
          STANDARD_D1 = 2; // only applies to EEA destinations
          URGENT_D1 = 3; // only applies to non-EEA destinations
          EXPRESS_D0 = 4; // applies to all destinations
        }
      }
    }
  }
}