Package google.cloud.paymentgateway.issuerswitch.bankadapter.v1

Stay organized with collections Save and categorize content based on your preferences.

Index

BankAdapterService

A service interface for the Issuer Switch Bank Adapter.

HoldFunds

rpc HoldFunds(HoldFundsRequest) returns (HoldFundsResponse)

Hold funds in the specified account.

This API should return a 400 HTTP status code if it is unable to process the request. The reason field in the ErrorInfo response should contain one of the following values:

  • ACCT_BLOCKED = Account is blocked.

  • ACCT_DORMANT = Account is dormant.

  • ACCT_FROZEN = Account is frozen.

  • ACCT_INACTIVE = Account is inactive.

  • ACCT_NOT_FOUND = Account not found in the bank's systems.

  • INSUFFICIENT_FUNDS = Insufficient funds in account to process request.

  • INVALID_TRANSACTION = Invalid transaction.

  • TRANSACTION_NOT_PERMITTED = Requested transaction is not permitted for account.

  • HOLD_FUNDS_NOT_ALLOWED = Hold funds is not allowed on certain account types.

  • DEBIT_NOT_ALLOWED = Debits are not allowed on this type of account.

Note: This API will be invoked in the UPI ReqMandate and ReqVoucher API flows.

InitiateRegistration

rpc InitiateRegistration(InitiateRegistrationRequest) returns (InitiateRegistrationResponse)

Initiates the registration of a customer's bank account with UPI on the issuer bank. Either a customer reference (such as a resident id, like Aadhaar or a mobile phone number) must be specified, or a bank account reference must be provided.

It is expected that the bank adapter service will trigger an SMS OTP to be sent to the customer's mobile phone.

This API should return a 400 HTTP status code if it is unable to process the request. The reason field in the ErrorInfo response should contain one of the following values:

  • ACCT_BLOCKED = Account is blocked.

  • ACCT_DORMANT = Account is dormant.

  • ACCT_FROZEN = Account is frozen.

  • ACCT_INACTIVE = Account is inactive.

  • ACCT_NOT_FOUND = Account not found in the bank's systems.

  • INVALID_DEBIT_CARD = Debit card details provided are invalid.

  • MOBILE_NUMBER_MULTIPLE_CUSTOMERS = Mobile number is linked with multiple customers.

Note: This API will be invoked in the UPI ReqOtp API flow.

NotifyCustomer

rpc NotifyCustomer(NotifyCustomerRequest) returns (Empty)

This is an API to notify the bank's customer via SMS/email when certain actions are taken by the issuer switch, or when it receives certain notifications from the NPCI.

There are a few scenarios when this API will be invoked by the issuer switch.

  1. The validation of the current M-PIN of a user, and the updating to a new M-PIN is handled by the issuer switch. The bank adapter is invoked after the new M-PIN has been updated successfully by the issuer switch for any further processing by the bank's systems. The NPCI circular RMD-014 requires issuer banks to send an SMS notification to customers when the UPI M-PIN is successfully set for a user. This is to make the user aware of any fradulent attempts to modify the user's M-PIN. This SMS notification could be one of the possible actions taken when this API is invoked on the Bank Adapter. Note that a customer is to be notified both in the case of a successful update of their M-PIN or when the M-PIN update fails.

  2. The issuer switch performs a number of operations with recurring (auto-pay) mandates. These include the following operations:

  • Creation
  • Modification
  • Revocation
  • Pause
  • Unpause

The NPCI circular OC-151 requires the issuer switch to notify the customer of the success/failure of the operation with an SMS. The issuer switch will invoke this Bank Adapter API with the details about the specific operation performed with the recurring (auto-pay) mandate. The Bank Adapter can then invoke other services to send out the appropriate SMS notification to the customer.

  1. 24 hours before a recurring mandate accepted by a customer is to be used for a payment settlement, a notification is to be sent to the customer with details about the mandate that will be executed. The issuer switch will invoke the bank adapter with all the details about the mandate that is to be executed in the next 24 hours for further processing by the bank adapter. This could include the bank adapter invoking the appropriate services in the bank's backend to notify the customer about the upcoming mandate execution. The NPCI's Recurring Mandate Technical Specification document describes this requirement. This notification is to allow the customer to either pause / revoke the mandate, or ensure that there are sufficient funds available in the account that will be debited upon mandate execution.

This API should return a 400 HTTP status code if it is unable to process the request. The reason field in the ErrorInfo response should contain one of the following values:

  • ACCT_BLOCKED = Account is blocked.

  • ACCT_DORMANT = Account is dormant.

  • ACCT_FROZEN = Account is frozen.

  • ACCT_INACTIVE = Account is inactive.

  • ACCT_NOT_FOUND = Account not found in the bank's systems.

Note: This API will be invoked in the UPI ReqSetCre API flow, or in the ReqValCust (mandate notification) API flow.

ReleaseFunds

rpc ReleaseFunds(ReleaseFundsRequest) returns (Empty)

Release funds previously held in the specified account.

This API should return a 400 HTTP status code if it is unable to process the request. The reason field in the ErrorInfo response should contain one of the following values:

  • ACCT_BLOCKED = Account is blocked.

  • ACCT_DORMANT = Account is dormant.

  • ACCT_FROZEN = Account is frozen.

  • ACCT_INACTIVE = Account is inactive.

  • ACCT_NOT_FOUND = Account not found in the bank's systems.

  • INSUFFICIENT_FUNDS = Insufficient funds in account to process request.

  • INVALID_TRANSACTION = Invalid transaction.

  • TRANSACTION_NOT_PERMITTED = Requested transaction is not permitted for account.

  • NO_FUNDS_ON_HOLD = Blocked funds have already been released.

Note: This API will be invoked in the UPI ReqMandate and ReqVoucher API flows.

ResolvePayment

rpc ResolvePayment(ResolvePaymentRequest) returns (ResolvePaymentResponse)

Note: Implementation of this Bank Adapter API is optional. Implement this API only if your bank wants to handle the unresolved payments all by itself.

Payment settlements done using the Bank Adapter service might fail because of various reasons such as time-out of the SettlePayment API or network failure. In the event of such a failure, the Issuer Switch does not receive the final status of the payment settlement. To handle unresolved payments, you can configure the Issuer Switch in either Search & Settle or Resolve Payment mode.

  • Search & Settle - This is the default configuration of the Issuer Switch. In this mode, the Issuer Switch handles the orchestration using the SearchPayments API to obtain the status of a payment settlement, and based on the state of the payment, it invokes the SettlePayment API to settle the payments.
  • Resolve Payment - In this mode the Issuer Switch delegates the task of checking the current status of a payment settlement and its possible re-execution to the bank adapter service / bank's core services. Use this mode if your bank wants to handle the unresolved payments all by itself. To enable this mode, you must implement the ResolvePayment API. If the Issuer Switch is configured in this mode, then the ResolvePayment API is invoked for all the unresolved transactions.

Based on the NPCI request, the Issuer Switch invokes the ResolvePayment API to resolve the payment settlement transaction and obtain its final status. This API is invoked to resolve a unresolved payment settlement of the following types:

  • Debit Reversal
  • Credit

Note: The Issuer Switch will not invoke this API if the final status of the payment settlement operation is already available with it.

If the bank adapter service attempts to resolve the payment, but is unable to resolve it successfully, then this API must return a HTTP status of 200 with the ResolvePaymentResponse containing [ResolutionStatus][] as FAILED and the appropriate error code in ResolvePaymentResult. Specifically, a non-200 HTTP status must be returned only when the bank adapter service itself fails and not when the resolution of the payment settlement fails.

The ErrorReason values that are allowed in the PaymentAdjustmentError in the ResolvePaymentResult are:

  • ACCT_INACTIVE = Indicates that the payer account is inactive, if the settlement request is for a debit reversal or that the payee account is inactive, if the settlement request is for a credit.

  • ACCT_FROZEN = Indicates that the payer account is frozen, if the settlement request is for a debit reversal or that the payee account is frozen, if the settlement request is for a credit.

  • UNABLE_TO_UPDATE_BANK_SERVICES = Indicates that the bank adapter service could not update the bank's services.

  • PARTY_INSTRUCTIONS = Indicates that the resolution of the payment failed due to party instructions.

  • DUPLICATE_PROCESSING = Indicates that the resolution request is a duplicate.

  • PAYMENT_UDIR_RET_114 = Indicates that the resolution failed due to error 114 as part of beneficiary bank attempting to resolve a TCC case.

  • PAYMENT_UDIR_RET_115 = Indicates that the resolution failed due to error 115 as part of beneficiary bank attempting to resolve a TCC case.

  • PAYMENT_UDIR_RET_116 = Indicates that the resolution failed due to error 116 as part of beneficiary bank attempting to resolve a TCC case.

  • PAYMENT_UDIR_RET_117 = Indicates that the resolution failed due to error 117 as part of beneficiary bank attempting to resolve a TCC case.

  • PAYMENT_UDIR_RET_118 = Indicates that the resolution failed due to error 118 as part of beneficiary bank attempting to resolve a TCC case.

  • PAYMENT_UDIR_RET_119 = Indicates that the resolution failed due to error 119 as part of beneficiary bank attempting to resolve a TCC case.

  • PAYMENT_UDIR_RET_120 = Indicates that the resolution failed due to error 120 as part of beneficiary bank attempting to resolve a TCC case.

Note: This API will be invoked as part of UPI's Online Dispute and Issue Resolution (UDIR) flows. Specifically, this API will be invoked in the UPI ReqChkTxn (transaction type AUTOUPDATE) and ReqComplaint (transaction type Complaint) API flow.

RetrieveBalance

rpc RetrieveBalance(RetrieveBalanceRequest) returns (RetrieveBalanceResponse)

Retrieves the account balance information for the specified account.

This API should return a 400 HTTP status code if it is unable to process the request. The reason field in the ErrorInfo response should contain one of the following values:

  • ACCT_BLOCKED = Account is blocked.

  • ACCT_DORMANT = Account is dormant.

  • ACCT_FROZEN = Account is frozen.

  • ACCT_INACTIVE = Account is inactive.

  • ACCT_NOT_FOUND = Account not found in the bank's systems.

Note: This API will be invoked in the UPI ReqBalEnq API flow.

SearchAccounts

rpc SearchAccounts(SearchAccountsRequest) returns (SearchAccountsResponse)

Search and return a list of accounts associated with a given customer. The customer may be identified in one of many ways (mobile number, email, unique national id, payment address, etc).

Accounts can be searched with one of two filters:

  1. Customer reference - For UPI, the supported customer identifiers are Mobile number or Aadhaar number. All accounts associated with the specified customer identifier need to be returned. The response will be zero or more accounts.
  2. Account reference - For UPI, this is the IFSC code and number of an account. The bank adapter should search for the specified account reference in the bank. The response will be either zero accounts or exactly one account.

NOTE: If no matching accounts are found for the given reference in the request, the response is a success with zero accounts. This condition is not an error.

This API should return a 400 HTTP status code if it is unable to process the request. The reason field in the ErrorInfo response should contain one of the following values:

  • ACCT_BLOCKED = Account linked with customer identifier is blocked.

  • ACCT_DORMANT = Account linked with customer identifier is dormant.

  • ACCT_FROZEN = Account linked with customer identifier is frozen.

  • ACCT_INACTIVE = Account linked with customer identifier is inactive.

  • ACCT_NOT_FOUND = No account(s) were found in the bank's systems linked with the customer identifier.

  • ACCT_MULTIPLE_CUSTOMERS = Indicates that the account is associated with multiple customers.

  • MOBILE_NUMBER_MULTIPLE_CUSTOMERS = Indicates that the same mobile number is associated with multiple customers in the bank's systems.

Note: This API will be invoked in the UPI ReqListAccount API flow.

SearchPayments

rpc SearchPayments(SearchPaymentsRequest) returns (SearchPaymentsResponse)

Returns information about a specific payment. The payment to search can be specified using various filter criteria. The request will contain all the values that could be used to search for the payment settlement.

If no matching payments are found, then this API must return a HTTP status of 200 with an empty list of payments in the response. A non-200 HTTP status must be returned only when the bank adapter service itself fails.

Note: This API will be invoked in the UPI ReqChkTxn (transaction type ChkTxn or AUTOUPDATE) and ReqComplaint API flows.

SettlePayment

rpc SettlePayment(SettlePaymentRequest) returns (SettlePaymentResponse)

Request issued by the Issuer Switch for the bank to execute a single payment settlement operation. The operation is either to debit a payer's account or to credit a payee's account.

This API should return a 400 HTTP status code if it is unable to process the request. The reason field in the ErrorInfo response should contain one of the following values:

  • ACCT_BLOCKED = Indicates that the payer account is blocked, if the settlement request is for a debit or that the payee account is blocked, if the settlement request is for a credit.

  • ACCT_DORMANT = Indicates that the payer account is dormant, if the settlement request is for a debit or that the payee account is dormant, if the settlement request is for a credit.

  • ACCT_FROZEN = Indicates that the payer account is frozen, if the settlement request is for a debit or that the payee account is frozen, if the settlement request is for a credit.

  • ACCT_INACTIVE = Indicates that the payer account is inactive, if the settlement request is for a debit or that the payee account is inactive, if the settlement request is for a credit.

  • ACCT_NOT_FOUND = Indicates that the payer account is not found, if the settlement request is for a debit or that the payee account is not found, if the settlement request is for a credit.

  • DEBIT_NOT_ALLOWED = Returned if debits are not allowed on the account type (such as CC, PF or PPF account).

  • INSUFFICIENT_FUNDS = Returned if the settlement type is debit and the payer's account does not have sufficient funds for the instructed amount.

  • INVALID_TRANSACTION = Requested settlement cannot be performed.

  • MAX_BALANCE_EXCEEDED = Returned if the settlement type is credit and the payee's account's maximum balance allowed value will be breached with the instructed amount.

  • FRAUDULENT_TRANSACTION = Returned if the settlement type is debit or credit and the requested transaction is suspected to be fraudulent due to high risk score.

  • REGISTERED_MOBILE_NUMBER_CHANGED = Returned if the settlement type is debit or credit and the registered mobile number linked to the account has been changed or removed.

  • STOPPED_BY_COURT_ORDER = Returned if the payment settlement was stopped because of a court order. This is typically used during mandate execution and is based on circular OC-128

Note: This API will be invoked in the UPI ReqPay, ReqChkTxn-AUTOUPDATE and ReqComplaint API flows.

ValidateCustomer

rpc ValidateCustomer(CustomerValidationRequest) returns (CustomerValidationResponse)

Validates a customer's government issued ID against the KYC (Know Your Customer) details stored by the bank for that customer.

The request will contain the following information:

  1. ID type and the ID value that needs to be validated.
  2. Account type and the account number of the customer.

Note: Issuer Switch supports only the PAN (Permanent Account Number) ID type in the current release.

Set the valid field in the response to TRUE, if the ID matches the account details of the customer in the request, and to FALSE otherwise.

This API should return a 400 HTTP status code if it is unable to process the request. The reason field in the ErrorInfo response should contain one of the following values:

  • ACCT_BLOCKED = Account is blocked.

  • ACCT_DORMANT = Account is dormant.

  • ACCT_FROZEN = Account is frozen.

  • ACCT_INACTIVE = Account is inactive.

  • ACCT_NOT_FOUND = Account not found in the bank's systems.

Note: This API will be invoked in the UPI ReqValCust API flow.

ValidateRegistration

rpc ValidateRegistration(ValidateRegistrationRequest) returns (Empty)

Validates a previously initiated registration request for a customer's bank account with UPI on the issuer bank. Either a customer reference (such as a resident id, like Aadhaar or a mobile phone number) must be specified, or a bank account reference must be provided.

The following security details must be validated by the bank adapter service with the bank's backend systems:

  1. Debit card details
  2. ATM PIN
  3. SMS OTP

This API should return a 400 HTTP status code if it is unable to process the request. The reason field in the ErrorInfo response should contain one of the following values:

  • ACCT_BLOCKED = Account is blocked.

  • ACCT_DORMANT = Account is dormant.

  • ACCT_FROZEN = Account is frozen.

  • ACCT_INACTIVE = Account is inactive.

  • ACCT_NOT_FOUND = Account not found in the bank's systems.

  • CARD_MANAGEMENT_SYSTEM_FAILURE = Bank card management system is down.

  • INACTIVE_DEBIT_CARD = Debit card is inactive.

  • INCORRECT_ATM_PIN = Incorrect ATM pin.

  • INCORRECT_OTP = OTP provided is incorrect.

  • INVALID_DEBIT_CARD = Debit card details provided are invalid.

  • EXPIRED_DEBIT_CARD = Debit card is expired.

  • MOBILE_NUMBER_MULTIPLE_CUSTOMERS = Mobile number is linked with multiple customers.

  • OTP_EXPIRED = Specified OTP has expired.

  • RESTRICTED_DEBIT_CARD = Debit card is restricted.

Note: This API will be invoked in the UPI ReqRegMob API flow.

AccountInfo

Provides information about an account.

Fields
account_reference

AccountReference

Information about an account as per India's UPI standards.

display_name

string

The name of the account.

account_alias

string

Alias set by the customer to easily identify an account.

aadhaar_enabled

bool

Boolean field indicating if Aadhaar is enabled for the account.

AccountReference

Unique identification of an account according to India's UPI standards.

Fields
ifsc_code

string

IFSC code of a bank's branch.

account_type

string

Type of account.

account_number

string

Unique number for the account in a bank and branch.

AdditionalInfo

Provides additional informations about an entity.

Fields
name

string

Field name.

value

string

Field value.

Amount

Represents an monetary amount in a given currency.

Fields
currency_code

string

The 3-letter currency code as defined in ISO 4217.

amount

string

The amount with fractional digits, where fractions can have between 2 and 4 digits. Negative amounts are represented with a prefix -ve sign. The decimal separator is a dot. In India, only 2 digits will be used after the decimal separator.

BalanceInfo

Balance information for a given account.

Fields
current_balance

Amount

The currency and value of the current balance.

available_balance

Amount

The currency and value of the available balance.

credit_limit

Amount

The allowed credit limit on the account.

CaseDetails

Provides details of the case raised by a user / remitter bank.

Fields
type

CaseType

Type of the case raised.

reason

CaseReason

Reason of the case raised.

initiation_mode

InitiationMode

Specifies how the case was raised,

adjustment_amount

Amount

Specifies the amount to be adjusted.

original_settlement_code

string

Settlement code of the original unresolved transaction.

curr_cycle

bool

Specifies if the complaint/dispute belongs to current settlement cycle or not.

CaseReason

Reason of the case raised.

Enums
CASE_REASON_UNSPECIFIED Case reason unspecified.
COMPLAINT_RAISE_GOODS_SERVICES_NOT_PROVIDED This indicates that a complaint is raised as goods or services are not provided to payer for approved transaction. This maps to reason code U008 defined in NPCI's UDIR specification.
COMPLAINT_RAISE_PAYER_CREDIT_NOT_RECEIVED_FOR_CANCELLED_GOODS_AND_SERVICES This indicates that a complaint is raised as payer credit is not processed for cancelled or returned goods & services. This maps to reason code U021 defined in NPCI's UDIR specification.
COMPLAINT_RAISE_MERCHANT_ACCOUNT_NOT_CREDITED This indicates that a complaint is raised as payer account is debited but transaction confirmation not received at merchant location. This maps to reason code U022 defined in NPCI's UDIR specification.
COMPLAINT_RAISE_PAYER_CREDIT_NOT_RECEIVED_FOR_DECLINED_MERCHANT_TRANSACTION This indicates that a complaint is raised as payer account is not credited back for declined merchant transaction. This maps to reason code U009 defined in NPCI's UDIR specification.
COMPLAINT_RAISE_DUPLICATE_PAYMENT This indicates that a complaint is raised as payment was already made by alternate means. This maps to reason code U023 defined in NPCI's UDIR specification.
COMPLAINT_RAISE_PAYEE_ACCOUNT_NOT_CREDITED This indicates that a complaint is raised as payee account is not credited for successful pay transaction. This maps to reason code U010 defined in NPCI's UDIR specification.
COMPLAINT_RAISE_PAYER_CREDIT_NOT_RECEIVED_FOR_DECLINED_P2P_TRANSACTION This indicates that a complaint is raised as payer account is not credited back for declined P2P transaction. This maps to reason code U005 defined in NPCI's UDIR specification.
RET_ACCOUNT_CLOSED This indicates that a return is initiated as the payee account is closed. This maps to reason code 114 defined in NPCI's UDIR specification.
RET_ACCOUNT_DOES_NOT_EXIST This indicates that a return is initiated as the payee account does not exist. This maps to reason code 115 defined in NPCI's UDIR specification.
RET_PARTY_INSTRUCTIONS This indicates that a return is initiated due to party instructions. This maps to reason code 116 defined in NPCI's UDIR specification.
RET_NRI_ACCOUNT This indicates that a return is initiated as payee account is NRI account. This maps to reason code 117 defined in NPCI's UDIR specification.
RET_CREDIT_FREEZED This indicates that a return is initiated as payee account has credit freezed. This maps to reason code 118 defined in NPCI's UDIR specification.
RET_INVALID_BENEFICIARY_DETAILS This indicates that a return in initiated due to invalid payee details. This maps to reason code 119 defined in NPCI's UDIR specification.
RET_OTHERS This maps to reason code 120 defined in NPCI's UDIR specification.
CREDIT_ADJUSTMENT_CREDIT_NOT_RECEIVED_FOR_CANCELLED_GOODS_SERVICES This indicates that a credit adjustment is initiated as credit was not provided for cancelled goods or services. This maps to reason code 1061 defined in NPCI's UDIR specification.
CREDIT_ADJUSTMENT_GOODS_SERVICES_DEFECTIVE This indicates that a credit adjustment is initiated as goods or services were defective. This maps to reason code 1062 defined in NPCI's UDIR specification.
CREDIT_ADJUSTMENT_PAID_ALTERNATE_MEANS This indicates that a credit adjustment is initiated as payment was made by alternate means. This maps to reason code 1063 defined in NPCI's UDIR specification.
CREDIT_ADJUSTMENT_GOODS_SERVICES_NOT_PROVIDED This indicates that a credit adjustment is initiated as goods or services were not provided. This maps to reason code 1064 defined in NPCI's UDIR specification.
CREDIT_ADJUSTMENT_MERCHANT_ACCOUNT_NOT_CREDITED This indicates that a credit adjustment is initiated as merchant account was not credited. This maps to reason code 1065 defined in NPCI's UDIR specification.
CREDIT_ADJUSTMENT_DUPLICATE_TRANSACTION This indicates that a credit adjustment is initiated as there was a duplicate transaction. This maps to reason code 1084 defined in NPCI's UDIR specification.
CREDIT_ADJUSTMENT_OTHERS This indicates that a credit adjustment is initiated due to other reasons. This maps to reason code 1090 defined in NPCI's UDIR specification.
CREDIT_ADJUSTMENT_NON_MATCHING_ACCOUNT_NUMBER This indicates that a credit adjustment is initiated as payment was made to a non matching account number. This maps to reason code 1091 defined in NPCI's UDIR specification.
CREDIT_ADJUSTMENT_CARD_HOLDER_CHARGED_MORE_THAN_AMOUNT This indicates that a credit adjustment is initiated as the card holder was charged more than the transaction amount. This maps to reason code 1092 defined in NPCI's UDIR specification.
CREDIT_ADJUSTMENT_CREDIT_NOT_PROCESSED This indicates that a credit adjustment is initiated as the credit was not processed. This maps to reason code 1093 defined in NPCI's UDIR specification.
CREDIT_ADJUSTMENT_BENEFICIARY_UNABLE_TO_UPDATE_CUSTOMER_ACCOUNT This indicates that a credit adjustment is initiated as the beneficiary bank was unable to update the customer account. This maps to reason code 1094 defined in NPCI's UDIR specification.

CaseType

The type of case raised.

Enums
CASE_TYPE_UNSPECIFIED Unspecified case type.
COMPLAINT Complaint.
DISPUTE Dispute.
REFUND Refund.
REVERSAL Reversal.
CHKSTATUS Check Status.

InitiationMode

Specifies how the case was raised.

Enums
INITIATION_MODE_UNSPECIFIED Initiation mode unspecified.
AUTO_CONVERSION This indicates that the complaint was auto-converted to dispute.
CUSTOMER_APP Customer App.
PSP Payments Service Provider.
BANK Bank.
CRM Customer relationship management system.

CustomerReference

The combination of a reference type and reference number that uniquely identifies a bank customer. The customer can either be a physical person or a business.

Fields
reference_type

ReferenceType

Types of identification used to uniquely identify a bank's customer.

reference_value

string

The value identifying the customer. The type of the value will be based on the referenceType field.

When using mobile_phone_number as the reference type, this value will contain a mobile phone number including country code.

When using resident_id as the reference type, this value will contain a given's country unique identification number, such as Aadhaar number in India.

ReferenceType

Types of identification used to uniquely identify a bank's customer. The admissible values will evolve over time.

Enums
REFERENCE_TYPE_UNSPECIFIED Unspecified reference type.
MOBILE_PHONE_NUMBER Mobile phone number as reference.
RESIDENT_ID Unique identifier used to identify residents of a country such as Aadhaar in India or SSN in the USA.

CustomerValidationId

Details around customer's government issued ID that needs to validated.

Fields
id_type

IdType

The type of the ID that needs to be validated.

value

string

The value of the ID that needs to be validated.

IdType

Supported ID types.

Enums
ID_TYPE_UNSPECIFIED Unspecified ID type.
PAN Permanent Account Number, an alphanumeric ID issued by the Income Tax Department.
AADHAAR A 12 digit ID number, issued by Unique Identification Authority of India.
VOTER_ID An alphanumeric ID issued by Election Commission of India.
DRIVING_LICENSE An alphanumeric ID issued by Regional Transport Offices in India.

CustomerValidationRequest

Request for validating customer against a government issued ID.

Fields
id

CustomerValidationId

Details of the ID that needs to be validated.

ref

AccountReference

Unique identification of an account according to India's UPI standards.

CustomerValidationResponse

Response for the customer validation against a government ID.

Fields
valid

bool

TRUE if the ID provided in the request is valid, FALSE otherwise.

account_nature

AccountNature

Nature of the account i.e. SINGLE/JOINT.

account_holder

AccountHolder

Denotes whether the customer is a PRIMARY or SECONDARY account holder.

account_type

string

Denotes whether the account type is SAVINGS, CURRENT etc.

mask_name

string

Mask Name of the customer with the bank.

customer_type

Persona

Denotes whether Customer is a PERSON or ENTITY.

category_code

string

Merchant Category code as specified by UPI (A four-digit number listed in ISO 18245 for retail financial services).

AccountHolder

Types of account holder.

Enums
ACCOUNT_HOLDER_UNDEFINED Unspecified account holder.
PRIMARY Customer is primary account holder.
SECONDARY Customer is secondary account holder.

AccountNature

Types of account nature.

Enums
ACCOUNT_NATURE_UNDEFINED Unspecified account nature.
SINGLE Acount nature is of type SINGLE.
JOINT Account nature is of type JOINT.

DebitCardInfo

Information about a customer's debit card that will be validated by the bank before sending an OTP to the customer's mobile phone or for validating an OTP received by the customer.

Fields
card_number

string

The last 6 digits of the customer's debit card.

expiry

string

The expiry date of the debit card in MMYY format.

ErrorReason

Provides additional reason about a particular error response returned by the Bank Adapter. Not all reasons can be returned by all APIs. The list of reasons that can be returned by a particular API are documented along with the API.

For any API, if the bank adapter returns an error reason that is not acceptable for that particular API, then the Google Cloud Issuer Gateway will default to INVALID_TRANSACTION.

Enums
ERROR_REASON_UNSPECIFIED Unspecified error reason.
ACCT_BLOCKED The account under consideration for the operation is blocked (as defined by the bank's policies).
ACCT_DORMANT The account under consideration for the operation is dormant (as defined by the bank's policies).
ACCT_FROZEN The account under consideration for the operation is frozen (as defined by the bank's policies).
ACCT_INACTIVE The account under consideration for the operation is inactive (as defined by the bank's policies).
ACCT_MULTIPLE_CUSTOMERS The account is associated with multiple customers.
ACCT_NOT_FOUND The account details specified are invalid and not found in the bank's systems.
EXPIRED_DEBIT_CARD The debit card has expired.
CARD_MANAGEMENT_SYSTEM_FAILURE The bank card management system is down.
INACTIVE_DEBIT_CARD The debit card is inactive.
INCORRECT_ATM_PIN The ATM PIN provided is incorrect.
INCORRECT_OTP The OTP provided is invalid.
INSUFFICIENT_FUNDS The funds in the bank account are insufficient to perform the requested operation.
INVALID_DEBIT_CARD The debit card is invalid.
INVALID_PARAMETERS The parameters provided are invalid.
INVALID_PATH The path invoked is not supported by the Bank Adapter service.
INVALID_TRANSACTION The requested transaction is invalid and will not be performed.
MAX_BALANCE_EXCEEDED The maximum allowed balance for the account has been exceeded.
MOBILE_NUMBER_MULTIPLE_CUSTOMERS More than one customer is associated with the same mobile number.
OTP_EXPIRED The OTP provided has expired.
RESTRICTED_DEBIT_CARD The debit card is restricted.
SERVICE_ERROR The requested operation could not be performed because of an error/bug in the Bank Adapter service.
SERVICE_UNAVAILAIBLE The requested operation could not be performed because the Bank Adapter service or one or more of the bank's services are unavailable.
TRANSACTION_NOT_PERMITTED The requested transaction is not permitted.
UNABLE_TO_UPDATE_BANK_SERVICES The requested settle/resolve payment could not be performed because the Bank Adapter service was unable to update the bank's services. This error code maps to the UT1 error code as defined in NPCI's UDIR specification.
PARTY_INSTRUCTIONS The requested settle/resolve payment could not be performed because of party instructions. This error code maps to the UT3 error code as defined in NPCI's UDIR specification.
DUPLICATE_PROCESSING The requested settle/resolve payment could not be performed because of duplicate processing. This error code maps to the UT5 error code as defined in NPCI's UDIR specification.
PAYMENT_UDIR_RET_ACCOUNT_CLOSED The requested settle/resolve payment (credit) operation could not be performed because the payee account is closed, and a reversal needs to be initiated. This error code maps to code 114 defined in NPCI's UDIR specification.
PAYMENT_UDIR_RET_ACCOUNT_DOES_NOT_EXIST The requested settle/resolve payment (credit) operation could not be performed because the payee account does not exist, and a reversal needs to be initiated. This error code maps to code 115 defined in NPCI's UDIR specification.
PAYMENT_UDIR_RET_PARTY_INSTRUCTIONS The requested settle/resolve payment (credit) operation could not be performed because of party instructions, and a reversal needs to be initiated. This error code maps to code 116 defined in NPCI's UDIR specification.
PAYMENT_UDIR_RET_NRI_ACCOUNT The requested settle/resolve payment (credit) operation could not be performed because the payee account is a NRI account, and a reversal needs to be initiated. This error code maps to code 117 defined in NPCI's UDIR specification.
PAYMENT_UDIR_RET_CREDIT_FREEZED The requested settle/resolve payment (credit) operation could not be performed because the payee account has credit freezed, and a reversal needs to be initiated. This error code maps to code 118 defined in NPCI's UDIR specification.
PAYMENT_UDIR_RET_INVALID_BENEFICIARY_DETAILS The requested settle/resolve payment (credit) operation could not be performed because of invalid payee details, and a reversal needs to be initiated. This error code maps to code 119 defined in NPCI's UDIR specification.
PAYMENT_UDIR_RET_OTHERS The requested settle/resolve payment (credit) operation could not be performed because of other errors, and a reversal needs to be initiated. This error code maps to code 120 defined in NPCI's UDIR specification.
SERVICE_TIMEOUT The requested operation could not be performed because the Bank Adapter service or one or more of the bank's services timed out.
HOLD_FUNDS_NOT_ALLOWED Hold funds not allowed for certain types of accounts (like CC, PF, PPF accounts) as per bank's policy.
DEBIT_NOT_ALLOWED Debit is not allowed on this type of account.
NO_FUNDS_ON_HOLD The blocked funds have already been released.
FRAUDULENT_TRANSACTION The requested transaction is suspected to be fraudulent due to high risk score.
REGISTERED_MOBILE_NUMBER_CHANGED The registered mobile number linked to the account has been changed or removed.
STOPPED_BY_COURT_ORDER The requested settle payment operation could not be performed as it was stopped by a court order.

HoldAmount

Specifies the amount to be held and the holding rule.

Fields
instructed_amount

Amount

The amount to be held in the account.

holding_rule

HoldingRule

The holding rule.

HoldingRule

The holding rule for the hold funds request.

Enums
HOLDING_RULE_UNSPECIFIED Unspecified holding rule.
EXACT Rule specifying that the exact amount is to be held.
MAX Rule specifying the maximum amount to be held.

HoldDetails

Specifies the amount held and the holding reference.

Fields
reference

string

The bank's reference for the funds held in the account.

amount

HoldAmount

The amount held in the account.

HoldFundsRequest

Request to hold funds in an account.

Fields
request_id

string

An identifier for this request. This is used to correlate a hold funds request to a release funds request. In UPI, this field maps to the Unified Mandate Number (UMN).

payer

SettlementParticipant

Payer in the transaction.

payee

SettlementParticipant

Payee in the transaction.

hold_amount

HoldAmount

Specifies the amount to be held and the holding type rule.

transaction_id

string

Identifier for the mandate creation transaction.

validity_period

ValidityPeriod

Specifies the validity period for the funds to be held.

description

string

Free form string describing the hold request.

payment_additional_info

PaymentAdditionalInfo

Additional payment information specific to India's UPI requirements.

original_hold_details

HoldDetails

If the hold funds call is triggered to update an existing hold on funds, then this field will contain the original hold funds reference and the amount held originally. In other cases, this field will be omitted in the request.

hold_reason

HoldReason

Reason for this hold request.

HoldReason

Indicates whether the hold funds request is for a mandate or a voucher.

Enums
REASON_UNSPECIFIED Unspecified hold reason.
MANDATE Hold funds for mandate.
VOUCHER Hold funds for voucher.

HoldFundsResponse

Response for the HoldFunds method.

Fields
hold_reference

string

The bank's reference for the funds held in an account.

InitiateRegistrationRequest

Request for initiating registration of a customer's bank account for UPI.

Fields
debit_card_info

DebitCardInfo

Information about a customer's debit card that will be provided if the issuer bank supports the ATM_REDIRECT mode of registration.

participant

Participant

Participant initiating the registration.

Union field reference. Identifies the customer or bank account registering for UPI. An OTP is sent to the mobile number associated with the customer/bank account. Either a customer reference or a bank account reference will be provided. Only one of the two will be specified. reference can be only one of the following:
customer_reference

CustomerReference

The combination of a reference type and reference number that uniquely identifies a bank customer. This field will be used if the customer is identified based on a unique resident identifier (like Aadhaar) or based on the customer's mobile number.

account_reference

AccountReference

A reference to uniquely identify a customer's bank account based on India's UPI standards.

InitiateRegistrationResponse

The response once a registration request has been processed and an OTP has been generated and sent to a customer's mobile phone.

Fields

MerchantAdditionalInfo

Additional merchant information specific to India's UPI requirements.

Fields
category_code

string

Merchant Category code as specified by UPI (A four-digit number listed in ISO 18245 for retail financial services).

store_id

string

A unique identifier for the merchant store where the payment occurs.

terminal_id

string

A unique identifier for the POS terminal in the store where the payment occurs.

type

Type

Indicates the type of merchant.

genre

Genre

Indicates the genre of the merchant.

onboarding_type

OnboardingType

Indicates by whom the merchant has been onboarded.

ownership_type

OwnershipType

Indicates the type of ownership for the merchant.

additional_info[]

AdditionalInfo

Additional information about the merchant.

Genre

Indicates whether it is an online or offline merchant.

Enums
GENRE_UNSPECIFIED Unspecified merchant genre.
ONLINE Online merchant.
OFFLINE Offline merchant

OnboardingType

Indicates whether the merchant has been onboarded by a bank or an aggregator.

Enums
ONBOARDING_TYPE_UNSPECIFIED Unspecified merchant onboarding type.
BANK Onboarded by bank.
AGGREGATOR Onboarded by aggreagator.

OwnershipType

Indicates the type of ownership for the merchant.

Enums
OWNERSHIP_TYPE_UNSPECIFIED Unspecified merchant ownership type.
PROPRIETARY Properiety ownership.
PARTNERSHIP Partnership ownership.
PUBLIC Public ownership.
PRIVATE Private ownership.
OTHERS Other ownership model.

Type

Indicates whether it is a small or large merchant.

Enums
TYPE_UNSPECIFIED Unspecified merchant type.
SMALL Small merchant.
LARGE Large merchant.

MerchantInfo

Information about a merchant entity participating in a payment settlement.

Fields
id

string

A unique identifier for the merchant.

name

MerchantName

The name of the merchant who is a party in the payment. Includes multiple possible names for the merchant.

additional_info

MerchantAdditionalInfo

India specific merchant additional information.

MerchantName

The name of a merchant who is a party in a payment settlement. Includes multiple possible names for the merchant.

Fields
brand

string

The name the merchant is commonly known as.

legal

string

The merchant's Legal Name.

franchise

string

The franchise name under which the merchant operates.

NotifyCustomerRequest

Request body for customer notification.

Fields
participant

Participant

Participant to be notified.

account

AccountReference

Unique identification of an account according to India's UPI standards. This is the details of the account of the customer who is to be notified.

Union field details. The details of the notification. Only one of two values will be specified. The type of notification to be sent can be inferred from which of the two possible values are set in the request. details can be only one of the following:
mpin_updated

MPINUpdated

Details of the MPIN operation processed by the issuer switch.

recurring_mandate

RecurringMandate

Details of the recurring mandate operation processed by the issuer switch.

MPINUpdated

Details of the MPIN update operation.

Fields
state

State

State of the MPIN update operation.

State

Possible states of the MPIN update operation.

Enums
STATE_UNSPECIFIED Unspecified state.
SUCCEEDED MPIN update succeeded.
FAILED MPIN update failed.

RecurringMandate

Details of the notification needed for recurring mandate (auto-pay) operations.

Fields
id

string

Identifier of the mandate. This maps to the Unique Mandate Number (UMN) in India's UPI standards.

payee

SettlementParticipant

Information about the payee who will be executing the mandate debit request. This will include the payee's VPA, name and all merchant details of the payee. Note that the account reference of the payee will not be populated in the request.

pattern

Pattern

The mandate's recurrence pattern.

amount

Amount

The amount that will be settled as part of the mandate execution.

state

State

State of the recurring mandate operation.

operation_type

OperationType

Type of operation performed on the recurring mandate.

Union field Operation. Additional information about the operation processed on a recurring mandate will be provided in this field. Operation can be only one of the following:
creation

Creation

Contains details about the recurring mandate creation operation.

execution

Execution

Contains details about the recurring mandate execution operation.

modification

Modification

Contains details about the recurring mandate modification operation.

pause

Pause

Contains details about the recurring mandate pause operation.

Creation

Details of a newly created recurring mandate.

Fields
start_date

Date

Start date of the recurring mandate.

end_date

Date

End date of the recurring mandate.

Execution

Details of a recurring mandate that is to be executed in the next 24 hours with a SettlePayment-DEBIT.

Fields
execution_date

Date

Date when the mandate will be executed next.

Modification

Details of a recurring mandate that has been modified.

Fields
start_date

Date

Modified start date of the recurring mandate.

end_date

Date

Modified end date of the recurring mandate.

OperationType

Enums
OPERATION_TYPE_UNSPECIFIED Unspecified operation type.
OPERATION_TYPE_CREATION Operation type creation. This type indicates that a new recurring mandate creation operation has been processed by the issuer switch. The operation field will contain details about the newly created mandate.
OPERATION_TYPE_EXECUTION Operation type execution. This type indicates that there will be an upcoming execution of a recurring mandate. The operation field will contain details about the upcoming execution of the recurring mandate.
OPERATION_TYPE_MODIFICATION Operation type modification. This type indicates that the issuer switch has processed a modification to a recurring mandate. The operation field will contain details about the modified recurring mandate.
OPERATION_TYPE_REVOCATION Operation type revocation. This type indicates that the issuer switch has processed a revocation of a recurring mandate. No additional information is included for this operation type.
OPERATION_TYPE_PAUSE Operation type pause. This type indicates that the issuer switch has processed a pause on a recurring mandate. The operation field will contain details about pause operation.
OPERATION_TYPE_UNPAUSE Operation type unpause. This type indicates that the issuer switch has processed an unpause on a recurring mandate. No additional information is included for this operation type.

Pattern

Recurrence pattern of the mandate.

Enums
PATTERN_UNSPECIFIED Unspecified recurrence pattern.
PATTERN_DAILY Mandate recurring daily.
PATTERN_WEEKLY Mandate recurring weekly.
PATTERN_FORTNIGHTLY Mandate recurring fortnightly.
PATTERN_MONTHLY Mandate recurring monthly.
PATTERN_BIMONTHLY Mandate recurring bi-monthly (once every 2 months).
PATTERN_QUARTERLY Mandate recurring quarterly.
PATTERN_HALFYEARLY Mandate recurring half yearly.
PATTERN_YEARLY Mandate recurring yearly.

Pause

Detailf of a recurring mandate that has been paused.

Fields
start_date

Date

Date when the recurring mandate's pause starts.

end_date

Date

Date when the recurring mandate's pause ends.

State

Possible states of the recurrming mandate operation.

Enums
STATE_UNSPECIFIED Unspecified state.
SUCCEEDED Recurring mandate operation succeeded.
FAILED Recurring mandate operation failed.

OriginalTransaction

Details of original transaction. This type is passed to the Bank Adapter service if the settlement type is REVERSAL.

Fields
payment_id

string

Uniquely identifies the original transaction. This maps to the Txn.Id value of the original transaction in India's UPI system.

retrieval_reference_number

string

Retrieval Reference Number (RRN) of the original transaction.

instructed_amount

Amount

Instructed amount for settlement in the original transaction.

settlement_type

SettlementType

Type of settlement of the original transaction.

request_time

Timestamp

Timestamp of the original transaction request.

Participant

Information about a person or entity participating in a transaction.

Fields
virtual_payment_address

string

The virtual payment address (VPA) of the settlement participant.

persona

Persona

The type of the participant. Could either a person or an entity.

name

string

The name of the participant.

customer_reference

CustomerReference

The combination of a reference type and reference number that uniquely identifies a bank customer. The Issuer Switch populates this field with the customer's unique resident identifier (like India's Aadhaar) or mobile number.

PaymentAdditionalInfo

Additional payment information specific to India's UPI requirements.

Fields
consumer_reference_number

string

Consumer reference number to identify (like Loan number, etc).

date_time

Timestamp

Settlement origination date/time as specified by the message originator. Formatted as specified in RFC 3339.

sub_type

SubType

Indicates if the payment initiated by the payer (pay) or the payee (collect).

initiation_mode

InitiationMode

Specifies how the payment was inititated.

purpose

Purpose

The purpose field is specially used for SEBI txn.

reference_category

ReferenceCategory

If referenceLink is present, then this field is mandatory. The field is used to identify the category of the transaction.

risk_info[]

RiskInfo

Risk information specific to India's UPI Standards.

miscellaneous[]

AdditionalInfo

Each additional info can be used to present more detailed information about the entity is attached to.

InitiationMode

Specifies how the payment was inititated.

Enums
INITIATION_MODE_UNSPECIFIED Unspecified payment initation mode.
DEFAULT_INITIATION_MODE Default.
QR_CODE QR Code.
SECURE_QR_CODE Secure QR Code.
BHARAT_QR_CODE Bharat QR Code.
INTENT Intent.
SECURE_INTENT Secure Intent.
NFC NFC(Near Field Communication).
BLUETOOTH BLE (Bluetooth).
ULTRA_HIGH_FREQUENCY UHF(Ultra High Frequency).
AADHAR Aadhaar.
SDK SDK (Software Development Kit).
UPI_MANDATE UPI-Mandate.
FOREIGN_INWARD_REMITTANCE FIR (Foreign Inward Remittance).
QR_MANDATE QR Mandate.
BBPS BBPS.
FUTURE_PURPOSE Future purpose.

Purpose

The purpose field is specially used for SEBI transactions.

Enums
PURPOSE_UNSPECIFIED Unspecified purpose.
DEFAULT_PURPOSE Default.
SEBI SEBI.
AMC AMC.
TRAVEL Travel.
HOSPITALITY Hospitality.
HOSPITAL Hospital.
TELECOM Telecom.
INSURANCE Insurance.
EDUCATION Education.
GIFTING Gifting.
OTHER_PURPOSES Others.
PURPOSE_TYPE_11 Purpose type 11.
PURPOSE_TYPE_12 Purpose type 12.
PURPOSE_TYPE_13 Purpose type 13.
PREAPPROVED_DISBURSEMENT Preapproved disbursement.

ReferenceCategory

The category of the transaction.

Enums
REFERENCE_CATEGORY_UNSPECIFIED Unspecified reference category.
NULL Null.
ADVERTISEMENT Advertisement.
INVOICE Invoice.
OTHER_REFERENCE_CATEGORIES Others, for future use.

SubType

Indicates who initiated the payment.

Enums
SUB_TYPE_UNSPECIFIED Unspecified sub-type.
PAY Pay subtype - initiated by payer.
COLLECT Collect subtype - initiated by payee.

PaymentAdjustmentError

Error found during execution of an individual payment resolution.

Fields
error_reason

ErrorReason

Error reason.

PaymentAdjustmentResponse

Information about the adjustment done by the bank adapter to resolve an unresolved transaction.

Fields
type

AdjustmentType

Type of adjustment done to resolve an unresolved transaction.

metadata

AdjustmentMetadata

Metadata of the adjustment done.

settlement_response

SettlePaymentResponse

Settlement related information if a settlement was done to resolve an unresolved transaction.

AdjustmentMetadata

Specifies additional metadata associated with an adjustment done by bank to resolve an unresolved transaction.

Fields
adjustment_id

string

This uniquely identifies the adjustment done by bank adapter service to resolve a transaction.

adjustment_remarks

string

Free form text to describe any adjustment remarks.

AdjustmentType

Type of adjustment action done by bank adapter service to resolve an unresolved transaction.

Enums
ADJUSTMENT_TYPE_UNSPECIFIED Adjustment type unspecified.
TRANSACTION_ALREADY_RESOLVED This indicates that the payment settlement transaction was already successfully resolved at the bank adapter service's end i.e. debit reversal/credit needed to resolve transaction was already done.
TRANSACTION_RESOLVED_NOW This indicates that payment settlement transaction was resolved now during execution of resolve payment request sent to bank adapter service. In this case, the response should contain the settlement response indicating the details of the debit reversal/credit done to resolve the transaction.
ORIGINAL_TRANSACTION_NOT_FOUND This type indicates that the original failed debit/credit transaction cannot be found by the bank adapter service.
ORIGINAL_TRANSACTION_DID_NOT_OCCUR This type indicates that original transaction was not executed on the bank's services. This code should be used only for resolution type RESOLVE_DEBIT_REVERSAL where the original debit settlement didn't occur.

Persona

The type of the customer.

Enums
PERSONA_UNSPECIFIED Unspecified persona.
PERSON Customer is a person.
ENTITY Customer is an entity.

ReleaseFundsRequest

Request to release previously held funds in an account.

Fields
request_id

string

An identifier for this request which must be the same as the identifier for a previous hold funds request. This is used to correlate a hold funds request to a release funds request. In UPI, this field maps to the Unified Mandate Number (UMN).

payer

SettlementParticipant

Payer in the transaction.

payee

SettlementParticipant

Payee in the transaction.

original_transaction_id

string

Identifier of the original hold funds transaction.

hold_details

HoldDetails

The bank's reference for the funds held in the account which are being released. It specifies the amount held and the hold reference returned when the funds were initially held in the account.

additional_info

PaymentAdditionalInfo

Additional information for executing the request.

ResolvePaymentRequest

Individual payment resolution request.

Fields
resolution_type

ResolutionType

Type of resolution to execute.

original_settle_payment_info

SettlePaymentRequest

Details of the original payment debit / credit settlement which needs to be resolved.

resolution_workflow

ResolutionWorkflow

Type of resolution workflow which triggered this request.

case_details

CaseDetails

If this request's resolution workflow is COMPLAINT, then details of the complaint raised by the user/bank will be provided in this field.

ResolutionType

Type of resolution required to be done by bank in order resolve to an unresolved payment settlement.

Enums
RESOLUTION_TYPE_UNSPECIFIED Unspecified resolution type.
RESOLVE_DEBIT_REVERSAL Resolve an unresolved debit reversal transaction. The bank adapter service needs to check whether debit reversal was done for the debit specified in original settle payment info. If it was unsuccessful, then bank adapter or banks systems should resolve it by performing the debit reversal.
RESOLVE_CREDIT Resolve an unresolved credit transaction. The bank adapter service needs to check whether the credit specified in original settle payment info was successful. If it was unsuccessful, then bank adapter or bank's systems should resolve the settlement by performing the credit.

ResolutionWorkflow

Type of payment resolution workflow. This indicates the UPI workflow which triggered this request.

Enums
RESOLUTION_WORKFLOW_UNSPECIFIED Unspecified resolution workflow.
AUTOUPDATE_WORKFLOW UPI's auto-update workflow.
COMPLAINT_WORKFLOW UPI's complaint workflow.

ResolvePaymentResponse

The response to be returned by the bank adapter once the resolve payment request is executed.

Fields
resolve_payment_response

ResolvePaymentResult

Resolve Payment result. Can indicate either a success or an error during resolution of an unresolved payment settlement.

resolution_status

ResolutionStatus

The status of the resolution.

ResolutionStatus

Describes the status of payment resolution.

Enums
STATE_UNSPECIFIED Unspecified resolution state.
SUCCEEDED Successful resolution.
FAILED Failed resolution.

ResolvePaymentResult

Result of resolution of an unresolved payment settlement. Can be one of either a success or an error response.

Fields
Union field resolve_payment_result. Resolve payment result can be either success or error. resolve_payment_result can be only one of the following:
success

PaymentAdjustmentResponse

Describes the payment adjustment done by the banks to successfully resolve an unresolved payment settlement.

error

PaymentAdjustmentError

Describes the error due to which an unresolved payment settlement couldn't be resolved.

RetrieveBalanceRequest

Request to retrieve an account balance.

Fields
participant

Participant

Participant requesting the balance retrieval.

Union field reference. Identifies the customer or bank account whose account balance is to be retrieved. Either a customer reference or a bank account reference will be provided. Only one of the two will be specified. reference can be only one of the following:
customer_reference

CustomerReference

The combination of a reference type and reference number that uniquely identifies a bank customer. This field will be used if the customer is identified based on a unique resident identifier (like Aadhaar) or based on the customer's mobile number.

account_reference

AccountReference

A reference to uniquely identify a customer's bank account based on India's UPI standards.

RetrieveBalanceResponse

Response for the RetrieveBalance method.

Fields
balance_info

BalanceInfo

Details of account balance.

account_reference

AccountReference

The account whose balance was retrieved.

RiskInfo

Risk information specific to India's UPI Standards.

Fields
risk_score_provider

string

Entity providing the risk score.

risk_score_value

string

Numeric value of risk evaluation ranging from 0 (No Risk) to 100 (Maximum Risk).

risk_type

string

Type of risk.

SearchAccountsRequest

Request to search for accounts, given a customer reference or an account reference.

Fields

Union field reference.

reference can be only one of the following:

customer_reference

CustomerReference

Reference of customer used to search for accounts.

account_reference

AccountReference

A reference to uniquely identify a customer's bank account based on India's UPI standards.

SearchAccountsResponse

Response for the SearchAccount method.

Fields
accounts[]

AccountInfo

List of accounts matching the search criteria.

SearchPaymentsRequest

Request to search for a payment settlement.

Fields
payment_id

string

Uniquely identifies the payment settlement transaction being searched for. This maps to the Txn.Id value in India's UPI system.

settlement_type

SettlementType

Type of settlement.

retrieval_reference_number

string

Retrieval Reference Number (RRN) of the payment settlement being searched for.

request_time

Timestamp

Timestamp of the payment settlement transaction request being searched for.

SearchPaymentsResponse

Information about a payment previously requested.

Fields
settlement_payment_response

SettlePaymentResult

Payment settlement result. Can indicate either a success or an error during the processing of the original payment settlement.

settlement_state

SettlementState

The status of the overall settlement.

SettlementState

The status of the overall settlement. It may have changed after it was executed (for example, if a refund was processed).

Enums
STATE_UNSPECIFIED Unspecified settlement state.
SUCCEEDED Successful settlement.
FAILED Failed settlement.
PARTIAL Partially completed settlement.
DEEMED Deemed settlement.
REVOKED Revoked settlement.

SettlePaymentError

Error found during execution of an individual settlement. This is returned when returning the status of individual payment settlements from the bank's backend systems.

Fields
error_reason

ErrorReason

Error reason for the original payment settlement.

SettlePaymentRequest

Individual payment settlement request.

Fields
settlement_type

SettlementType

Type of settlement to execute.

payer

SettlementParticipant

Payer in the payment settlement transaction.

payee

SettlementParticipant

Payee in the settlement payment transaction.

instructed_amount

Amount

Amount needed to complete payment settlement.

payment_id

string

Uniquely identifies the payment this settlement is part of. This maps to the transaction id in India's UPI system.

retrieval_reference_number

string

Retrieval Reference Number (RRN) for the transaction.

description

string

Free form string providing a description of the payment settlement.

hold_details

HoldDetails

Specifies the amount held and the holding reference i.e. the bank's reference for the funds held in the account which are being debited in this request. A value will be specified for this field only for DEBIT settlements which are initiated against funds held in the account.

request_time

Timestamp

Timestamp of the current request.

additional_info

PaymentAdditionalInfo

Additional information about the payment settlement.

original_transaction

OriginalTransaction

If this request's settlement type is REVERSAL, then details of the original transaction that is being reversed will be provided in this field.

case_details

CaseDetails

If this request is being triggered as part of a complaint raised via UPI's UDIR system, then details of the complaint will be available in this field.

SettlePaymentResponse

The response to be returned by the bank adapter once the settlement request is executed.

Fields
backend_settlement_id

string

An identifier used by the bank's systems for the settlement operation. In India's UPI system, this translates to the approval number.

settlement_time

Timestamp

Timestamp indicating when the settlement was executed. Formatted as specified in RFC 3339.

settled_amount

Amount

The amount settled by the backend systems.

miscellaneous[]

AdditionalInfo

Generic additional information.

SettlePaymentResult

Result of a settlement payment. Can be one of either a success or an error response.

Fields
Union field settle_payment_result. Settlement payment can be either success or error. settle_payment_result can be only one of the following:
success

SettlePaymentResponse

Successful settlement response.

error

SettlePaymentError

Settlement Error Response.

SettlementParticipant

Contains all information about a participant in a payment settlement (either the payer or the payee).

Fields
participant

Participant

The participant information.

account

AccountReference

Unique identification of an account according to India's UPI standards.

merchant_info

MerchantInfo

Information about a merchant who is a participant in the payment. This field will be specified only if the participant is a merchant.

SettlementType

Type of settlement to execute.

Enums
SETTLEMENT_TYPE_UNSPECIFIED Unspecified settlement type.
DEBIT Debit settlement.
CREDIT Credit settlement.
REVERSAL Reversal of a previous settlement.

ValidateRegistrationRequest

Request for a previously initiated registration to be validated.

Fields
debit_card_info

DebitCardInfo

Information about a customer's debit card that needs to be validated by the bank.

atm_pin

string

The ATM pin for the debit card that needs to be validated by the bank.

otp

string

The OTP received on the customer's mobile phone that needs to be validated by the bank.

participant

Participant

Participant validating the registration.

Union field reference. Identifies the customer or bank account whose registration for UPI is to be validated. Either a customer reference or a bank account reference will be provided. Only one of the two will be specified. reference can be only one of the following:
customer_reference

CustomerReference

The combination of a reference type and reference number that uniquely identifies a bank customer. This field will be used if the customer is identified based on a unique resident identifier (like Aadhaar) or based on the customer's mobile number.

account_reference

AccountReference

A reference to uniquely identify a customer's bank account based on India's UPI standards.

ValidityPeriod

The fund holding period duration.

Fields
start_date_time

Timestamp

The date and time at which the fund holding period begins.

end_date_time

Timestamp

The date and time at which the fund holding period ends.