providerapi

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


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

import "account.proto";
import "token.proto";
import "transferinstructions.proto";
import "extensions/field.proto";

message Account {
  string id = 1 [(io.token.proto.extensions.field.redact) = true];
  string name = 2 [(io.token.proto.extensions.field.redact) = true];
  string number = 3 [(io.token.proto.extensions.field.redact) = true];
  string state = 4;
}

message Transaction {
  string id = 1;
  string account_id = 2 [(io.token.proto.extensions.field.redact) = true];
  string amount = 3;
  string currency = 4; // ISO4217: 3 letter code such as "USD" or "EUR"
  Type type = 5;
  Status status = 6;
  string account_number = 7 [(io.token.proto.extensions.field.redact) = true]; // Optional account number of the transaction
  string description = 8 [(io.token.proto.extensions.field.redact) = true]; // Optional description of the transaction
  int64 created_at = 9; // Optional timestamp in milliseconds, use booking date if creation date is not available

  map<string, string> metadata = 10 [(io.token.proto.extensions.field.redact) = true]; // Optional additional fields.

  enum Status {
    INVALID = 0;
    SUCCESS = 1;
    INSUFFICIENT_FUNDS = 2;
    FAILURE = 3;
    PENDING = 4;
    SENT = 5;
  }

  enum Type {
    INVALID_TYPE = 0;
    DEBIT = 1;
    CREDIT = 2;
  }
}

message Balance {
  string amount = 1;
  string available_amount = 2;
  string currency = 3; // ISO4217: 3 letter code such as "USD" or "EUR"
}

message TransferPayload {
  string amount = 1;
  string currency = 2; // ISO4217: 3 letter code such as "USD" or "EUR"
  string reference_id = 3;
  string description = 4 [(io.token.proto.extensions.field.redact) = true]; // Optional description
  io.token.proto.common.transferinstructions.TransferInstructions.Metadata metadata = 5;
  repeated io.token.proto.common.transferinstructions.TransferEndpoint destinations = 6;
}

message GetBalanceRequest {
  string bank_id = 1;
  string account_id = 2;
  string account_state = 3;
}

message GetBalanceResponse {
  Balance balance = 1;
}

message GetTransactionsRequest {
  string bank_id = 1;
  string account_id = 2;
  string account_state = 3;
  int32 limit = 5;
  string offset = 6;
}

message GetTransactionsResponse {
  repeated Transaction transactions = 1;
  string offset = 2;
}

message GetTransactionRequest {
  string bank_id = 1;
  string account_id = 2;
  string account_state = 3;
  string transaction_id = 4;
}

message GetTransactionResponse {
  Transaction transaction = 1;
}

message ResolveDestinationRequest {
  string bank_id = 1;
  string account_id = 2;
  string account_state = 3;
}

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

message TransferRequest {
  string bank_id = 1;
  string account_id = 2; // Optional, empty for appless flow
  string payment_state = 3;
  TransferPayload payload = 4;
}

message TransferResponse {
  Transaction transaction = 1;
}

message InitiatePaymentRequest {
  string bank_id = 1;
  string account_id = 2; // Optional, empty in appless flow
  string account_state = 3; // Optional, empty in appless flow
  string client_state = 4;
  string member_state = 5; // Optional
  TransferPayload payload = 6;
  string callback_uri = 7;
}

message InitiatePaymentResponse {
  string member_state = 1;
  string redirect_url = 2; // Optional; external authorization required if present
}

message PaymentCallbackRequest {
  string bank_id = 1;
  map<string, string> parameters = 2 [(io.token.proto.extensions.field.redact) = true];
}

message PaymentCallbackResponse {
  string payment_state = 2;
  string client_state = 3;
}

message InitiateLinkingRequest {
  string bank_id = 1;
  string client_state = 2;
  string member_state = 3; // Optional
  string callback_uri = 4;
}

message InitiateLinkingResponse {
  string member_state = 1;
  string redirect_url = 2;
}

message LinkingCallbackRequest {
  string bank_id = 1;
  map<string, string> parameters = 2 [(io.token.proto.extensions.field.redact) = true];
}

message LinkingCallbackResponse {
  repeated Account accounts = 1;
  string client_state = 2;
}

service AccountService {
  rpc GetBalance (GetBalanceRequest) returns (GetBalanceResponse) {}

  rpc GetTransactions (GetTransactionsRequest) returns (GetTransactionsResponse) {}

  rpc GetTransaction (GetTransactionRequest) returns (GetTransactionResponse) {}

  rpc ResolveDestination (ResolveDestinationRequest) returns (ResolveDestinationResponse) {}
}

service TransferService {
  rpc Transfer (TransferRequest) returns (TransferResponse) {}

  rpc InitiatePayment (InitiatePaymentRequest) returns (InitiatePaymentResponse) {}

  rpc PaymentCallback (PaymentCallbackRequest) returns (PaymentCallbackResponse) {}
}

service LinkingService {
  rpc InitiateLinking (InitiateLinkingRequest) returns (InitiateLinkingResponse) {}

  rpc LinkingCallback (LinkingCallbackRequest) returns (LinkingCallbackResponse) {}
}