bankapi

io.token.proto.bankapi /external/src/main/proto/bankapi/bankapi.proto


syntax = "proto3";
package io.token.proto.bankapi;

import "google/api/annotations.proto";

import "account.proto";
import "money.proto";
import "pricing.proto";
import "token.proto";
import "transfer.proto";
import "transaction.proto";
import "transferinstructions.proto";
import "notification.proto";
import "subscriber.proto";
import "banklink.proto";
import "extensions/field.proto";

enum StatusCode {
  INVALID_STATUS = 0;                   // invalid status, reserved
  PROCESSING = 1;                       // transaction is being processed
  SUCCESS = 2;                          // transaction succeeded
  FAILURE_CANCELED = 3;                 // transaction has been canceled, rolled back
  FAILURE_INSUFFICIENT_FUNDS = 4;       // the transaction failed due to insufficient funds
  FAILURE_INVALID_CURRENCY = 5;         // the transaction failed due to currency mismatch
  FAILURE_PERMISSION_DENIED = 6;        // the transaction failed due to access violation
  FAILURE_QUOTE_EXPIRED = 7;            // the transaction failed because the quote has expired
  FAILURE_INVALID_AMOUNT = 8;           // the transaction failed due to invalid amount
  FAILURE_INVALID_QUOTE = 9;            // the transaction failed due to invalid quote (wrong fx rate)
  FAILURE_EXPIRED = 10;                 // the transaction failed to complete within alotted time
  FAILURE_GENERIC = 11;                 // the transaction has failed due to other reasons
  FAILURE_ACCOUNT_NOT_FOUND = 12;       // the account is not found
  FAILURE_TRANSACTION_NOT_FOUND = 13;   // the transaction has failed due to other reasons
  FAILURE_UNSUPPORTED_DESTINATION = 14; // the transaction failed because bank does not support requested destination
  SENT = 15;                            // legacy transfers only: the transaction has been sent but has not been acknowledged by the bank
}


////////////////////////////////////////////////////////////////////////////////////////////////////
// Account API types
//
message GetTransactionRequest {
  string transaction_id = 1;
  io.token.proto.common.account.BankAccount account = 2;
}

message GetTransactionResponse {
  io.token.proto.common.transaction.Transaction transaction = 1;
}

message GetTransactionsRequest {
  io.token.proto.common.account.BankAccount account = 1;
  int32 integer_offset = 2 [deprecated=true];  // use offset instead
  int32 limit = 3;
  string offset = 4;
}

message GetTransactionsResponse {
  repeated io.token.proto.common.transaction.Transaction transactions = 1;
  string offset = 2;
}

message GetBalanceRequest {
  io.token.proto.common.account.BankAccount account = 1;
}

message GetBalanceResponse {
  io.token.proto.common.money.Money current = 1;
  io.token.proto.common.money.Money available = 2;
}

message GetCustomerDataRequest {
  io.token.proto.common.account.BankAccount account = 1;
}

message GetCustomerDataResponse {
  io.token.proto.common.transferinstructions.CustomerData customer_data = 1;
  StatusCode status = 2;
  string status_description = 3;
}

message ResolveTransferDestinationRequest {
  io.token.proto.common.account.BankAccount account = 1;
}

message ResolveTransferDestinationResponse {
  repeated io.token.proto.common.account.BankAccount destinations = 1;
}

message GetAccountDetailsRequest {
  io.token.proto.common.account.BankAccount account = 1;
}

message GetAccountDetailsResponse {
  io.token.proto.common.account.AccountDetails account_details = 1;
}

////////////////////////////////////////////////////////////////////////////////////////////////////
// Account linking API types
//
message GetBankAuthorizationRequest {
  string access_token = 1;
}

message GetBankAuthorizationResponse {
  io.token.proto.banklink.BankAuthorization bank_authorization = 1;
}

////////////////////////////////////////////////////////////////////////////////////////////////////
// Instant transfer API types
//
message BeginDebitTransactionRequest {
  string token_ref_id = 1;
  string transfer_ref_id = 2;
  string transfer_id = 3;
  io.token.proto.common.money.Money requested_amount = 4;
  io.token.proto.common.money.Money transaction_amount = 5;
  io.token.proto.common.money.Money settlement_amount = 6;
  io.token.proto.common.account.BankAccount account = 7;
  io.token.proto.common.pricing.Pricing pricing = 8;
  io.token.proto.common.transferinstructions.TransferEndpoint counterparty = 9;
  io.token.proto.common.transferinstructions.PurposeOfPayment payment_purpose = 10;
  string description = 11;
}

message BeginDebitTransactionResponse {
  string transaction_id = 1;
  StatusCode status = 2;
  string status_description = 3;
  bool is_delayed = 4;
}

message BeginCreditTransactionRequest {
  string token_ref_id = 1;
  string transfer_ref_id = 2;
  string transfer_id = 3;
  io.token.proto.common.money.Money requested_amount = 4;
  io.token.proto.common.money.Money transaction_amount = 5;
  io.token.proto.common.money.Money settlement_amount = 6;
  io.token.proto.common.account.BankAccount account = 7;
  io.token.proto.common.pricing.Pricing pricing = 8;
  io.token.proto.common.transferinstructions.TransferEndpoint counterparty = 9;
  io.token.proto.common.transferinstructions.PurposeOfPayment payment_purpose = 10;
  string description = 11;
}

message BeginCreditTransactionResponse {
  string transaction_id = 1;
  StatusCode status = 2;
  string status_description = 3;
  bool is_delayed = 4;
}

message CommitDebitTransactionRequest {
  string transfer_id = 1;
  string transaction_id = 2;
  io.token.proto.common.money.Money amount = 3;
  io.token.proto.common.account.BankAccount account = 4;
}

message CommitDebitTransactionResponse {}

message CommitCreditTransactionRequest {
  string transfer_id = 1;
  string transaction_id = 2;
  io.token.proto.common.money.Money amount = 3;
  io.token.proto.common.account.BankAccount account = 4;
}

message CommitCreditTransactionResponse {}

message RollbackDebitTransactionRequest {
  string transfer_id = 1;
  string transaction_id = 2;
  io.token.proto.common.money.Money amount = 3;
  io.token.proto.common.account.BankAccount account = 4;
}

message RollbackDebitTransactionResponse {}

message RollbackCreditTransactionRequest {
  string transfer_id = 1;
  string transaction_id = 2;
  io.token.proto.common.money.Money amount = 3;
  io.token.proto.common.account.BankAccount account = 4;
}

message RollbackCreditTransactionResponse {}


////////////////////////////////////////////////////////////////////////////////////////////////////
// Notification API types
//
message NotifyRequest {
  io.token.proto.common.notification.Notification notification = 1;
  io.token.proto.common.subscriber.Subscriber subscriber = 2;
}

message NotifyResponse {}


////////////////////////////////////////////////////////////////////////////////////////////////////
// Pricing API types
//
message PrepareDebitRequest {
  string token_ref_id = 1;
  io.token.proto.common.money.Money amount = 2;
  io.token.proto.common.account.BankAccount source = 3;
  io.token.proto.common.transferinstructions.TransferEndpoint destination = 4;
  io.token.proto.common.pricing.TransferQuote counterpartyQuote = 5;
  io.token.proto.common.transferinstructions.PurposeOfPayment payment_purpose = 6;
}

message PrepareDebitResponse {
  StatusCode status = 1;
  string status_description = 2;
  io.token.proto.common.pricing.TransferQuote quote = 3;
}

message PrepareCreditRequest {
  string token_ref_id = 1;
  io.token.proto.common.money.Money amount = 2;
  io.token.proto.common.transferinstructions.TransferEndpoint source = 3;
  io.token.proto.common.transferinstructions.TransferEndpoint destination = 4;
  io.token.proto.common.transferinstructions.PurposeOfPayment payment_purpose = 5;
}

message PrepareCreditResponse {
  StatusCode status = 1;
  string status_description = 2;
  io.token.proto.common.pricing.TransferQuote quote = 3;
}


////////////////////////////////////////////////////////////////////////////////////////////////////
// Storage API types
//
message SetValueRequest {
  enum ContentCategory {
    INVALID = 0;
    ACCOUNT_INFO = 1;
    TOKEN_INFO = 2;
  }

  string key = 1;
  bytes value = 2 [(io.token.proto.extensions.field.redact) = true];
  ContentCategory category = 3;
}

message SetValueResponse {
  bytes previous = 1 [(io.token.proto.extensions.field.redact) = true];
}

message GetValueRequest {
  string key = 1;
}

message GetValueResponse {
  bytes value = 1 [(io.token.proto.extensions.field.redact) = true];
}

message RemoveValueRequest {
  string key = 1;
}

message RemoveValueResponse {
}


////////////////////////////////////////////////////////////////////////////////////////////////////
// Non-instant transfer API types
//
message TransferRequest {
  string token_ref_id = 10;
  string transfer_ref_id = 11;
  string transfer_id = 1;
  io.token.proto.common.money.Money requested_amount = 2;
  io.token.proto.common.money.Money transaction_amount = 3;
  io.token.proto.common.account.BankAccount source = 4;
  repeated io.token.proto.common.transferinstructions.TransferEndpoint destinations = 5;
  io.token.proto.common.pricing.TransferQuote quote = 6;
  io.token.proto.common.pricing.FeeResponsibility fee_responsibility = 7;
  string description = 9; // optional transfer description
  io.token.proto.common.transferinstructions.TransferInstructions.Metadata metadata = 12;
}

message TransferResponse {
  string transaction_id = 1;
  StatusCode status = 2;
  string status_description = 3;
}

message BatchTransferRequest {
  repeated TransferRequest transfers = 1;
}

message BatchTransferResponse {
  TransferResponse transfer_response = 1;
}

////////////////////////////////////////////////////////////////////////////////////////////////////
// Account API
//
service AccountService {
  rpc GetBalance (GetBalanceRequest) returns (GetBalanceResponse) {
    option (google.api.http) = {
        get: "/accounts/{account.custom.bank_id}/{account.custom.payload}/balance"
    };
  }

  rpc GetTransaction (GetTransactionRequest) returns (GetTransactionResponse) {
    option (google.api.http) = {
        get: "/accounts/{account.custom.bank_id}/{account.custom.payload}/transactions?transaction_id={transaction_id}"
    };
  }

  rpc GetTransactions (GetTransactionsRequest) returns (GetTransactionsResponse) {
    option (google.api.http) = {
        get: "/accounts/{account.custom.bank_id}/{account.custom.payload}/transactions?offset={offset}&limit={limit}"
    };
  }

  rpc GetCustomerData(GetCustomerDataRequest) returns (GetCustomerDataResponse) {
    option (google.api.http) = {
        get: "/accounts/{account.custom.bank_id}/{account.custom.payload}/customer-data"
    };
  }

  rpc ResolveTransferDestination(ResolveTransferDestinationRequest) returns (ResolveTransferDestinationResponse) {
    option (google.api.http) = {
        get: "/accounts/{account.custom.bank_id}/{account.custom.payload}/transfer-destination"
    };
  }

  rpc GetAccountDetails(GetAccountDetailsRequest) returns (GetAccountDetailsResponse) {
    option (google.api.http) = {
        get: "/accounts/{account.custom.bank_id}/{account.custom.payload}/account-details"
    };
  }
}

////////////////////////////////////////////////////////////////////////////////////////////////////
// Account Linking API
//
service AccountLinkingService {
  rpc GetBankAuthorization (GetBankAuthorizationRequest) returns (GetBankAuthorizationResponse) {
    option (google.api.http) = {
        get: "/bank-authorization?access_token={access_token}"
    };
  }
}

////////////////////////////////////////////////////////////////////////////////////////////////////
// Instant Transfer API
//
service InstantTransferService {
  rpc BeginDebitTransaction (BeginDebitTransactionRequest) returns (BeginDebitTransactionResponse) {
    option (google.api.http) = {
        post: "/instant-transfers/begin-debit"
    };
  }

  rpc BeginCreditTransaction (BeginCreditTransactionRequest) returns (BeginCreditTransactionResponse) {
    option (google.api.http) = {
        post: "/instant-transfers/begin-credit"
    };
  }

  rpc CommitDebitTransaction (CommitDebitTransactionRequest) returns (CommitDebitTransactionResponse) {
    option (google.api.http) = {
        post: "/instant-transfers/{reference_id}/commit-debit"
    };
  }

  rpc CommitCreditTransaction (CommitCreditTransactionRequest) returns (CommitCreditTransactionResponse) {
    option (google.api.http) = {
        post: "/instant-transfers/{reference_id}/commit-credit"
    };
  }

  rpc RollbackDebitTransaction (RollbackDebitTransactionRequest) returns (RollbackDebitTransactionResponse) {
    option (google.api.http) = {
        post: "/instant-transfers/{reference_id}/rollback-debit"
    };
  }

  rpc RollbackCreditTransaction (RollbackCreditTransactionRequest) returns (RollbackCreditTransactionResponse) {
    option (google.api.http) = {
        post: "/instant-transfers/{reference_id}/rollback-credit"
    };
  }
}


////////////////////////////////////////////////////////////////////////////////////////////////////
// Notification API
//
service NotificationService {
  rpc Notify (NotifyRequest) returns (NotifyResponse) {
    option (google.api.http) = {
        post: "/notifications"
    };
  }
}


////////////////////////////////////////////////////////////////////////////////////////////////////
// Pricing API
//
service PricingService {
  rpc PrepareCredit(PrepareCreditRequest) returns (PrepareCreditResponse) {
    option (google.api.http) = {
        post: "/pricing/prepare-credit"
    };
  }

  rpc PrepareDebit(PrepareDebitRequest) returns (PrepareDebitResponse) {
    option (google.api.http) = {
        post: "/pricing/prepare-debit"
    };
  }
}


////////////////////////////////////////////////////////////////////////////////////////////////////
// Storage API
//
service StorageService {
  rpc SetValue (SetValueRequest) returns (SetValueResponse) {
    option (google.api.http) = {
        put: "/storage/{key}"
    };
  }

  rpc GetValue (GetValueRequest) returns (GetValueResponse) {
    option (google.api.http) = {
        get: "/storage/{key}"
    };
  }

  rpc RemoveValue (RemoveValueRequest) returns (RemoveValueResponse) {
    option (google.api.http) = {
        delete: "/storage/{key}"
    };
  }
}


////////////////////////////////////////////////////////////////////////////////////////////////////
// Non-instant transfer API
//
service TransferService {
  rpc Transfer (TransferRequest) returns (TransferResponse) {
    option (google.api.http) = {
        post: "/transfers"
    };
  }

  rpc BatchTransfer (BatchTransferRequest) returns (BatchTransferResponse) {
    option (google.api.http) = {
        post: "/batch/transfers"
    };
  }
}