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 "consent.proto";
import "money.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
  INITIATED = 16;                       // not recommended: the transaction has been initiated but the result is unknown, this may be the final status and may not get updated later
}


////////////////////////////////////////////////////////////////////////////////////////////////////
// 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;
  int64 updated_at_ms = 3;
  repeated io.token.proto.common.transaction.Balance.TypedBalance other_balances = 4; // optional
}

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 [deprecated=true];
  repeated io.token.proto.common.transferinstructions.TransferEndpoint endpoints = 2 [deprecated=true];
  repeated io.token.proto.common.transferinstructions.TransferDestination transfer_destinations = 3;
}

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


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

message NotifyResponse {}


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


////////////////////////////////////////////////////////////////////////////////////////////////////
// Transfer API types
//
message TransferRequest {
  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 [deprecated=true];
  string description = 9; // optional transfer description
  string token_ref_id = 10; // reference ID of the token, set by the initiator
  string transfer_ref_id = 11;
  io.token.proto.common.transferinstructions.TransferInstructions.Metadata metadata = 12;
  string token_initiator_id = 13; // ID of member who requested token creation
  repeated io.token.proto.common.transferinstructions.TransferDestination transfer_destinations = 14;
}

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

message GetTransferStatusRequest {
  string transfer_id = 1;
}

message GetTransferStatusResponse {
  io.token.proto.common.transaction.TransactionStatus status = 1;
}

////////////////////////////////////////////////////////////////////////////////////////////////////
// Account Management API types
//
message OnAccountLinkedRequest {
  io.token.proto.common.account.BankAccount account = 1;
  string account_id = 2;
}

message OnAccountLinkedResponse {}

message OnAccountUnlinkedRequest {
  io.token.proto.common.account.BankAccount account = 1;
  string account_id = 2;
}

message OnAccountUnlinkedResponse {}


////////////////////////////////////////////////////////////////////////////////////////////////////
// Consent Management API types
//
message OnConsentCreatedRequest {
  io.token.proto.common.consent.Consent consent = 1;
}

message OnConsentCreatedResponse {}

message OnConsentRevokedRequest {
  string token_id = 1;
}

message OnConsentRevokedResponse {}


////////////////////////////////////////////////////////////////////////////////////////////////////
// Health Check API types
//
message HealthCheckRequest {
  string bank_id = 1;
}

message HealthCheckResponse {

}


////////////////////////////////////////////////////////////////////////////////////////////////////
// Account API
//
service AccountService {
  rpc GetBalance (GetBalanceRequest) returns (GetBalanceResponse) {
    option (google.api.http) = {
        get: "/accounts/balance?account.swift.bic={account.swift.bic}&account.swift.account={account.swift.account}&account.sepa.iban={account.sepa.iban}&account.sepa.bic={account.sepa.bic}&account.ach.routing={account.ach.routing}&account.ach.account={account.ach.account}&account.faster_payments.sort_code={account.faster_payments.sort_code}&account.faster_payments.account_number={account.faster_payments.account_number}&account.custom.bank_id={account.custom.bank_id}&account.custom.payload={account.custom.payload}"
    };
  }

  rpc GetTransaction (GetTransactionRequest) returns (GetTransactionResponse) {
    option (google.api.http) = {
        get: "/accounts/transactions?transaction_id={transaction_id}&account.swift.bic={account.swift.bic}&account.swift.account={account.swift.account}&account.sepa.iban={account.sepa.iban}&account.sepa.bic={account.sepa.bic}&account.ach.routing={account.ach.routing}&account.ach.account={account.ach.account}&account.faster_payments.sort_code={account.faster_payments.sort_code}&account.faster_payments.account_number={account.faster_payments.account_number}&account.custom.bank_id={account.custom.bank_id}&account.custom.payload={account.custom.payload}"
    };
  }

  rpc GetTransactions (GetTransactionsRequest) returns (GetTransactionsResponse) {
    option (google.api.http) = {
        get: "/accounts/transactions?offset={offset}&limit={limit}&account.swift.bic={account.swift.bic}&account.swift.account={account.swift.account}&account.sepa.iban={account.sepa.iban}&account.sepa.bic={account.sepa.bic}&account.ach.routing={account.ach.routing}&account.ach.account={account.ach.account}&account.faster_payments.sort_code={account.faster_payments.sort_code}&account.faster_payments.account_number={account.faster_payments.account_number}&account.custom.bank_id={account.custom.bank_id}&account.custom.payload={account.custom.payload}"
    };
  }

  rpc GetCustomerData(GetCustomerDataRequest) returns (GetCustomerDataResponse) {
    option deprecated = true;
    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/transfer-destination?account.swift.bic={account.swift.bic}&account.swift.account={account.swift.account}&account.sepa.iban={account.sepa.iban}&account.sepa.bic={account.sepa.bic}&account.ach.routing={account.ach.routing}&account.ach.account={account.ach.account}&account.faster_payments.sort_code={account.faster_payments.sort_code}&account.faster_payments.account_number={account.faster_payments.account_number}&account.custom.bank_id={account.custom.bank_id}&account.custom.payload={account.custom.payload}"
    };
  }

  rpc GetAccountDetails(GetAccountDetailsRequest) returns (GetAccountDetailsResponse) {
    option (google.api.http) = {
        get: "/accounts/account-details?account.swift.bic={account.swift.bic}&account.swift.account={account.swift.account}&account.sepa.iban={account.sepa.iban}&account.sepa.bic={account.sepa.bic}&account.ach.routing={account.ach.routing}&account.ach.account={account.ach.account}&account.faster_payments.sort_code={account.faster_payments.sort_code}&account.faster_payments.account_number={account.faster_payments.account_number}&account.custom.bank_id={account.custom.bank_id}&account.custom.payload={account.custom.payload}"
    };
  }
}

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


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


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


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

  rpc GetTransferStatus (GetTransferStatusRequest) returns (GetTransferStatusResponse) {
    option (google.api.http) = {
        get: "/transfers/{transfer_id}/status"
    };
  }
}

////////////////////////////////////////////////////////////////////////////////////////////////////
// Account Management API
//
service AccountManagementService {
  rpc OnAccountLinked (OnAccountLinkedRequest) returns (OnAccountLinkedResponse) {
    option (google.api.http) = {
        put: "/accounts/linked"
    };
  }

  rpc OnAccountUnlinked (OnAccountUnlinkedRequest) returns (OnAccountUnlinkedResponse) {
    option (google.api.http) = {
        put: "/accounts/unlinked"
    };
  }
}

////////////////////////////////////////////////////////////////////////////////////////////////////
// Consent Management API
//
service ConsentManagementService {
  rpc OnConsentCreated (OnConsentCreatedRequest) returns (OnConsentCreatedResponse) {
    option (google.api.http) = {
        put: "/consent/created"
    };
  }

  rpc OnConsentRevoked (OnConsentRevokedRequest) returns (OnConsentRevokedResponse) {
    option (google.api.http) = {
        put: "/consent/revoked"
    };
  }
}

////////////////////////////////////////////////////////////////////////////////////////////////////
// Health Check API
//
service HealthCheckService {
  rpc HealthCheck (HealthCheckRequest) returns (HealthCheckResponse) {
    option (google.api.http) = {
        get: "/health-check?bank_id={bank_id}"
    };
  }
}