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
}