Method: payments.search

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

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.

HTTP request

POST https://issuer-bank-adapter.your-domain.com/v1/payments:search

Request body

The request body contains data with the following structure:

JSON representation
{
  "paymentId": string,
  "settlementType": enum (SettlementType),
  "retrievalReferenceNumber": string,
  "requestTime": string
}
Fields
paymentId

string

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

settlementType

enum (SettlementType)

Type of settlement.

retrievalReferenceNumber

string

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

requestTime

string (Timestamp format)

Timestamp of the payment settlement transaction request being searched for.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

Response body

If successful, the response body contains data with the following structure:

Information about a payment previously requested.

JSON representation
{
  "settlementPaymentResponse": {
    object (SettlePaymentResult)
  },
  "settlementState": enum (SettlementState)
}
Fields
settlementPaymentResponse

object (SettlePaymentResult)

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

settlementState

enum (SettlementState)

The status of the overall settlement.

SettlePaymentResult

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

JSON representation
{

  // Union field settle_payment_result can be only one of the following:
  "success": {
    object (SettlePaymentResponse)
  },
  "error": {
    object (SettlePaymentError)
  }
  // End of list of possible types for union field settle_payment_result.
}
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

object (SettlePaymentResponse)

Successful settlement response.

error

object (SettlePaymentError)

Settlement Error Response.

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.

JSON representation
{
  "errorReason": enum (ErrorReason)
}
Fields
errorReason

enum (ErrorReason)

Error reason for the original payment 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.