1// Copyright 2023 Google LLC 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package google.cloud.paymentgateway.issuerswitch.v1; 18 19import "google/api/annotations.proto"; 20import "google/api/client.proto"; 21import "google/api/field_behavior.proto"; 22import "google/cloud/paymentgateway/issuerswitch/v1/common_fields.proto"; 23import "google/protobuf/field_mask.proto"; 24import "google/protobuf/timestamp.proto"; 25 26option csharp_namespace = "Google.Cloud.PaymentGateway.IssuerSwitch.V1"; 27option go_package = "cloud.google.com/go/paymentgateway/issuerswitch/apiv1/issuerswitchpb;issuerswitchpb"; 28option java_multiple_files = true; 29option java_outer_classname = "ParticipantsProto"; 30option java_package = "com.google.cloud.paymentgateway.issuerswitch.v1"; 31option php_namespace = "Google\\Cloud\\PaymentGateway\\IssuerSwitch\\V1"; 32option ruby_package = "Google::Cloud::PaymentGateway::IssuerSwitch::V1"; 33 34// A service that allows for the management of participants in the issuer 35// switch. 36service IssuerSwitchParticipants { 37 option (google.api.default_host) = "issuerswitch.googleapis.com"; 38 option (google.api.oauth_scopes) = 39 "https://www.googleapis.com/auth/cloud-platform"; 40 41 // Fetch the issuer switch participant. This method can be used to retrieve 42 // all details of a participant in the issuer switch. 43 // 44 // In UPI, the participant is identified by their account's IFSC and their 45 // account number. 46 rpc FetchParticipant(FetchParticipantRequest) returns (IssuerParticipant) { 47 option (google.api.http) = { 48 post: "/v1/{parent=projects/*}/issuerParticipants:fetch" 49 body: "*" 50 }; 51 } 52 53 // Update the issuer switch participant. Currently, this API only allows for 54 // the 55 // [metadata][google.cloud.paymentgateway.issuerswitch.v1.IssuerParticipant.metadata] 56 // field to be updated. 57 // 58 // The `number` of key-value pairs in the `metadata` field, the length of each 59 // `key` and the length of each `value` should be within the thresholds 60 // defined for them in the issuer switch configuration. Any violation of these 61 // thresholds will cause this API to return an error. The default values for 62 // these thresholds are: 63 // 64 // * `Maximum number` of key-value pairs - `5` 65 // * `Maximum length` of a key - `100` 66 // * `Maximum length` of a value - `500` 67 // 68 // **Note** that this method replaces any existing `metadata` field value in 69 // the participant with the new value. Specifically, it does not do a merge. 70 // If key-value pairs are to be added/removed from the metadata, then 71 // callers must follow the following steps: 72 // 73 // 1. Invoke the 74 // [FetchParticipant][google.cloud.paymentgateway.issuerswitch.v1.IssuerSwitchParticipants.FetchParticipant] 75 // API to get the current value of the `metadata` field. 76 // 1. Update the `metadata` map to add/remove key-value pairs from it. 77 // 1. Update the `metadata` in the issuer switch using this method. 78 rpc UpdateIssuerParticipant(UpdateIssuerParticipantRequest) 79 returns (IssuerParticipant) { 80 option (google.api.http) = { 81 post: "/v1/{parent=projects/*}/issuerParticipants:update" 82 body: "issuer_participant" 83 }; 84 option (google.api.method_signature) = 85 "parent,issuer_participant,update_mask"; 86 } 87 88 // Activate the issuer switch participant for UPI transactions. This API 89 // sets the state of the participant to 90 // [ACTIVE][google.cloud.paymentgateway.issuerswitch.v1.IssuerParticipant.State.ACTIVE]. 91 // A participant in the `ACTIVE` state can perform all UPI operations 92 // normally. 93 // 94 // The behavior of this API varies based on the current state of the 95 // participant. 96 // 97 // * Current state is 98 // [ACTIVE][google.cloud.paymentgateway.issuerswitch.v1.IssuerParticipant.State.ACTIVE] 99 // : This API will make no change to the participant's state and returns a 100 // successful response. 101 // * Current state is 102 // [INACTIVE][google.cloud.paymentgateway.issuerswitch.v1.IssuerParticipant.State.INACTIVE] 103 // : If an _MPIN_ has already been provisioned for the participant, then 104 // this API will change the state of the participant to `ACTIVE`. Else, 105 // this API will return an error. 106 // * Current state is 107 // [MOBILE_NUMBER_CHANGED][google.cloud.paymentgateway.issuerswitch.v1.IssuerParticipant.State.MOBILE_NUMBER_CHANGED] 108 // : The state cannot be changed to `ACTIVE`. This API will return an 109 // error. 110 // * Current state is 111 // [NEW_REGISTRATION_INITIATED][google.cloud.paymentgateway.issuerswitch.v1.IssuerParticipant.State.NEW_REGISTRATION_INITIATED] 112 // : The state cannot be changed to `ACTIVE`. This API will return an 113 // error. 114 // * Current state is 115 // [RE_REGISTRATION_INITIATED][google.cloud.paymentgateway.issuerswitch.v1.IssuerParticipant.State.RE_REGISTRATION_INITIATED] 116 // : The state cannot be changed to `ACTIVE`. This API will return an 117 // error. 118 rpc ActivateParticipant(ParticipantStateChangeRequest) 119 returns (IssuerParticipants) { 120 option (google.api.http) = { 121 post: "/v1/{parent=projects/*}/issuerParticipants:activate" 122 body: "*" 123 }; 124 } 125 126 // Deactivate the issuer switch participant for UPI transactions. This API 127 // sets the state of the participant to 128 // [INACTIVE][google.cloud.paymentgateway.issuerswitch.v1.IssuerParticipant.State.INACTIVE]. 129 // An `INACTIVE` participant cannot perform any UPI operation which involves 130 // MPIN verification. 131 // 132 // The behavior of this API varies based on the current state of the 133 // participant. 134 // 135 // * Current state is 136 // [ACTIVE][google.cloud.paymentgateway.issuerswitch.v1.IssuerParticipant.State.ACTIVE] 137 // : The state will change to `INACTIVE`. The user will be forced to 138 // re-register with UPI and reset their MPIN to perform any UPI 139 // operations. 140 // * Current state is 141 // [INACTIVE][google.cloud.paymentgateway.issuerswitch.v1.IssuerParticipant.State.INACTIVE] 142 // : This API will make no change to the participant's state and returns a 143 // successful response. 144 // * Current state is 145 // [MOBILE_NUMBER_CHANGED][google.cloud.paymentgateway.issuerswitch.v1.IssuerParticipant.State.MOBILE_NUMBER_CHANGED] 146 // : The state cannot be changed to `INACTIVE`. This API will return an 147 // error. 148 // * Current state is 149 // [NEW_REGISTRATION_INITIATED][google.cloud.paymentgateway.issuerswitch.v1.IssuerParticipant.State.NEW_REGISTRATION_INITIATED] 150 // : The state cannot be changed to `INACTIVE`. This API will return an 151 // error. 152 // * Current state is 153 // [RE_REGISTRATION_INITIATED][google.cloud.paymentgateway.issuerswitch.v1.IssuerParticipant.State.RE_REGISTRATION_INITIATED] 154 // : The state cannot be changed to `INACTIVE`. This API will return an 155 // error. 156 rpc DeactivateParticipant(ParticipantStateChangeRequest) 157 returns (IssuerParticipants) { 158 option (google.api.http) = { 159 post: "/v1/{parent=projects/*}/issuerParticipants:deactivate" 160 body: "*" 161 }; 162 } 163 164 // Mark the state of the issuer switch participant as _mobile number changed_ 165 // to prevent UPI transactions by the user. This API sets the state of the 166 // participant to 167 // [MOBILE_NUMBER_CHANGED][google.cloud.paymentgateway.issuerswitch.v1.IssuerParticipant.State.MOBILE_NUMBER_CHANGED]. 168 // 169 // Any UPI operation for a participant in the `MOBILE_NUMBER_CHANGED` state 170 // will cause the issuer switch to return a `B1` error to the UPI payments 171 // orchestrator which would force the user to re-register with UPI. 172 // 173 // The behavior of this API varies based on the current state of the 174 // participant. 175 // 176 // * Current state is 177 // [ACTIVE][google.cloud.paymentgateway.issuerswitch.v1.IssuerParticipant.State.ACTIVE] 178 // : The state will change to `MOBILE_NUMBER_CHANGED`. Any operation 179 // involving MPIN verification of the participant will return a `B1` error 180 // to the UPI payments orchestrator. The user will be forced to 181 // re-register with their changed mobile number. 182 // * Current state is 183 // [INACTIVE][google.cloud.paymentgateway.issuerswitch.v1.IssuerParticipant.State.INACTIVE] 184 // : The state will change to `MOBILE_NUMBER_CHANGED`. Any operation 185 // involving MPIN verification of the participant will return a `B1` error 186 // to the UPI payments orchestrator. The user will be forced to 187 // re-register with their changed mobile number. 188 // * Current state is 189 // [MOBILE_NUMBER_CHANGED][google.cloud.paymentgateway.issuerswitch.v1.IssuerParticipant.State.MOBILE_NUMBER_CHANGED] 190 // : This API will make no change to the participant's state and returns a 191 // successful response. 192 // * Current state is 193 // [NEW_REGISTRATION_INITIATED][google.cloud.paymentgateway.issuerswitch.v1.IssuerParticipant.State.NEW_REGISTRATION_INITIATED] 194 // : The state cannot be changed to `MOBILE_NUMBER_CHANGED`. This API will 195 // return an error. 196 // * Current state is 197 // [RE_REGISTRATION_INITIATED][google.cloud.paymentgateway.issuerswitch.v1.IssuerParticipant.State.RE_REGISTRATION_INITIATED] 198 // : The state will change to `MOBILE_NUMBER_CHANGED`. Any operation 199 // involving MPIN verification of the participant will return a `B1` error 200 // to the UPI payments orchestrator. The user will be forced to 201 // re-register with their changed mobile number. 202 rpc MobileNumberChanged(ParticipantStateChangeRequest) 203 returns (IssuerParticipants) { 204 option (google.api.http) = { 205 post: "/v1/{parent=projects/*}/issuerParticipants:mobileNumberChanged" 206 body: "*" 207 }; 208 } 209} 210 211// Request for the 212// [FetchParticipant][google.cloud.paymentgateway.issuerswitch.v1.IssuerSwitchParticipants.FetchParticipant] 213// method. 214message FetchParticipantRequest { 215 // Required. The parent resource for the participants. The format is 216 // `projects/{project}`. 217 string parent = 1 [(google.api.field_behavior) = REQUIRED]; 218 219 // Required. The account details of the issuer participant. 220 AccountReference account_reference = 2 221 [(google.api.field_behavior) = REQUIRED]; 222} 223 224// A customer of the bank who participates in transactions processed by the 225// issuer switch. 226message IssuerParticipant { 227 // The state of the participant. 228 enum State { 229 // Unspecified state. 230 STATE_UNSPECIFIED = 0; 231 232 // The participant is inactive for all UPI transactions. The issuer switch 233 // will return the `AM` error to the UPI payments orchestrator for any 234 // operation involving MPIN verification for the participant. They need to 235 // register with UPI again and provide a new MPIN. 236 INACTIVE = 1; 237 238 // The participant is active for all UPI transactions. 239 ACTIVE = 2; 240 241 // The participants MPIN has been locked because they have exceeded the 242 // threshold for maximum number of incorrect MPIN verification attempts. No 243 // UPI transactions will be permitted until the participant's MPIN has been 244 // reset. 245 MPIN_LOCKED = 3; 246 247 // The participants mobile number has been changed in the issuer bank. Any 248 // transaction involving MPIN verification of the participant will return a 249 // `B1` error to the UPI payments orchestrator. The user will be forced to 250 // re-register with their changed mobile number. 251 MOBILE_NUMBER_CHANGED = 4; 252 253 // The participant is registering for UPI transactions for the first time. 254 NEW_REGISTRATION_INITIATED = 5; 255 256 // The participant had already registered for UPI transactions but is now 257 // registering again or resetting their MPIN. 258 RE_REGISTRATION_INITIATED = 6; 259 } 260 261 // The metadata of the participant. 262 message Metadata { 263 // Optional. Additional metadata about a particular participant as key-value 264 // pairs. These values are returned by the bank adapter/card adapter in 265 // response to the SearchAccounts/InitiateRegistration APIs. 266 map<string, string> values = 1 [(google.api.field_behavior) = OPTIONAL]; 267 } 268 269 // Required. The account details of the issuer participant. Only the 270 // account_number and ifsc fields will be used. 271 AccountReference account_reference = 1 272 [(google.api.field_behavior) = REQUIRED]; 273 274 // Output only. The mobile number of the participant. 275 string mobile_number = 2 [(google.api.field_behavior) = OUTPUT_ONLY]; 276 277 // Output only. The current state of the participant. 278 State state = 3 [(google.api.field_behavior) = OUTPUT_ONLY]; 279 280 // Optional. Additional metadata about the participant. 281 Metadata metadata = 4 [(google.api.field_behavior) = OPTIONAL]; 282 283 // Output only. The current count of consecutive incorrect MPIN attempts. 284 int32 mpin_failure_count = 5 [(google.api.field_behavior) = OUTPUT_ONLY]; 285 286 // Output only. The time when participant's MPIN got locked due to too many 287 // incorrect attempts. 288 google.protobuf.Timestamp mpin_locked_time = 6 289 [(google.api.field_behavior) = OUTPUT_ONLY]; 290 291 // Output only. The time when the participant's account was onboarded to PGIS. 292 google.protobuf.Timestamp create_time = 7 293 [(google.api.field_behavior) = OUTPUT_ONLY]; 294 295 // Output only. The time when the participant was last updated. 296 google.protobuf.Timestamp update_time = 8 297 [(google.api.field_behavior) = OUTPUT_ONLY]; 298} 299 300// Request for the 301// [UpdateIssuerParticipant][google.cloud.paymentgateway.issuerswitch.v1.IssuerSwitchParticipants.UpdateIssuerParticipant] 302// method. 303message UpdateIssuerParticipantRequest { 304 // Required. The parent resource for the participants. The format is 305 // `projects/{project}`. 306 string parent = 1 [(google.api.field_behavior) = REQUIRED]; 307 308 // Required. The participant to update. 309 IssuerParticipant issuer_participant = 2 310 [(google.api.field_behavior) = REQUIRED]; 311 312 // Required. The list of fields to update. 313 google.protobuf.FieldMask update_mask = 3 314 [(google.api.field_behavior) = REQUIRED]; 315} 316 317// Request for the 318// [ActivateParticipant][google.cloud.paymentgateway.issuerswitch.v1.IssuerSwitchParticipants.ActivateParticipant], 319// [DeactivateParticipant][google.cloud.paymentgateway.issuerswitch.v1.IssuerSwitchParticipants.DeactivateParticipant] 320// and 321// [MobileNumberUpdated][google.cloud.paymentgateway.issuerswitch.v1.IssuerSwitchParticipants.MobileNumberChanged] 322// methods. 323message ParticipantStateChangeRequest { 324 // Required. The parent resource for the participant. The format is 325 // `projects/{project}`. 326 string parent = 1 [(google.api.field_behavior) = REQUIRED]; 327 328 // The identifier for the issuer participant. One of the two values must be 329 // specified. 330 oneof id { 331 // Optional. The account details of the issuer participant. 332 AccountReference account_reference = 2 333 [(google.api.field_behavior) = OPTIONAL]; 334 335 // Optional. The mobile number of the issuer participant. 336 string mobile_number = 3 [(google.api.field_behavior) = OPTIONAL]; 337 } 338} 339 340// Response for the 341// [ActivateParticipant][google.cloud.paymentgateway.issuerswitch.v1.IssuerSwitchParticipants.ActivateParticipant], 342// [DeactivateParticipant][google.cloud.paymentgateway.issuerswitch.v1.IssuerSwitchParticipants.DeactivateParticipant] 343// and 344// [MobileNumberChanged][google.cloud.paymentgateway.issuerswitch.v1.IssuerSwitchParticipants.MobileNumberChanged] 345// methods. 346message IssuerParticipants { 347 // Output only. The list of updated participants. 348 repeated IssuerParticipant participants = 1 349 [(google.api.field_behavior) = OUTPUT_ONLY]; 350} 351