common.v2.openbanking.vrp

io.token.proto.common.v2.openbanking.vrp common/src/main/proto/v2/openbanking/vrp.proto


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

option java_outer_classname = "VrpProtos";

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

message VrpConsent {
  // the list of fields should be kept in sync with io.token.proto.providerapi.VrpConsentUpdate fields:
  // fields that has to be updated by the provider should be listed in the update message
  string id = 1; // The Token generated Vrp consent id.
  string member_id = 2; // The initiator member.
  Initiation initiation = 3;
  string created_date_time = 4; // The time when this consent object is created.
  string updated_date_time = 5; // The last update time for the current status, bank consent status, status reason information and authentication.
  string bank_vrp_consent_id = 6; // The vrp consent id at the bank side. This field could be empty no consent id is available from the bank
  Status status = 7; // Token aggregated status
  string bank_vrp_consent_status = 8; // The raw vrp consent status received the bank. Can be empty if no consent status is available on bank side
  string status_reason_information = 9; // A human-readable description of the reason behind the status
  openbanking.common.Authentication authentication = 10; // Required authentication operation to proceed with the consent

  message Initiation {
    reserved 18;
    string bank_id = 1;
    string ref_id = 2; // The reference id from the customer
    string remittance_information_primary = 3; // try to map it to whatever main remittance field is used in the given standard
    string remittance_information_secondary = 4; // additional remittance field; mapped to a secondary remittance field used by the standard, if any
    string start_date_time = 5; // Date from which payments can be made.
    string end_date_time = 6; // Any payments made after this date will be rejected.
    v2.common.OnBehalfOf on_behalf_of = 7 [deprecated = true]; // We are now using string on_behalf_of_id instead of this.
    VrpType vrp_type = 8;
    v2.common.LocalInstrument local_instrument = 9;
    v2.common.DebtorInformation debtor = 10;
    v2.common.CreditorInformation creditor = 11;
    string maximum_individual_amount = 12; // double amount in the string format.
    string minimum_individual_amount = 13; // double amount in the string format
    repeated PeriodicLimit periodic_limits = 14;
    int32 maximum_occurrences = 15; // Any payments will be rejected if the consent is over its maximum occurrences.
    string callback_url = 16; // the TPP redirect url for the redirect flow.
    string callback_state = 17; // Specify a state for bank callbacks.
    bool return_refund_account = 19;
    StandardSpecific standard_specific = 20 [deprecated=true]; // use fields in risk instead
    string currency = 21; // ISO4217, 3 letter currency code such as "USD" or "EUR".
    string on_behalf_of_id = 22; // Act on behalf of the ultimate clients to initiate the payment. This is only available for gateway or reseller customers.
    v2.common.Risk risk = 23;
  }

  message StandardSpecific {
    option deprecated = true;
    oneof standard {
      openbanking.standard.obie.Payment obie = 1;
    }
  }

  enum Status {
    // the list of statuses should be kept in sync with io.token.proto.providerapi.VrpConsentUpdate.Status values
    INVALID_STATUS = 0;
    PENDING = 1; // Token has received the request to create a VRP consent and it has passed Token's validation
    PENDING_MORE_INFO = 2; // Token requires some mandatory fields that have to be collected before connecting to the bank (e.g. bank_id)
    PENDING_REDIRECT_AUTH = 3; // Token awaits TPP and the PSU to open the redirect url to process.
    PENDING_REDIRECT_AUTH_VERIFICATION = 4; // Token awaits bank to verify the callback result,
    AUTHORIZED = 5; // the VRP consent has been successfully authorized
    REJECTED = 6; // the VRP consent has been rejected. More details are shared in the corresponding status reason information
    REVOKED = 7; // the VRP consent has been revoked by the PSU
    FAILED = 8; // Token failed to proceed with the consent due to problems with reaching the bank
  }
}

enum VrpType {
  INVALID_VRP_TYPE = 0;
  SWEEPING = 1;
  OTHER = 2; // cover all the other use case
}

message PeriodicLimit {
  string maximum_amount = 1; // double amount in the string format
  PeriodType period_type = 2;
  PeriodAlignment period_alignment = 3;
  enum PeriodType {
    INVALID_TYPE = 0;
    DAY = 1;
    WEEK = 2;
    MONTH = 3;
    YEAR = 4;
  }

  enum PeriodAlignment {
    INVALID_ALIGNMENT = 0;
    CONSENT = 1;
    CALENDAR = 2;
  }
}

message Vrp {
  // the list of fields should be kept in sync with io.token.proto.providerapi.VrpUpdate fields:
  // fields that has to be updated by the provider should be listed in the update message
  string id = 1; // The Token generated Vrp id.
  string member_id = 2; // The initiator member.
  Initiation initiation = 3;
  string created_date_time = 4; // The time when this payment object is created.
  string updated_date_time = 5; // The last update time for the current status, sub status, status reason information and authentication.
  string bank_vrp_id = 6; // The vrp id at the bank side. This field could be empty no vrp id is available on bank side
  Status status = 7; // Token aggregated status
  string bank_vrp_status = 8; // The raw vrp status from the bank. Can be empty if no vrp status is available on bank side
  string status_reason_information = 9; // A human-readable description of the reason behind the status
  v2.common.Refund refund_details = 11; // Optional: Only if refund permission and/or request_refund_account is granted

  message Initiation {
    string consent_id = 1;
    string ref_id = 2; // Required. The reference id is used between Token and the direct customer. It requires to be unique per customer.
    string remittance_information_primary = 3; // must match the corresponding field in the consent
    string remittance_information_secondary = 4; // additional remittance field; mapped to a secondary remittance field used by the standard, if any
    money.Money amount = 5;
    bool confirm_funds = 6; // If set, the bank will do fund confirmation check before accepting the payment.
    v2.common.Risk risk = 7;
  }

  enum Status {
    // the list of statuses should be kept in sync with io.token.proto.providerapi.VrpUpdate.Status values
    INVALID_STATUS = 0;
    INITIATION_PENDING = 1; // Token has received the vrp initiation and the initiation has passed Token validation
    INITIATION_PROCESSING = 2; // The initiation is processing on the bank side. Status can be updated to one of INITIATION_COMPLETED or INITIATION_REJECTED or stay INITIATION_PROCESSING forever.
    INITIATION_COMPLETED = 3; // The initiation is successful. This does not guarantee the payment is settled.
    INITIATION_REJECTED = 4; // The initiation is rejected. More details are shared in the corresponding status reason information.
    INITIATION_REJECTED_INSUFFICIENT_FUND = 5; // The initiation is rejected due to insufficient funds; // only applied when we use a separate confirmFunds call
    INITIATION_FAILED = 6;  // Token failed to proceed with the initiation due to problems with reaching the bank
    INITIATION_NO_FINAL_STATUS_AVAILABLE = 7; // This happens when we stop polling the status.
  }
}

// Metadata payload contains all the internal metadata that platform and adapters maintain
// together. These metadata will not be shared to external clients.
//
// The list of fields should be kept in sync with io.token.proto.providerapi.VrpConsentMetadataUpdate fields:
// fields that has to be updated by the provider should be listed in the update message
message VrpConsentMetadata {
  // A state only adapter can understand. Platform will persist it and share with adapters.
  string bank_state = 1;
  // When the bank state should be refreshed. Platform will call the refresh endpoint first.
  string bank_state_refresh_date_time = 2;
  // Records how many callback has been finished. It is useful in adapter getPaymentStatus.
  int32 finished_callback_count = 3;
  // callback url that should be sent to the bank (might differ from the callback_url in the payload)
  string callback_url = 4;
  // a flag confirming that PSU accepted the PISP consent (only required for TPPs using Token's licence);
  // not used by adaptors
  bool pisp_consent_accepted = 5;
}

// The list of fields should be kept in sync with io.token.proto.providerapi.VrpMetadataUpdate fields:
// fields that has to be updated by the provider should be listed in the update message
message VrpMetadata {
  // TBD
}