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

Bank adapter overview

This page provides an overview of the bank adapter, the security mechanisms used by the bank adapter APIs, and considerations when implementing the bank adapter APIs.

This page assumes that you are familiar with the UPI (Unified Payments Interface) payment system developed by the NPCI (National Payments Corporation of India).

What is a bank adapter?

You can think of the bank adapter as an extension of your bank's backend systems. You can run the bank adapter as a service running on Google Cloud infrastructure or as a service running inside or outside your bank's network. The bank adapter abstracts your bank's backend services and provides uniform APIs for the issuer switch to invoke your bank's services.

The bank adapter is a crucial part of the overall ecosystem within which the issuer switch operates. Hence, when you implement the bank adapter, we recommend that you ensure that the service is highly performant, scalable, available, and secure. To ensure that UPI transactions are processed within the prescribed threshold, we recommend that the bank adapter add not more than 300 milliseconds of processing time to a transaction's entire processing duration.

Why the bank adapter?

The bank adapter provides the following advantages:

  • Hides your core banking services and APIs from the external world.
  • Provides a standard interface for the issuer switch to communicate with your backend services and APIs.

Bank adapter API specification

For the issuer switch to interact with your bank adapter, you must implement your bank adapter as per the API specification described in this document. Google provides you only the API specification for the bank adapter and not the implementation details. You can implement the bank adapter APIs either as REST APIs or as gRPC. For more information, see:

The API specification has the following categories of APIs:

  • Payments settlement APIs - Specifies APIs for payment and settlement related (financial) transactions. For more information, see payments.

  • Accounts service APIs - Specifies APIs for account related (non-financial) transactions. For more information, see accounts.

  • Customer service APIs - Specifies APIs for customer service related transactions. For more information, see users.

Note: You must implement all the APIs in the specification.

Security

This section describes the issuer switch security mechanisms when calling your bank adapter APIs.

Security in REST APIs

If you implement the bank adapter REST APIs, the issuer switch ensures security during communication, authentication, authorization, and message exchange.

Communication

All communications between the issuer switch and the bank adapter are secured with the TLS (Transport Layer Security) protocols.

Authentication

The issuer switch uses mTLS (Mutual Authenticated TLS) to identify and authenticate itself with the bank's server. You must ensure that your bank adapter accepts only incoming TLS connections that present a valid and unexpired certificate identifying the issuer switch.

Authorization

There are no specific security mechanisms for authorization, as it is expected that the issuer switch can invoke any of the APIs documented in this specification and implemented by the bank adapter.

Error handling

This section describes how the bank adapter APIs are expected to return errors to the issuer switch.

Error handling in REST implementation

If you implement the bank adapter as REST APIs, the service should return all errors using the HTTP mapping mechanism as described in ErrorReason[REST, gRPC]. The following example shows the JSON payload that the bank adapter should return when an API call fails.

{
  "code": 9,
  "message": "Insufficient balance in account to process debit.",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "INSUFFICIENT_FUNDS",
      "domain": "issuerswitch.googleapis.com",
      "metadata": {
        "service": "issuer-bank-adapter.your-domain.com"
      }
    ]
  }
}

Error payload considerations

Consider the following points when returning a JSON error payload in your bank adapter API's response:

  1. The code field must have the values defined in the google.grpc.Code enum.
  2. Even though the details field is an array, it should contain only one item within it.
  3. The item in the details field should have the @type field, whose value should be type.googleapis.com/google.rpc.ErrorInfo.
  4. The reason field in the details array item should be one of the values defined in the ErrorReason enum described by the bank adapter API specification.

Error handling in gRPC implementation

If the bank adapter is developed as a service implementing the gRPC version of this API specification, then all APIs should follow the standard mechanism supported in gRPC for status and error handling.

Request identification

All requests (via REST or gRPC) from the issuer switch to the bank adapter include a unique identifier (request-id) for identifying a request. By logging this identifier in your bank adapter logs, you can track and troubleshoot your transactions end-to-end.

  • In a REST request, the identifier is present in the X-Request-Id HTTP request header.
  • In a gRPC request, the identifier is present in the request-id key of the request metadata.