JavaScript is disabled. Some features may not work. You can also read the static version: View text version

Approve/Decline a Collect Request

This api is to review and take an action on a pending payment request. requestType can be APPROVE or DECLINE. If requestType is APPROVE, then payeeName and credBlock parameters are mandatory. A collect request is successfully approved when gatewayResponseCode is 00 in response. A collect request is successfully declined only when gatewayResponseCode is ZA in response.

Note: SERVICE_UNAVAILABLE_{entity}_{error} will be returned in case of NPCI timeout or deemed transactions.

Request

Response

API Endpoints

Production Link

POST

http://{{host}}/api/{uri}/merchants/transactions/collect

                      Content-Type
                      *
                      

string

Required

application/json

                      x-merchant-signature
                      *
                      

string

Required

This is a signature over combination of headers, payload. Refer Signature Calculation section for more details.

                      x-merchant-id
                      *
                      

string

Required

Will be shared while onboarding.

                      x-merchant-channel-id
                      *
                      

string

Required

Will be shared while onboarding.

                      Accept
                      *
                      

string

Required

application/json

                      x-timestamp
                      *
                      

string

Required

This is an epoch unix timestamp string. For example, 1496918882000. It can be used by us to invalidate older requests.

Body

                      merchantCustomerId
                      *
                      

String

Mandatory

Merchant generated unique profile id for customer
Constraints: Alphanumeric string with dot(.). Maximum length is 256.

                      deviceFingerPrint
                      *
                      

String

Mandatory

Device fingerprint of the customer

                      merchantRequestId
                      *
                      

String

Mandatory

Merchant generated id for the transaction
Constraints: 35 characters alphanumeric

                      payerVpa
                      *
                      

String

Mandatory

If collectType is null or TRANSACTION, Vpa of the customer request to be used for payment and if collectType is MANDATE, umn of the mandate.

                      payeeVpa
                      *
                      

String

Mandatory

Vpa of the payee to whom money is being sent
Constraints: something@handle

                      payeeName
                      
                      

String

optional

Name of the payee

                      amount
                      *
                      

String

Mandatory

Amount for transaction
Constraints:Numeric string with two decimals

                      upiRequestId
                      *
                      

String

Mandatory

Unique id sent to UPI switch for the transaction
Constraints:35 character alphanumeric

                      collectType
                      
                      

String

optional

Differentiates between a transaction collect request (TRANSACTION) or a mandate execution collect request (MANDATE).
Constraints:TRANSACTION or MANDATE

                      requestType
                      *
                      

String

Mandatory

Action to be taken on the collect request
Constraints:APPROVE or DECLINE

                      bankAccountUniqueId
                      *
                      

String

Mandatory

Unique id for the selected bank account
Constraints:bankAccountUniqueId in the response of Fetch Accounts api call

                      credBlock
                      
                      

String

optional

Encrypted credblock containing user mpin
Constraints:As returned by Common Library

                      currency
                      *
                      

String

Mandatory

Currency code
Constraints:String - INR

                      udfParameters
                      
                      

JSON string

optional

Stringified JSON for udf parameters

                      packageName
                      
                      

String

optional

Package name of the UPI application

                      clVersion
                      
                      

String

Optional

Common Library Version of the UPI application clVersion
Constraints: Common Library Version of the UPI application (Mandatory for BioAuth payments)

Response Body

                      status
                      *
                      

String

Mandatory

PSP status of the API
Values: SUCCESS, FAILURE

                      responseCode
                      *
                      

String

Mandatory

PSP response code for the API
Values: Refer error code section

                      responseMessage
                      *
                      

String

Mandatory

PSP response message for the API
Values: Refer error code section

                      payload
                      *
                      

JSON

Mandatory

                      merchantId
                      *
                      

String

Mandatory

Unique id for the merchant as passed in request headers

                      merchantChannelId
                      *
                      

String

Mandatory

Unique id for the merchant channel as passed in request headers

                      merchantCustomerId
                      *
                      

String

Mandatory

Merchant generated unique profile id for customer as passed in the request

                      merchantRequestId
                      *
                      

String

Mandatory

Merchant generated request id as passed in the collect request

                      customerMobileNumber
                      *
                      

String

Mandatory

Customer mobile number
Values: 12 digits mobile number string

                      payerVpa
                      *
                      

String

Mandatory

If collectType is null or TRANSACTION, Vpa of the customer who received the collect request and if collectType is MANDATE, umn of the mandate.

                      payeeMcc
                      *
                      

String

Mandatory

MCC for the payee

                      payeeMerchantCustomerId
                      *
                      

String

Mandatory

Merchant generated unique id for customer who received the payment. Only if it is an onus P2P transaction.

                      payeeVpa
                      *
                      

String

Mandatory

Vpa of the upi user who received the payment
Values: As passed in the request

                      payeeName
                      *
                      

String

Mandatory

Name of the upi user who received the payment. Only if payment is done to a non A/C+IFSC vpa.

                      refUrl
                      *
                      

String

Mandatory

Reference url for the intent transaction

                      bankAccountUniqueId
                      *
                      

String

Mandatory

Unique id for the selected bank account
Values: As passed in the request

                      bankCode
                      *
                      

String

Mandatory

Bank code of the account which was used
Values: Valid bank IIN

                      maskedAccountNumber
                      *
                      

String

Mandatory

Masked account number of the account which was used
Values: XXXX123456

                      amount
                      *
                      

String

Mandatory

Amount for the payment
Values: As passed in the request

                      transactionTimestamp
                      *
                      

String

Mandatory

Timestamp of when the transaction was attempted
Values: YYYY-MM-DDTHH:MM:SS+05:30

                      gatewayTransactionId
                      *
                      

String

Mandatory

Transaction id returned by gateway

                      gatewayReferenceId
                      *
                      

String

Mandatory

Reference id returned by the gateway

                      gatewayResponseStatus
                      *
                      

String

Mandatory

Response status returned by gateway
Values: SUCCESS, DECLINED, FAILURE

                      gatewayResponseCode
                      *
                      

String

Mandatory

Response code returned by gateway

                      gatewayResponseMessage
                      *
                      

String

Mandatory

Response message for code returned by gateway

                      gatewayPayerResponseCode
                      
                      

String

optional

Response code returned by gateway

                      gatewayPayeeResponseCode
                      
                      

String

optional

Response code returned by gateway

                      gatewayPayerReversalResponseCode
                      
                      

String

optional

Response code returned by gateway

                      gatewayPayeeReversalResponseCode
                      
                      

String

optional

Response code returned by gateway

                      requestType
                      *
                      

String

Mandatory

Action to be taken on the collect request. As passed in the request body
APPROVE or DECLINE

                      collectType
                      
                      

String

optional

Differentiates between a transaction collect request (TRANSACTION) or a mandate execution collect request (MANDATE).
Values: TRANSACTION or MANDATE

                      seqNumber
                      
                      

String

optional

Denotes the recurring cycle of mandate execution. Will be received only during mandate executions.

                      riskScore
                      
                      

String

optional

RiskScore shared by NPCI or Bank

                      udfParameters
                      
                      

JSON String

optional

Udf parameters as passed in the request