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

Search for transactions

This page describes how you can use the issuer switch API to search for transactions based on specified search criteria.

To identify the required transactions, you can use the relevant API method to search for the following types of transactions:

  • Financial transactions: Transactions with the API type SETTLE_PAYMENT.
  • Metadata transactions: Transactions with any of the following API types.

    • BALANCE
    • CHECK_STATUS
    • HEART_BEAT
    • INITIATE_REGISTRATION
    • LIST_ACCOUNTS
    • UPDATE_CREDENTIALS
    • VALIDATE_REGISTRATION
  • Mandate transactions: Transactions with the API type MANDATE.

  • Complaint transactions: Transactions with the API type COMPLAINT. Complaint transactions include transactions that create or modify either complaint or dispute objects.

Search for financial transactions

To search for financial transactions using the issuer switch API, use the ListFinancialTransactions method [REST, gRPC].

Specify filter criteria using the filter parameter. This parameter allows you to filter transactions based on various fields such as the Retrieval Reference Number (RRN), transaction type, transaction ID, payer or payee VPA, payer or payee mobile number, and so on. You can specify multiple criteria, so that only results that match all the specified criteria are returned. The RRN is unique for every payment, so if you specify the RRN, all transactions related to that payment are returned. For example, if a debit transaction was made and then reversed, specifying the RRN for that transaction returns both the debit transaction and the reversal. The transaction ID is unique for each transaction. See the ListFinancialTransactions API documentation for the complete list of supported filter criteria.

The following curl command lists debit transactions related to the specified RRN.

curl -X GET -H "Authorization: Bearer $TOKEN" "https://ISSUER_SWITCH_API_ENDPOINT/v1/projects/PROJECT_ID/financialTransactions?filter=RRN%3D100000000000%20AND%20transactionType%3DTRANSACTION_TYPE_DEBIT"

In this example:

  • PROJECT_ID is the ID of your Google Cloud project.
  • $TOKEN is your OAuth 2.0 access token.
  • ISSUER_SWITCH_API_ENDPOINT is your issuer switch's API endpoint. For example, api.129a0b1a-bb73-4906-a5b7-a6e0bfe7860e.issuerswitch.goog.

Replace these with values specific to your environment.

When you run this command, you see a response similar to the following:

{
  "financialTransactions": [
    {
      "name": "projects/PROJECT_ID/financialTransactions/GOO963805f556e48b1b2def079d5e52903",
      "info": {
        "id": "GOO963805f556e48b1b2def079d5e52903",
        "apiType": "SETTLE_PAYMENT",
        "transactionType": "TRANSACTION_TYPE_DEBIT",
        "transactionSubType": "PAY",
        "state": "SUCCEEDED",
        "createTime": "2022-05-20T10:54:54.817828Z",
        "bankAdapterRequestId": "1296eeb7-4385-4690-9f73-de0f22f2e3a8"
      },
      "retrievalReferenceNumber": "100000000000",
      "payer": {
        "participant": {
          "virtualPaymentAddress": "foo@okgoog",
          "persona": "PERSON"
        },
        "account": {
          "ifscCode": "GOOG0002022",
          "accountType": "SAVINGS",
          "accountNumber": "50100100675001"
        },
        "merchantInfo": {
          "merchant": {},
          "additionalInfo": {}
        },
        "mobile": "911234567890",
        "deviceId": "2a1314cb7138adc3"
      },
      "payee": {
        "participant": {
          "virtualPaymentAddress": "bar@okgoog",
          "persona": "PERSON"
        },
        "account": {
          "ifscCode": "GOOG0002022",
          "accountType": "SAVINGS",
          "accountNumber": "50100100675002"
        },
        "merchantInfo": {
          "merchant": {},
          "additionalInfo": {}
        },
        "mobile": "919876543210",
        "deviceId": "2a1314cb712xadc3"
      },
      "amount": {
        "currencyCode": "INR",
        "units": "100"
      }
    }
  ]
}

Search for metadata transactions

To search for metadata transactions using the issuer switch API, use the ListMetadataTransactions method [REST, gRPC].

Specify filter criteria using the filter parameter. This parameter allows you to filter transactions based on various fields such as the transaction type, the UPI transaction ID, the transcation state, the VPA of the transaction originator, and so on. You can specify multiple criteria, so that only results that match all the specified criteria are returned. See the ListMetadataTransactions API documentation for the complete list of supported filter criteria.

The following curl command lists accounts associated with the originator VPA that have the specified state:

curl -X GET -H "Authorization: Bearer $TOKEN" "https://ISSUER_SWITCH_API_ENDPOINT/v1/projects/PROJECT_ID/metadataTransactions?filter=apiType%3DLIST_ACCOUNTS%20AND%20transactionType%3DTRANSACTION_TYPE_LIST_ACCOUNTS%20AND%20originVPA%3Dfoo%40okgoog%20AND%20state%3DSUCCEEDED"

In this example:

  • PROJECT_ID is the ID of your Google Cloud project.
  • $TOKEN is your OAuth 2.0 access token.
  • ISSUER_SWITCH_API_ENDPOINT is your issuer switch's API endpoint. For example, api.129a0b1a-bb73-4906-a5b7-a6e0bfe7860e.issuerswitch.goog.

Replace these with values specific to your environment.

When you run this command, you see a response similar to the following:

{
  "metadataTransactions": [
    {
      "name": "projects/PROJECT_ID/metadataTransactions/GOO963805f556e48b1b2def079d5e52901",
      "info": {
        "id": "GOO963805f556e48b1b2def079d5e52901",
        "apiType": "LIST_ACCOUNTS",
        "transactionType": "TRANSACTION_TYPE_LIST_ACCOUNTS",
        "transactionSubType": "TRANSACTION_SUB_TYPE_UNSPECIFIED",
        "state": "SUCCEEDED",
        "errorCode": "",
        "errorMessage": "",
        "createTime": "2022-04-19T04:19:38.910493Z",
        "bankAdapterRequestId": "eacdcf92-4fa9-47e5-a51d-e030b70c2b7e",
        "upiErrorCode": ""
      },
      "originVpa": "foo@okgoog"
    }
  ]
}

Search for mandate transactions

To search for mandate transactions using the issuer switch API, use the ListMandateTransactions method [REST gPRC].

Specify filter criteria using the filter parameter. This parameter allows you to filter transactions based on various fields such as the unique mandate number (UMN), transaction ID, transaction type, payer or payee VPA, payer or payee mobile number, and so on. You can specify multiple criteria, so that only results that match all the specified criteria are returned. The UMN is unique for every mandate, so if you specify the UMN, all transactions related to that mandate are returned. For example, if a mandate was created and then updated, specifying the UMN for that mandate returns both the create transaction and the update transaction. The transaction ID is unique for each transaction. See the ListMandateTransactions API documentation for the complete list of supported filter criteria.

The following curl command lists the transaction where the specified mandate was created.

curl -X GET -H "Authorization: Bearer $TOKEN" "https://ISSUER_SWITCH_API_ENDPOINT/v1/projects/PROJECT_ID/mandateTransactions?filter=uniqueMandateNumber%3Dmandate%40okgoog%20AND%20transactionType%3DTRANSACTION_TYPE_CREATE"

In this example:

  • PROJECT_ID is the ID of your Google Cloud project.
  • $TOKEN is your OAuth 2.0 access token.
  • ISSUER_SWITCH_API_ENDPOINT is your issuer switch's API endpoint. For example, api.129a0b1a-bb73-4906-a5b7-a6e0bfe7860e.issuerswitch.goog.

Replace these with values specific to your environment.

When you run this command, you see a response similar to the following:

{
  "mandateTransactions": [
    {
      "name": "projects/PROJECT_ID/mandateTransactions/GOO963805f556e48b1b2def079d5e52902",
      "transactionInfo": {
        "id": "GOO963805f556e48b1b2def079d5e52902",
        "apiType": "MANDATE",
        "transactionType": "TRANSACTION_TYPE_CREATE",
        "state": "SUCCEEDED",
        "errorCode": "",
        "errorMessage": "",
        "createTime": "2022-06-11T13:00:09.668525Z",
        "upiErrorCode": ""
      },
      "uniqueMandateNumber": "mandate@okgoog",
      "payerVpa": "foo@okgoog",
      "payeeVpa": "bar@okgoog",
      "payerMobileNumber": "911234567890",
      "payeeMobileNumber": "919876543210",
      "payeeMerchantId": "barMerchantID",
      "startDate": {
        "year": 2021,
        "month": 7,
        "day": 23
      },
      "endDate": {
        "year": 2029,
        "month": 10,
        "day": 22
      },
      "revokable": true,
      "amount": 100,
      "amountRule": "MAX",
      "lastUpdateTime": "2022-06-11T13:00:12.479989Z",
      "recurrencePattern": "ONE_TIME",
      "recurrenceRuleType": "ON",
      "recurrenceRuleValue": 1,
      "approvalReference": "foo-reference"
    }
  ]
}

Search for complaint transactions

To search for complaint transactions using the issuer switch API, use the ListComplaintTransactions method [REST, gRPC].

Specify filter criteria using the filter parameter. This parameter allows you to filter transactions based on various fields such as the transaction ID of the complaint transaction, the transaction type, or the RRN of the transaction for which the complaint is raised. You can specify multiple criteria, so that only results that match all the specified criteria are returned. See the ListComplaintTransactions API documentation for the complete list of supported filter criteria.

The following curl command lists complaint transactions of the specified transaction type and with the specified complaint reference number (CRN).

curl -X GET -H "Authorization: Bearer $TOKEN" "https://ISSUER_SWITCH_API_ENDPOINT/v1/projects/PROJECT_ID/complaintTransactions?filter=crn%3DUPI2005138765432%20AND%20transactionType%3DTRANSACTION_TYPE_COMPLAINT"

In this example:

  • PROJECT_ID is the ID of your Google Cloud project.
  • $TOKEN is your OAuth 2.0 access token.
  • ISSUER_SWITCH_API_ENDPOINT is your issuer switch's API endpoint. For example, api.129a0b1a-bb73-4906-a5b7-a6e0bfe7860e.issuerswitch.goog.

Replace these with values specific to your environment.

When you run this command, you see a response similar to the following:

{
  "complaint_transactions": [
    {
      "name": "projects/PROJECT_ID/complaintTransactions/GOO387edc5d3a86481fac67a491179d04c2",
      "info": {
        "id": "GOO387edc5d3a86481fac67a491179d04c2",
        "api_type": "COMPLAINT",
        "transaction_type": "TRANSACTION_TYPE_COMPLAINT",
        "transaction_sub_type": "REMITTER",
        "state": "SUCCEEDED",
        "error_code": "",
        "error_message": "",
        "create_time": "2022-07-01T11:58:10.531Z",
        "bank_adapter_request_ids": "",
        "upi_error_code": ""
      },
      "complaint": {
        "name": "",
        "raise_complaint_adjustment": {
          "adjustment_flag": "RAISE",
          "adjustment_code": "GOODS_SERVICES_NOT_PROVIDED"
        },
        "details": {
          "original_transaction": {
            "transaction_id": "GOOce24f48309e442d4aad006f3252bad0e",
            "retrieval_reference_number": "123456789098",
            "request_time": null
          },
          "transaction_sub_type": "TRANSACTION_SUB_TYPE_REMITTER",
          "amount": {
            "currency_code": "INR",
            "units": "99",
            "nanos": 990000000
          },
          "original_settlement_response_code": "RR",
          "current_cycle": true
        },
        "response": {
          "complaint_reference_number": "UPI2005138765432",
          "amount": {
            "currency_code": "INR",
            "units": "99",
            "nanos": 990000000
          },
          "adjustment_flag": "DRC",
          "adjustment_code": "NO",
          "adjustment_reference_id": "38fa72224b374c25ab7b6f8beb3ba98d",
          "adjustment_remarks": "",
          "approval_number": "",
          "process_status": "COMPLETED",
          "adjustment_time": "2022-07-01T11:58:13.687143475Z",
          "payer": {
            "participant": {
              "virtual_payment_address": "",
              "persona": "PERSONA_UNSPECIFIED",
              "user": ""
            },
            "account": {
              "ifsc_code": "",
              "account_type": "",
              "account_number": ""
            },
            "merchant_info": null,
            "mobile": "",
            "device_id": ""
          }
        },
        "resolve_complaint_adjustment": {
          "adjustment_flag": "DEBIT_REVERSAL_CONFIRMATION",
          "adjustment_code": "REASON_CODE_UNSPECIFIED"
        }
      }
    }
  ]
}