Introduction

This is the api reference document for Multibank UPI PSP backend. In the multibank model all are Server to Server APIs. We use application/json content type for our request and response type.

Before this document explains more about every API, let's start with the philosophy behind the structure of request and response of the APIs.

HTTP Response Codes

500: This error will only come in case any of the internal service is down. Some examlples are newtork issue, server crashes, etc.

401: In case of signature mismatch or invalid credentials.

200: For all other queries. Any business logic or validation error can have a response as 200 OK but the data will have status = FAILURE. Details of this behavior will be explained later in this document.

Note

1. These are specific to our logic. While all other HTTP error codes are still valid.
2. x-response-signature and udfParameters will be only present in responses where HTTP response code is 200.

Request Structure

Headers

{
  "content-type": "application/json",
  "accept": "application/json",
  "x-merchant-id": "TEST",
  "x-merchant-channel-id": "TESTAPP",
  "x-timestamp": "1496918882000",
  "x-merchant-signature": "26b339a48db62a..."
}

All the request must have following headers.

Header Name	Header Value
content-type	application/json
accept	application/json
x-merchant-id	Will be shared while onboarding.
x-merchant-channel-id	Will be shared while onboarding.
x-timestamp	This is an epoch unix timestamp string. For example, 1496918882000. It can be used by us to invalidate older requests.
x-merchant-signature	This is a signature over combination of headers, payload. Refer Signature Calculation section for more details.

Signature Calculation

Input = headers["x-merchant-id"] + headers["x-merchant-channel-id"] +
    headers["x-timestamp"] + RequestBody in String UTF-8 encoding
Signature rsa = Signature.getInstance("SHA256withRSA");
rsa.initSign(getPrivate(keyFile));
rsa.update(Input.getBytes("utf-8"));
byte[] signature = rsa.sign();
headers["x-merchant-signature"] =  byteArrayToHex(signature);

Where,

String byteArrayToHex(byte[] a) {
  StringBuilder sb = new StringBuilder(a.length * 2);
  for(byte b: a) sb.append(String.format("%02x", b));
  return sb.toString();
}

Following snippet shows the way to create a signature over the headers and payload of the request.

Note

1. The order of the parameters while creation of a string for signature should be adhered as above.
2. PSS padding is to be used for signature calculation.

RefUrl

An additional url that is provided by the merchant as a part of a p2m collect or intent request that provides additional information about the transaction, i.e., bill/invoice information.

RefCategory

The RefCategory field is used to identify the category of the transaction. It tells whether to show addition information (via refUrl) to the customer. RefCategory can take the following values:

1. 00 -> NULL/Dont show additional information
2. 01 -> Advertisement
3. 02 -> Invoice.

There are others for future use.

Body

This is a JSON. Every API will have its own set of keys and structure. All the request parameters are mandatory for an api unless stated otherwise. The data type of all parameters is string.

Credblock Request Body

# Common `data` structure
"data": {
  "type":"",
  "skey":"",
  "pid":"",
  "ki":"20150822",
  "hmac":"",
  "code": "NPCI",
  "encryptedBase64String": "2.0|mBlwBX...ALoZjNZwD841tZQ==",
  "ki": "20150822"
}

# Sample Set/Reset MPIN credblock
{
  "otpcred": {
    "data": {...},
    "subType": "SMS",
    "type": "OTP"
  },
  "mpincred": {
    "data": {...},
    "subType": "MPIN",
    "type": "PIN"
  }
}

# Sample Change MPIN credblock
{
  "newcred": {
    "data": {...},
    "subType": "MPIN",
    "type": "PIN"
  },
  "mpincred": {
    "data": {...},
    "subType": "MPIN",
    "type": "PIN"
  }
}

# Sample Check Balance, Pay credblock
{
  "mpincred": {
    "data": {...},
    "subType": "MPIN",
    "type": "PIN"
  }
}

Some of the APIs take a credblock string as input. This is an encrypted string generated by the NPCI Common Library and verifies the MPIN with customer bank. The credblock strings of various apis are dereived from a common data structure.

In the Set MPIN api for example, there are two data blocks. One for the OTP and one for the MPIN.

Initiation Mode

Mode	Meaning
00	Default txn
01	QR Code
02	Secure QR Code
03	Bharat QR
04	Intent
05	Secure Intent
06	NFC
07	BLE (Bluetooth)
08	UHF (Ultra High Frequency)
09	Aadhaar
10	SDK
11	UPI Mandate
12	FIR (Foreign Inward Remittance)
13	Static Secure QR Mandate (Offline)
14	Restricted
15	Dynamic QR Code (Offline)
16	Dynamic Secure QR Code (Offline)
17	Dynamic Secure QR Mandate (Offline)
18	ATMQR (Dynamic)
19	Online STATIC QR Code
20	Online STATIC Secure QR Code
21	Online Static QR Mandate
22	Online Dynamic QR Code
23	Online Dynamic Secure QR Code
24	Online Dynamic Secure QR Code Mandate

Purpose code

Code	Meaning
00	Default
01	SEBI
02	AMC
03	Travel
04	Hospitality
05	Hospital
06	Telecom
07	Insurance
08	Education
09	Gifting Common
10	BBPS
11	Global UPI
12	Metro ATM QR
13	Non-metro ATM QR
14	SI
15	Corporate disbursement
20	B2B transactions
25	RDS (For Govt. Securities via RBI Retail Direct Scheme with max limit upto 5L/txn for verified merchants, MCC 6211)
41	UPI Lite Initial Top Up
42	UPI Lite Subsequent Top Up
43	UPI Lite Deregistration with Amount in Wallet
44	UPI Lite Send Money
45	Offline Payments using Lite
46	UPI Lite Transfer Out
50	UPI Lite Zero Balance Disablement
60	Customer from another country wishes to pay to Indian Merchant
71	Initial topup and enablement for UPI Lite Autopay
76	SBMD (Single Block Multiple Debit) for Securities brokers & dealers (Secondary Market)
77	SBMD (Single Block Multiple Debit) for Online goods & service delivery
82	Subsequent topups for UPI Lite Autopay
92	Digital Rupee - CBDC (Wallet Id @drbankname)

Initiating Channels

Channel	Meaning
MOB	Mobile
IOTVOICE	Voice based payments

Response Structure

Headers

{
  "content-type": "application/json",
  "x-response-signature": "26b339a48db62a..."
}

All the response we send will have following headers.

Header Name	Header Value
content-type	application/json
x-response-signature	This is a signature over combination of headers, payload. Refer Signature Calculation section for more details.

Note

1. x-response-signature will be only present in responses where HTTP response code is 200.

Signature Validation

String input = RequestBody in String UTF-8 encoding
String signature = headers["x-merchant-payload-signature"]

Signature rsa = Signature.getInstance("SHA256withRSA");
rsa.initVerify(getPublic(keyFile));
rsa.update(input.getBytes("utf-8"));

boolean isSignatureSame = rsa.verify(Hex.decode(signature));

At the time of onboarding, PSP will share a public key with the merchant. The algorithm used for creating the signature is SHA256 RSA with PSS padding. Following snippet shows how merchant has to validate the signature at their end.

Note

1. The order of the parameters while creation of a string for signature should be adhered as above.
2. PSS padding is to be used for signature calculation.

Body

{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {},
  "udfParameters": "{}"
}

Every valid API response will have a valid json as a response body. Our general philosophy around the response structure is, response json should contain a key called status. The value of this key can be SUCCESS or FAILURE.

Consumers should first look at this key and decide whether querying was a success or not. If status is SUCCESS, there will be another key as payload which will be the output for the API being consumed. In case of failure, check the keys called responseCode and responseMessage which will give details around the reason for querying failure.

Details about the structure will be explained later in this document.

Note

1. udfParameters will be only present in responses where HTTP response code is 200.

VpaAccount Response Body

"vpaAccount": {
  "account": {
    "bankCode": "607153",
    "bankName": "BankName",
    "maskedAccountNumber": "XXXX8796",
    "mpinLength": "6",
    "mpinSet": "true",
    "otpLength": "6",
    "atmPinLength": "4",
    "type": "SAVINGS",
    "ifsc": "BankIFSC",
    "name": "Ram Singh",
    "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf"
  },
  "vpa": "vpa@handle",
  "isDefault": "true"
}

Some of the account management APIs return a vpaAccount object as part of their response. This is a nested json containing data related to the customer account and the vpas linked to it.

Response parameters

Parameter	Description	Values
bankCode	IIN of the bank for the account	String
bankName	Name of bank for the account	String
maskedAccountNumber	Masked account number as returned by NPCI	String
mpinLength	MPIN length for the account	String
mpinSet	Flag to denote if the account has MPIN set or not	Boolean string
otpLength	OTP length for the account	String
atmPinLength	ATM PIN length for the account used for FORMAT2 usecases	String
type	Type of the account as returned by NPCI	SAVINGS, CURRENT,CREDIT,DEFAULT,NRE,NRO,UOD,SOD etc
ifsc	Ifsc for the bank account as returned by NPCI	String
name	Name of the account holder as returned by NPCI	String
bankAccountUniqueId	Unique id for the bank account (does not change incase customer deregisters)	sha256(accountNumber + ifsc.substr(0,4))
vpa	Vpa linked to the bank account	vpa@handle
isDefault	Flag denoting whether this account is default for the given vpa or not (incoming money to a vpa is credited to its default account)	Boolean string

Error Codes

{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {},
  "udfParameters": "{}"
}

Every valid API response will have a valid json as a response body. Our general philosophy around the response structure is, response json should contain a key called status. The value of this key can be SUCCESS or FAILURE.

Consumers should first look at this key and decide whether querying was a success or not. If status is SUCCESS, there will be another key as payload which will be the output for the API being consumed. In case of failure, check the keys called responseCode and responseMessage which will give details around the reason for querying failure.

Common API Error Codes

# Here are some examples of error codes

# HTTP 200 OK
{
  "status": "FAILURE",
  "responseCode": "BAD_REQUEST",
  "responseMessage": "merchantCustomerId regex match not found"
}

# HTTP 200 OK
{
  "status": "FAILURE",
  "responseCode": "INVALID_DATA",
  "responseMessage": "Invalid merchantCustomerRegistrationTokenReferenceId"
}

# HTTP 500
{
  "status": "FAILURE",
  "responseCode": "INTERNAL_SERVER_ERROR",
  "responseMessage": "INTERNAL_SERVER_ERROR"
}

# HTTP 401
{
  "status": "FAILURE",
  "responseCode": "UNAUTHORIZED",
  "responseMessage": "UNAUTHORIZED"
}

# HTTP 200 OK
{
  "status":"FAILURE",
  "responseCode": "SERVICE_UNAVAILABLE_NPCI_406",
  "responseMessage": "UPI Service is not reachable at a moment"
}

These are the common error codes which can come for any of the APIs,

responseCode	Meaning
BAD_REQUEST	This error will be returned in case a mandatory parameter is missing from the request or some regex mismatch happens.
INVALID_DATA	In case all madantory keys are passed, but they contain an incorrect value. For example, in send money api call merchant passes a payer vpa that does not belong to the customer.
INTERNAL_SERVER_ERROR	This error will be returned in case something went wrong with internal PSP components. For example, the database server went down. Ideally this error should never come.
UNAUTHORIZED	This error will come in case the validation of merchant signature fails at PSP.
DEVICE_FINGERPRINT_MISMATCH	This error will come in case the customer device fingerprint is not valid.
REQUEST_EXPIRED	This error will be returned in case the x-timestamp header passed in request is older than 30 minutes.
SERVICE*UNAVAILABLE*{entity}_{error}	This error will be returned in case the third party servers are not reachable from PSP. entity will be the third party that is not reachable like NPCI, etc. error will be the HTTP error returned by the third party servers like 406, timeout, reset, etc.

Error codes specific to particular APIs are discussed later in the document.

Note

1. In case of BAD_REQUEST and INVALID_DATA errors, the responseMessage field will have more details on the error.
2. HTTP 401 will be returned with UNAUTHORIZED.
3. HTTP 500 will be returned with INTERNAL_SERVER_ERROR.
4. HTTP 200 will be returned with all other error codes.

Monitoring of Error Codes

# Monitoring of error codes
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
    "gatewayReferenceId": "809323430413",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Successful"
  },
  "udfParameters": "{}"
}

Merchants can setup monitoring of api responses at their end.

HTTP response codes can be monitored as described in the HTTP Response Codes section. Every valid API response will have a valid json as a response body. The response json should contain a key called status. The value of this key can be SUCCESS or FAILURE. In case of failure, check the keys called responseCode and responseMessage which will give details around the reason for querying failure.

Incase for an API, the PSP requires to interact with third party systems (like NPCI, CBS), additional parameters gatewayResponseStatus, gatewayResponseCode and gatewayResponseMessage will be returned in the response. gatewayResponseStatus is the status returned by the third party, gatewayResponseCode is the error code retuned by the third party and gatewayResponseMessage is a human readable error messsage for the error code.

Flows

This section describes the various flows supported by the PSP.

• Device Binding
• Device Registration with NPCI
• Account Management
• Transactions

Multiple APIs can be involved in each flow.

Utility APIs

These are the various utility apis.

List Banks

curl -L -X GET '{{host}}/api/n2/merchants/banks'

# Response: HTTP 200 OK
{
  "banks": [{
    "name": "Bank of XYZ",
    "code": "12345",
    "upiEnabled": true,
    "referenceId": "JUS_ABCXYZ",
    "mobRegFormat": "FORMAT1",
    "versionSupported": {
      "Version": [
        {
          "description": "ITS A BASE VERSION",
          "mandatory": "true",
          "no": "1.0"
        },
        {
          "description": "ITS A FIR VERSION",
          "mandatory": "true",
          "no": "2.0"
        },
        {
          "description": "ITS A MANDATE VERSION",
          "mandatory": "false",
          "no": "2.1"
        },
        {
          "description": "Lite",
          "mandatory": "false",
          "no": "2.98"
        },
        {
          "description": "Credt card",
          "mandatory": "false",
          "no": "2.99"
        }
      ]
    }
  }]
}

This api can be used for getting the list of banks available on the UPI ecosystem.

Response parameters

Parameter	Description	Values
name	Name of the bank	String
code	Unique IIN for the bank	Numeric String
upiEnabled	Flag denoting whether bank is enabled for UPI or not	Boolean
referenceId	PSP generated reference id for bank	String
mobRegFormat	Mobile registraion format type for the bank	FORMAT1, FORMAT2, FORMAT3
versionSupported	Details of all the features supported by the bank	JSON

Note: This api does not require any authentication.

List NPCI Keys

curl -L -X GET '{{host}}/api/n2/merchants/npci/keys'
-H 'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...', \
  'x-api-version' : '1'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "npciKey": "PD94bWwgdMS4wI...iBlbmNvRS2V5cz4="
  },
  "udfParameters": "{}"
}

# For UPI Lite
curl -L -X GET '{{host}}/api/n2/merchants/npci/keys'
-H 'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
  'x-api-version: 1'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "npciKey": "PD94bWwgdMS4wI...iBlbmNvRS2V5cz4="
  },
  "udfParameters": "{}"
}

This api can be used for fetching the NPCI public keys.

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
npciKey	NPCI public key to be passed to Common Library	Base64 String

Registration APIs

Here we describe the various apis available to support the device binding flows.

Get SMS Token

curl -L -X POST '{{host}}/api/n2/merchants/customer/getSmsToken' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "deviceId":"device-id-1",
  "os":"ios",
  "provider": "VODAFONE",
  "udfParameters": "{}"
}'

# Response: 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "serviceProviders": [{
      "name": "Vodafone",
      "number": "09988776655"
    },{
      "name": "Airtel",
      "number": "09876543210"
    }]
    "smsContent": "UPIACT ad56ef90396348bac56099",
    "expiryTimestamp": "2017-06-09T17:57:49+05:30"
  },
  "udfParameters": "{}"
}

This API will start the device binding process and return an sms token. The sms token will provide the sms text and the virtual mobile number(VMN) for the sms to be sent from customer device. A new sms token will be returned every time this api is called.

Request parameters

Parameter	Description	Constraints
deviceId	Unique identifier for the device	String
os	Operating system running on the device	String
provider optional	Cellular provider for VMN selection strategy	String from ENUM [AIRTEL, VODAFONE, JIO, BSNL, UNKNOWN]
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
serviceProviders	Array of VMNs that can be used for device binding for this token	Array of object
name	Name of the VMN service provider like Vodafone, Airtel	String
number	Number of the VMN service provider	Numeric String
smsContent	SMS content to be used for device binding for this token	String
expiryTimestamp	Expiry timestamp for the SMS token	YYYY-MM-DDTHH:MM:SS+05:30
udfParameters optional	Udf parameters as passed in the request	JSON string

SMS Retriever

curl --location 'http://34.93.161.62:8030/api/n2/merchants/customer/registration/init' \
--header 'Content-Type: application/json' \
--header 'x-merchant-id: APLTEST' \
--header 'x-merchant-channel-id: APLTEST' \
--header 'x-timestamp: 1754898452901' \
--header 'x-merchant-checksum: bypass' \
--header 'x-merhant-signature: 530d57f225453e199957c73917c7e01ece46520afcfb3336d6c0f72d9e8d7d39aa696447995bd3e09a4708a8e3c92624b7600329abe271935938ffe275701c652cf78044df73690fe7d546ba043a4406fa20e9e5298bb72af294cd1f79c4387066eb86ec2377a1db50682800a3d00f9d7144d342ad4b912fb8232497068423737d1c635124f87591ae44078c5f1dfd68752282e1911a190a7ffaa48b24e7f30e3ca3badfb9a6d7d75a89aa44b4c09b55dd38f107aa688aa962406267bd2106785f6e4a66f211f4c43bf399e8f20fb5328c6c89e8b8b7061864f509aaba968de883d4507bd479114bf742ee3e052ef98afd78741ee0d8628188068f566b7b0010' \
--header 'x-sandbox-id: YESBAMZ' \
--data '{
    "merchantCustomerId": "amzn1.account.N573334",
    "registrationFlow": "OTP",
    "deviceId" : "test-device-573334",
    "mobileNumber": "911142230528",
    "appHash": "amazonpay",
    "packageName": "amazonpayios",
    "udfParameters": "{}"
}'


# Response:
{
   "status": "SUCCESS",
   "responseMessage": "Trigger otp Success",
   "responseCode": "TRIGGER_OTP_SUCCESS",
   "payload": {
       "merchantChannelId": "APLTEST",
       "merchantId": "APLTEST",
       "attemptIdentifier": "OTP ppNWGj-7q5IBj?Tx2IbH7gEp*(o25CFkVaDSh",
       "merchantCustomerId": "amzn1.account.N305137",
       "expiryTimestamp": "2025-02-27T13:43:16+05:30"
   },
   "udfParameters": "{}"
}

The SMS Retriever API enables automatic OTP retrieval without requiring manual input from the customer or SMS read permissions.

Request parameters

Param	Description	Constraint
merchantCustomerId	Unique identifier for the customer at merchant end	Alphanumeric string with dot(.). Max length 256
registrationFlow	Registration flow type	SMS / OTP
deviceId	Unique identifier for the device	String
attemptIdentifier	If same to previous request will return the Same OTP	String (Optional)
mobileNumber	Expected mobile number of the customer	12 digit phone number as String
appHash	Unique to the App for receiving OTP via SMS retriever
packageName	Package name of the UPI application	String
udfParameters optional	Stringified JSON for udf parameters	JSON string

Bind Device

curl -L -X POST '{{host}}/api/n2/merchants/customer/bindDevice' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "smsContent": "UPIACT ad56ef90396348bac56099",
  "deviceId": "device-id-1",
  "manufacturer": "Samsung",
  "model": "Galaxy",
  "version": "7.0",
  "os": "ANDROID",
  "ssid": "1234567890",
  "packageName": "test.merchant.upi.com",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "customerMobileNumber": "919988776655",
    "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e"
  },
  "udfParameters": "{}"
}

This api is used to bind the device to customer. If device binding is not completed before the expiry of sms token, the sms token will be marked as expired.

If responseCode = "SMS_VERIFICATION_PENDING" in the response, the api has to be retried.

Note: This api is idempotent for one day.

Request parameters

Param	Description	Constraint
merchantCustomerId	Unique identifier for the customer at merchant end	Alphanumeric string with dot(.). Max length 256
deviceId	Unique identifier for the device	String
attemptIdentifier	attemptIdentifier received in init response	String
mobileNumber	Expected mobile number of the customer	12 digit phone number as String
os	Operating system running on the device	String
manufacturer	Manufacturer of the device	String
model	Model of the device	String
version	Version of the device	String
ssid	Ssid of simId chosen for device binding	String
packageName	Package name of application	String
otp	OTP captured via SMS retriever API	String
senderId	Last 6 characters of SMS header	String
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
customerMobileNumber	Customer mobile number as received from the VMN aggregator	12 digits mobile number string
deviceFingerPrint	PSP generated fingerprint for the device used for binding	String
udfParameters optional	Udf parameters as passed in the request	JSON string

Additional Error Codes

responseCode	Meaning
SMS_VERIFICATION_PENDING	PSP has not recieved a callback from VMN yet, merchant to poll again.
SMS_VERIFICATION_EXPIRED	PSP did not recieve a callback from VMN within expiry, device binding expired.
REGISTRATION_DECLINED	Device binding declined because fraud was suspected.
BIND_DEVICE_LIMIT_EXCEEDED	Bind device limit has exceeded as per guidelines.

Activate Customer

curl -L -X POST '{{host}}/api/n2/merchants/customer/activate' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "smsContent": "UPIACT ad56ef90396348bac56099",
  "merchantCustomerId": "amzn.account.c1.usr1",
  "mobileNumber": "919140454145",
  "deregisterOldCustomer": "true",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "amzn.account.c1.usr1",
    "customerMobileNumber": "919140854145",
    "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e"
  },
  "udfParameters": "{}"
}

This Api is used to activate the merchantCustomer to use UPI services with mobile number recieved in bindDevice response.

If responseCode = "SMS_VERIFICATION_PENDING" in the response, then device binding is not done yet.

If responseCode = "SMS_VERIFICATION_MISMATCH" in the response, customerMobileNumber will be present in the payload of response.

The deregisterOldCustomer flag can be used to handle the scenario where the given merchantCustomerId or mobileNumber is already registered. If this flag is passed as "false" then responseCode = "OPERATION_RESTRICTED_DEREGISTER_CUSTOMER" error will be returned, else the older customer will be auto deregistered.

Note: This api is idempotent for one day.

Request parameters

Param	Description	Constraint
merchantCustomerId	Unique identifier for the customer at merchant end	Alphanumeric string with dot(.). Max length 256
deregisterOldCustomer	Flag denoting whether the older customer should be deregistered or not	Boolean string
attemptIdentifier	attemptIdentifier received in init response	String
mobileNumber	Expected mobile number of the customer	12 digit phone number as String
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
customerMobileNumber	Customer mobile number as received from the VMN aggregator	12 digits mobile number string
deviceFingerPrint	PSP generated fingerprint for the device used for binding	String
udfParameters optional	Udf parameters as passed in the request	JSON string

Additional Error Codes

responseCode	Meaning
SMS_VERIFICATION_PENDING	Device binding is not success yet.
REGISTRATION_TOKEN_EXPIRED	PSP did not recieve a callback from VMN within expiry, device binding expired.
SMS_VERIFICATION_MISMATCH	Customer mobile number recieved from the VMN is not same as the one passed by merchant
BIND_DEVICE_LIMIT_EXCEEDED	Bind device limit has exceeded as per guidelines.
OPERATION_RESTRICTED_DEREGISTER_CUSTOMER	Active device binding already exists for the customer, deregister before continuing.
JPDL	If the merchantCustomer or mobile number is already binded and an active mandate is there.

[Draft] Decline Device Binding

curl -L -X POST '{{host}}/api/n2/merchants/customer/declineDeviceBinding' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "smsContent": "UPIACT ad56ef90396348bac56099",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "gatewayResponseCode": "JP19",
    "gatewayResponseMessage": "Device binding declined"
  },
  "udfParameters": "{}"
}

This api is to be used for declining the device binding in case of an app toggle by customer.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
smsContent	SMS content to be used for device binding for this token	As returned by the Get SMS Token api.
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
gatewayResponseCode	Response code for device binding	Boolean string
gatewayResponseMessage	Response message for device binding	Boolean string
udfParameters optional	Udf parameters as passed in the request	JSON string

Get NPCI Token

curl -L -X POST '{{host}}/api/n2/merchants/npci/token' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "tokenRequestType": "initial",
  "tokenChallenge": "LtPrxuUTsXH4bOlj08BuGsIZiN...5k8GtW5LchPgz8+Vg0lGs1uYJrkLwA==",
  "udfParameters": "{}",
  "packageName": "in.amazon.mShop.android.shopping"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "919988776655",
    "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "NPCI token generated succesfully"
    "npciToken": "ZFznYL6htX83bJYI7pIMZEkz9djLeSvcNgzh+kQ/PdQ="
  },
  "udfParameters": "{}"
}

This api generate a new NPCI token. This token is to be used when calling the Common Library APIs.

npciToken will be returned only if gatewayResponseCode = "00".

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
upiRequestId	Unique request id passed to UPI switch	35 character alphanumeric. Should always start with merchant prefix provided.
deviceFingerPrint	Device fingerprint of the customer	String
tokenRequestType	Type of operation to be performed on the token	String - Pass initial (For New Token Creation), rotate (For Expired Token Updation)
tokenChallenge	Challenge for the NPCI token generation	Base 64 encrypted string as returned by Common Library
udfParameters optional	Stringified JSON for udf parameters	JSON string
packageName optional	Package name of the UPI application	String

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number as per device binding	12 digits mobile number string
gatewayTransactionId	Transaction id returned by gateway for the request	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
npciToken optional	NPCI token for Common Library	Base 64 encrypted string
udfParameters optional	Udf parameters as passed in the request	JSON string

[Draft] Delink Customer

curl -L -X POST '{{host}}/api/n2/merchants/customer/delink' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "918969453703"
  }
  "udfParameters": "{}"
}

This api can be used to delete all the vpa and accounts of the customer. The device binding of the customer will be preserved.

Note: This is an idempotent api.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number as per device binding	12 digits mobile number string
udfParameters optional	Udf parameters as passed in the request	JSON string

Deregister Customer

curl -L -X POST '{{host}}/api/n2/merchants/customer/deregister' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "delink": "PROFILE",
  "appIds": [{
      "merchantId": "SUBTEST",
      "merchantChannelId": "SUBTESTAPP"
    }]
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "918969453703"
  }
  "udfParameters": "{}"
}

This api can be used to deregister the customer from UPI ecosystem. Customers device binding, all vpas, all accounts and their mappings will be deleted.

Note: This is an idempotent api.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
delink optional	Delink type of the profile	CUSTOMER or PROFILE
appIds optional	Only for P2MSDK which is the list of merchants	Array of JSON of merchantId and channelId of partner app to be delinked
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number as per device binding	12 digits mobile number string
appIds optional	Only for P2MSDK which is the list of merchants	Array of JSON of merchantId and channelId of partner app which are delinked
udfParameters optional	Udf parameters as passed in the request	JSON string

Fetch Customer Info

curl -L -X POST '{{host}}/api/n2/merchants/customer/info' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload": {
        "merchantChannelId": "TESTAPP",
        "merchantId": "TEST",
        "vpaAccounts": [
            {
                "vpa": "vpa@handle",
                "account": {
                    "maskedAccountNumber": "878658XXXXXXXX8",
                    "otpLength": "6",
                    "mpinSet": "true",
                    "atmPinLength": "4",
                    "referenceId": "Aff604056f9c4c58a91ed7bbd38b6b",
                    "name": "ABC",
                    "ifsc": "AABD0000011",
                    "type": "SOD",
                    "bankCode": "500007",
                    "mpinLength": "6",
                    "bankAccountUniqueId": "7cfeac090d01a0eca9d644946ac82cb3731203691a2d30ca45a5dfb986c3f2a8",
                    "bankName": "Mybank"
                },
                "isDefault": false
            },
            {
                "vpa": "vpa1@handle",
                "account": {
                    "maskedAccountNumber": "878658XXXXXXXX8",
                    "otpLength": "6",
                    "mpinSet": "true",
                    "atmPinLength": "4",
                    "referenceId": "Aff604056f9c4c58a91ed7bbd38b6b",
                    "name": "ABC",
                    "ifsc": "AABD0000011",
                    "type": "SOD",
                    "bankCode": "500007",
                    "mpinLength": "6",
                    "bankAccountUniqueId": "7cfeac090d01a0eca9d644946ac82cb3731203691a2d30ca45a5dfb986c3f2a8",
                    "bankName": "Mybank"
                },
                "isDefault": false
            },
            {
                "vpa": "vpa1@handle",
                "account": {
                    "maskedAccountNumber": "XXXXXXXXXX254769",
                    "otpLength": "6",
                    "mpinSet": "true",
                    "atmPinLength": "6",
                    "referenceId": "Aeb111f994d74d8da2342f7a782f0b",
                    "name": "ABC",
                    "ifsc": "AABF0008032",
                    "type": "CURRENT",
                    "bankCode": "500004",
                    "mpinLength": "6",
                    "bankAccountUniqueId": "58dec06b75ade81beed1656cbed64ea8440ce24a28cb240814589d1299e0dbed",
                    "bankName": "Mypsp2"
                },
                "isDefault": true
            },
            {
                "vpa": "vpa@handle",
                "account": {
                    "maskedAccountNumber": "XXXXXXXXXX254769",
                    "otpLength": "6",
                    "mpinSet": "true",
                    "atmPinLength": "6",
                    "referenceId": "Aeb111f994d74d8da2342f7a782f0b",
                    "name": "ABC",
                    "ifsc": "AABF0008032",
                    "type": "CURRENT",
                    "bankCode": "500004",
                    "mpinLength": "6",
                    "bankAccountUniqueId": "58dec06b75ade81beed1656cbed64ea8440ce24a28cb240814589d1299e0dbed",
                    "bankName": "Mypsp2"
                },
                "isDefault": true
            }
        ],
        "upiNumbers": [
            {
                "vpa": "vpa@handle",
                "upiNumber": "88617898",
                "upiNumberStatus": "ACTIVE"
            }
        ],
        "customerMobileNumber": "911111111288",
        "deviceDetails": {
            "manufacturer": "Samsung",
            "packageName": "test.TEST.com",
            "ssid": "1234567890",
            "deviceFingerPrint": "cb2cc63392c9753d9bf25607b68e7a3fe02b2d7b8f9238419e80de542e3ab439",
            "os": "ANDROID",
            "model": "Galaxy",
            "version": "7.0",
            "deviceId": "432563523"
        },
        "merchantCustomerId": "JTEST123"
    },
    "udfParameters": "{}"
}

This api returns the registration and account information maintained at the PSP for the customer. Merchants can use this api to periodically sync data with the PSP.

Note You can add --header 'x-api-version: 1' to get UpiNumbers linked with the merchantCustomer.

This is yet to be launched in production.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number as per device binding	12 digits mobile number string
deviceFingerPrint	Fingerprint of the customer device	String
deviceId	Unique identifier for the customer device	String
manufacturer	Manufacturer of the customer device	String
model	Model of the customer device	String
version	Version of the operating system on the customer device	String
os	Operating system running on the customer device	String
ssid	Identifier of the SIM used to send the SMS	String
packageName	Package name of the UPI application	String
vpaAccounts	Vpa account mapping of the customer	Array of vpa accounts
upiNumbers optional	upiNumbers of the customer	8-10 digit Number
udfParameters optional	Udf parameters as passed in the request	JSON string

Account Management APIs

Fetch Accounts

curl -L -X POST '{{host}}/api/n2/merchants/accounts/fetch' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "bankCode": "607153",
  "udfParameters": "{}",
  "packageName" : "in.amazon.mShop.android.shopping"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "919988776655",
    "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Accounts fetched successfully",
    "accounts": [{
      "bankCode": "607153",
      "bankName": "BankName",
      "maskedAccountNumber": "XXXX8796",
      "mpinLength": "6",
      "mpinSet": "true",
      "otpLength": "6",
      "atmPinLength": "4",
      "type": "SAVINGS",
      "ifsc": "BankIFSC",
      "name": "Ram Singh",
      "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf"
    }],
    "vpaSuggestions": ["vpa@handle", "vpa2@handle"]
  },
  "udfParameters": "{}"
}

This api fetches customer accounts from NPCI. accounts will be present in the response only if gatewayResponseCode = "00". In case there are one or more accounts fetched, vpaSuggestions will be sent in response.

Note: In case merchant retries this api, the accounts will be fetched from NPCI again.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
deviceFingerPrint	Device fingerprint of the customer	String
bankCode	Bank code (IIN) of selected bank	String
udfParameters optional	Stringified JSON for udf parameters	JSON string
accountType optional	Account Type(In CC TPAP should send accountType as CREDIT, in other cases they can skip sending this field)	String
packageName optional	Package name of the UPI application	String

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Mobile number of the customer	12 digits mobile number string
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
accounts optional	Bank accounts as returned by NPCI for the customer mobile number	Array of accounts
vpaSuggestions optional	Vpa suggestions for the bank accounts fetched	Array of strings
udfParameters optional	Udf parameters as passed in the request	JSON string

List Voucher

curl --location 'localhost:8012/api/x2/merchants/vouchers/list' \
--header 'Content-Type: application/json' \
--header 'x-merchant-id: APLTEST' \
--header 'x-merchant-channel-id: APLTEST' \
--header 'x-merchant-signature: 34a6c687f40d4120b19b77234d0a17c1e4691ba1ba9c3f4c75c7b07fa6fbc11b0e0df96ae80f64c817c8023302ce7662759ec41ca1cf6a9209f962eb74a8a342bd48727b28ab2a52bb2423506dd783cdb9da7ae680afcd79c66869e515b584058ebab14ef3f025109d621a006897fdc18d6ed6448089de5158db78d076b46175afa025667483d5f4086cf76196729aacc061431b989dd695cf61246558a74ed1452f9e1bc1f53b94996476f669d78f0fd205348e0bcececb4bf9edeec3d6296637c125332c79fd7302682853c42dc3a6bd6b05e9bf82f3b462931b1041c9ddd501d1f480557e2cabce800a8d1d0e5f369ca0eaa1c80e4b107d90deb440069fe4' \
--header 'x-timestamp: 1546071441685' \
--header 'x-merchant-checksum: true' \
--data '{
    "merchantCustomerId": "mc90864",
    "deviceFingerprint": "e17537d22b4cb1d50e467241a8911652e50ff083883d14dd346290c95e5dc3fa",
    "upiRequestId": "APLasdffasd",
    "udfParameters": null
}'

<Data header="payerName,payeeName,mandateName,payerMcc,payeeMcc,type,valStart,valEnd,amount,acNum,ifsc,payeeBrandName,revokeable,MBEBA,additionalInfo" ver="1.0"/><Data rn="1" value="rose,,SRIRAM,0000,0000,ONETIME,29052024,28112024,1000.00,919977881006,ANDB0123456,,N,N,"/>

#Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "customerMobileNumber": "919988776655",
    "gatewayTransactionId": "",
    "gatewayTimestamp": "",
    "gatewayResponseCode": "",
    "gatewayResponseStatus": "",
    "gatewayResponseMessage": ""
    "merchantId": "APLTEST",
    "merchantChannelId": "APLTEST",
    "merchantCustomerId": "mc90864",
    "vpaSuggestions" : ["qwert@abcd",...],
    "vouchers": [
      {
        "umn": "",
        "payerVpa": "",
        "payeVpa": "",
        "purpose": "",
        "amount": "",
        "mpinSet": "",
        "revokeable": "",
        "sponsorAccountNumber": "",
        "purchaserBrandName": "",
        "sponsorIfsc": "",
        "validityEnd": "",
        "purchaserName": "",
        "validityStart": "",
        "type": "",
        "sponsorName": "",
        "mandateName": "",
        "purchaserMcc": "",
        "sponsorMcc": ""
      }
    ]
  },
  "udfParameters": "{}"
}

This api Fetches active Vouchers for a given mobile number from NPCI.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
deviceFingerPrint	Device fingerprint of the customer	String
fallbackDeviceFingerPrint optional	Fallback Device fingerprint of the customer	String
udfParameters optional	Stringified json for udf parameters.	String

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
customerMobileNumber	Customer mobile number	12 digits mobile number string
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
gatewayTimestamp	Gateway timestamp for the Api call.	String(YYYY-MM-DDTHH:MM:SS+05:30)
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
vpaSuggestions optional	VPA suggestions for the customer generated using a random combination of customers' name, mobile number, and account details. This will come only when available is false.	[qwer@abcd,...]
vouchers optional	List of active vouchers	JSON Array
udfParameters optional	Udf parameters as passed in the request	JSON string

Is Vpa Available

curl -L -X POST '{{host}}/api/n2/merchants/vpas/availability' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "customerVpa": "something@handle",
  "udfParameters": "{}"
}'


#Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "919988776655",
    "available" : "true"/"false",
    "vpaSuggestions" : ["qwert@abcd",...]
  },
  "udfParameters": "{}"
}

This api checks the availability of the VPA and also provides suggestion if the vpa is not available.

Note: This is an idempotent api.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
customerVpa	VPA of the customer for which the availability check is called.	something@handle
udfParameters optional	Stringified json for udf parameters.	String

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
available	Availablity Status	String - "true", "false"
vpaSuggestions optional	VPA suggestions for the customer generated using a random combination of customers' name, mobile number, and account details. This will come only when available is false.	[qwer@abcd,...]
udfParameters optional	Udf parameters as passed in the request	JSON string

Add Account

curl -L -X POST '{{host}}/api/n2/merchants/accounts/add' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf",
  "customerVpa": "vpa@handle",
  "setAsDefaultBank": "true",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "919988776655",
    "vpaAccounts": [{
      "account": {
        "bankCode": "607153",
        "bankName": "BankName",
        "maskedAccountNumber": "XXXX8796",
        "mpinLength": "6",
        "mpinSet": "true",
        "otpLength": "6",
        "atmPinLength": "4",
        "type": "SAVINGS",
        "ifsc": "BankIFSC",
        "name": "Ram Singh",
        "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf"
      },
      "vpa": "vpa@handle",
      "isDefault": "true"
    },{
      "account": {
        "bankCode": "607153",
        "bankName": "BankName",
        "maskedAccountNumber": "XXXX11244",
        "mpinLength": "6",
        "mpinSet": "true",
        "otpLength": "6",
        "atmPinLength": "4",
        "type": "SAVINGS",
        "ifsc": "BankIFSC",
        "name": "John Doe",
        "bankAccountUniqueId": "3b716774b05dad3a2ea219d6f00c45fa54f23619b133e95dec3186050566f09b"
      },
      "vpa": "vpa@handle",
      "isDefault": "false"
    }]
  },
  "udfParameters": "{}"
}

This api links the customer bank account to a vpa (ONE_TO_ONE mapping) / vpas (ONE_TO_MANY mapping). In case the vpa does not exist, same will be created.

If primaryAccountMapping is ONE_TO_ONE then account in request will be set primary for vpa passed in request. If primaryAccountMapping is ONE_TO_ALL then account in request will be set primary for all vpas of a customer. If primaryAccountMapping is NONE then account in request will not be set primary for vpa passed in request.

This is yet to be launched in production.

Additionally, if setAsDefaultBank is passed as "true", then the account becomes default for the customer and all his vpas. All incoming payments to any of the customer vpas will be credited to this account.

Note: This is an idempotent api.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
bankAccountUniqueId	Unique id for the bank account to be linked	bankAccountUniqueId in the response of Fetch Accounts api call.
customerVpa	VPA to which the bank account should be linked	something@handle
setAsDefaultBank	A flag denoting whether the account has to be made default for the customer	Boolean string
primaryAccountMapping	A flag denoting whether the account has to be made primary for the customer	ONE_TO_ONE, ONE_TO_ALL, NONE
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
vpaAccounts	Detail of all the active linked vpas and accounts	VpaAccount array
udfParameters optional	Udf parameters as passed in the request	JSON string

Delete Account

curl -L -X POST '{{host}}/api/n2/merchants/accounts/delete' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf"
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "919988776655",
    "vpaAccounts": [{
      "account": {
        "bankCode": "607153",
        "bankName": "BankName",
        "maskedAccountNumber": "XXXX8796",
        "mpinLength": "6",
        "mpinSet": "true",
        "otpLength": "6",
        "atmPinLength": "4",
        "type": "SAVINGS",
        "ifsc": "BankIFSC",
        "name": "Ram Singh",
        "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf"
      },
      "vpa": "vpa@handle",
      "isDefault": "true"
    }]
  },
  "udfParameters": "{}"
}

This api deletes a customer account and its mapping to corresponding vpas.

Note

1. The last account of the customer cannot be deleted.
2. The default account of the customer cannot be deleted.
3. Device binding will be retained.
4. This is an idempotent api.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
bankAccountUniqueId	Unique id for the bank account to be deleted	bankAccountUniqueId in the response of Fetch Accounts api call.
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
vpaAccounts	Details of the active linked vpa account mappings	VpaAccount array
udfParameters optional	Udf parameters as passed in the request	JSON string

Additional Error Codes

responseCode	Meaning
OPERATION_RESTRICTED_LAST_ACCOUNT	Last account of the customer cannot be deleted
OPERATION_RESTRICTED_DEFAULT_ACCOUNT	Default account of the customer cannot be deleted

Add VPA

curl -L -X POST '{{host}}/api/n2/merchants/vpas/addDefault' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "customerVpa": "vpa2@handle",
  "customerPrimaryVpa": "vpa@handle",
  "deleteCustomerPrimaryVpa": "true",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "919988776655",
    "vpaAccounts": [{
      "account": {
        "bankCode": "607153",
        "bankName": "BankName",
        "maskedAccountNumber": "XXXX8796",
        "mpinLength": "6",
        "mpinSet": "true",
        "otpLength": "6",
        "atmPinLength": "4",
        "type": "SAVINGS",
        "ifsc": "BankIFSC",
        "name": "Ram Singh",
        "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf"
      },
      "vpa": "vpa2@handle",
      "isDefault": "true"
    }]
  },
  "udfParameters": "{}"
}

This api creates an alias to an existing vpa. All the accounts liked to customerPrimaryVpa will be linked to customerVpa.

If deleteCustomerPrimaryVpa is passed as "true" then customerPrimaryVpa will be deleted. This api can also be used for Edit Vpa functionality.

Note

1. Regex for vpa prefix is ^[a-zA-Z0-9]([a-zA-Z0-9-\.]{1,23})[a-zA-Z0-9]$.
2. Regex for mobile number vpa prefix is ^[0-9]{10,12}$.
3. If a customer has already created vpa of his mobile number, he cannot create another mobile number vpa.
4. This is an idempotent api.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
customerVpa	New vpa that is to be added	String
customerPrimaryVpa	Existing vpa whose alias is to be created	String
deleteCustomerPrimaryVpa	Flag denoting whether to delete customerPrimaryVpa	Boolean string
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
vpaAccounts	Details of the active linked vpa account mappings	VpaAccount array
udfParameters optional	Udf parameters as passed in the request	JSON string

Delete VPA

curl -L -X POST '{{host}}/api/n2/merchants/vpas/deleteVpa' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "customerVpa": "vpa@handle",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "919988776655",
    "vpaAccounts": [{
      "account": {
        "bankCode": "607153",
        "bankName": "BankName",
        "maskedAccountNumber": "XXXX8796",
        "mpinLength": "6",
        "mpinSet": "true",
        "otpLength": "6",
        "atmPinLength": "4",
        "type": "SAVINGS",
        "ifsc": "BankIFSC",
        "name": "Ram Singh",
        "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf"
      },
      "vpa": "vpa@handle",
      "isDefault": "true"
    }]
  },
  "udfParameters": "{}"
}

This api deletes a customer vpa and its mapping to corresponding accounts.

After deletion, same customer can claim same vpa again anytime. Here same customer means customer with same merchantCustomerId and same mobileNumber.

Any other customer can claim same vpa only if it is inactive for a period of 2 years.

Note

1. The last vpa of the customer cannot be deleted.
2. Device binding will be retained.
3. This is an idempotent api.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
customerVpa	Customer vpa to be deleted	something@handle
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
vpaAccounts	Details of the active linked vpa account mappings	VpaAccount array
udfParameters optional	Udf parameters as passed in the request	JSON string

Additional Error Codes

responseCode	Meaning
OPERATION_RESTRICTED_LAST_VPA	Last vpa of the customer cannot be deleted

Generate OTP

curl -L -X POST '{{host}}/api/n2/merchants/accounts/otp' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf",
  "customerVpa": "vpa@handle",
  "card": "123456",
  "expiry": "0122",
  "udfParameters": "{}",
  "packageName": "in.amazon.mShop.android.shopping"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "919988776655",
    "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
    "bankCode": "123456",
    "customerVpa": "vpa@handle",
    "maskedAccountNumber": "XXXX123456",
    "mobRegFormat": "FORMAT1",
    "mpinLength": "6",
    "otpLength": "6",
    "atmPinLength": "4",
    "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "OTP generation successful"
  },
  "udfParameters": "{}"
}

This api can be used to generate an otp to be used for set/reset mpin process. Customer has to entre this otp in the Common Library page.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
deviceFingerPrint	Device fingerprint of the customer	String
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
bankAccountUniqueId	Unique id for the selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call.
customerVpa	VPA of the customer linked to the account	something@handle
card	Last 6 digits of the debit card	String
expiry	Expiry of the debit card	String in format MMYY (pass 0149 for Maestro cards)
udfParameters optional	Stringified JSON for udf parameters	JSON string
packageName optional	Package name of the UPI application	String

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
bankAccountUniqueId	Unique id for the selected bank account	As passed in the request
bankCode	Bank code of the account which was used	Valid bank IIN
customerVpa	Vpa of the customer linked to this account	As passed in the request
maskedAccountNumber	Masked account number of the account which was used	XXXX123456
mobRegFormat	Mobile registraion format type	FORMAT1, FORMAT2
mpinLength	MPIN length for the account	String
otpLength	OTP length for the account	String
atmPinLength	ATM PIN length for the account used for FORMAT2 usecases	String
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
udfParameters optional	Udf parameters as passed in the request	JSON string

gatewayResponseCode	Description
00	Success.
ZT	Failure. OTP retry limit exceeded.
Else	Failure. Any other reason.

Set/Reset MPIN

curl -L -X POST '{{host}}/api/n2/merchants/accounts/setMpin' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf",
  "customerVpa": "vpa@handle",
  "credBlock": "{\"otpcred\":{\"type\":\"OTP\",\"subType\":\"SMS\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|IMQQwH6pcsw/cXNOWy...9gnNkA/o8CWGOQ==\",\"code\":\"NPCI\"}},\"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|qhRJ...d9Be7AQg2IFg==\",\"code\":\"NPCI\"}}}",
  "card": "123456",
  "expiry": "0122",
  "udfParameters": "{}",
  "packageName": "in.amazon.mShop.android.shopping"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "919988776655",
    "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
    "bankCode": "123456",
    "customerVpa": "vpa@handle",
    "maskedAccountNumber": "XXXX123456",
    "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Set/Reset MPIN successful"
  },
  "udfParameters": "{}"
}

This api can be used to set/reset mpin for a customer bank account. Set/reset mpin is successful only when gatewayResponseCode = "00".

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
deviceFingerPrint	Device fingerprint of the customer	String
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
bankAccountUniqueId	Unique id for the selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call.
customerVpa	VPA of the customer linked to the account	something@handle
credBlock	Encrypted credblock for containing user otp and mpin	As returned by Common Library
card	Last 6 digits of the debit card	String
expiry	Expiry of the debit card	String in format MMYY (pass 0149 for Maestro cards)
udfParameters optional	Stringified JSON for udf parameters	JSON string
packageName optional	Package name of the UPI application	String

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
bankAccountUniqueId	Unique id for the selected bank account	As passed in the request
bankCode	Bank code of the account which was used	Valid bank IIN
customerVpa	Vpa of the customer linked to this account	As passed in the request
maskedAccountNumber	Masked account number of the account which was used	XXXX123456
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
udfParameters optional	Udf parameters as passed in the request	JSON string

gatewayResponseCode	Description
00	Success.
XN	Failure. No Card Record found.
XL	Failure. Expired Card Details.
ZR	Failure. Invalid / Incorrect OTP.
ZS	Failure. OTP Time expired.
G74	Incorrect mobile registration format used.
Else	Failure. Any other reason.

Change MPIN

curl -L -X POST '{{host}}/api/n2/merchants/accounts/changeMpin' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf",
  "customerVpa": "vpa@handle",
  "credBlock": "{\"newcred\":{\"type\":\"PIN\",\"subType\":\"NMPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|b+I02sxlvw0F...q3kav3YctGUrhEFWL+ow==\",\"code\":\"NPCI\"}},\"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|jCAnXZ...eyiQn90M+5QH8GA==\",\"code\":\"NPCI\"}}}",
  "udfParameters": "{}",
  "packageName": "in.amazon.mShop.android.shopping"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "919988776655",
    "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
    "bankCode": "123456",
    "customerVpa": "vpa@handle",
    "maskedAccountNumber": "XXXX123456",
    "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Change MPIN successful"
  },
  "udfParameters": "{}"
}

This api can be used to change mpin for a customer bank account. Change mpin is successful only when gatewayResponseCode = "00".

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
deviceFingerPrint	Device fingerprint of the customer	String
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
bankAccountUniqueId	Unique id for the selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call.
customerVpa	VPA of the customer linked to the account	something@handle
credBlock	Encrypted credblock for containing user old and new mpin	As returned by Common Library
udfParameters optional	Stringified JSON for udf parameters	JSON string
packageName optional	Package name of the UPI application	String

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
bankAccountUniqueId	Unique id for the selected bank account	As passed in the request
bankCode	Bank code of the account which was used	Valid bank IIN
customerVpa	Vpa of the customer linked to this account	As passed in the request
maskedAccountNumber	Masked account number of the account which was used	XXXX123456
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
udfParameters optional	Udf parameters as passed in the request	JSON string

gatewayResponseCode	Description
00	Success.
ZM	Failure. Invalid / Incorrect MPIN.
Else	Failure. Any other reason.

Check Balance

curl -L -X POST '{{host}}/api/n2/merchants/accounts/balance' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf",
  "customerVpa": "vpa@handle",
  "credBlock": "{\"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|j+dtxs...1ca1o0CrjnUw==\",\"code\":\"NPCI\"}}}",
  "udfParameters": "{}",
  "packageName": "in.amazon.mShop.android.shopping"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "919988776655",
    "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
    "bankCode": "123456",
    "customerVpa": "vpa@handle",
    "maskedAccountNumber": "XXXX123456",
    "balance": "123.00",
    "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Check balance successful",
    "outstandingAmount": "200.00"
  },
  "udfParameters": "{}"
}

This api can be used to get the balance for a customer bank account. balance is sent in response only when gatewayResponseCode = "00".

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
deviceFingerPrint	Device fingerprint of the customer	String
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
bankAccountUniqueId	Unique id for the selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call.
customerVpa	VPA of the customer linked to the account	something@handle
credBlock	Encrypted credblock containing user mpin	As returned by Common Library
udfParameters optional	Stringified JSON for udf parameters	JSON string
packageName optional	Package name of the UPI application	String

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
bankAccountUniqueId	Unique id for the selected bank account	As passed in the request
bankCode	Bank code of the account which was used	Valid bank IIN
customerVpa	Vpa of the customer linked to this account	As passed in the request
maskedAccountNumber	Masked account number of the account which was used	XXXX123456
balance optional	Balance of the bank account used	1234.00
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
udfParameters optional	Udf parameters as passed in the request	JSON string
outstandingAmount optional	Used amount out of the available credit limit in case of a CREDIT or OD account	String

Transaction APIs

Verify VPA 360

# Sample request

curl -L -X POST '{{host}}/api/n2/merchants/vpas/validity360' \
-H 'x-api-version: 1' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "vpa": "8123715658@upi",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "merchantCustomerId": "test-merchantcustomer-1",
  "udfParameters" : "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Verify vpa successful"
    "vpa": "8123715658@upi",
    "name": "TEJA",
    "ifsc": "BankIFSC",
    "iin": "607153",
    "isMerchant": "true",
    "isMerchantVerified": "true",
    "mcc": "1520",
    "merchantType": {
      "identifier": {
        "subCode": "1520",
        "mid": "MG0001",
        "sid": "1520",
        "tid": "78654",
        "merchantType": "SMALL"
      },
      "name": {
        "brand": "Pra Imports",
        "legal": "Indian",
        "franchise": "Raja Babu Imports"
      },
      "ownership": {
        "type": "PRIVATE"
      }
    },
    "featureTags": ["01","05","11"]
  },
  "udfParameters": "{}"
}

This API will be used to resolve the name of the entity to whom a vpa belongs. In case of a valid vpa, it will provide the name and other details of the entity.

name, ifsc and iin will be sent in response only when gatewayResponseCode is "00".

isMerchantVerified, mcc and merchantType will be sent in response only when isMerchant is "true".

UPI Numbers can also be resolved using this API by passing the request parameter vpa in the format upiNumber@mapper.npci (Example: 9876543210@mapper.npci). The actual VPA mapped to the upiNumber shall be sent in the response parameter vpa.

Note: For featureTags you will need to send x-api-version: 1 in headers.

Request parameters

Parameter	Description	Constraints
vpa	VPA to be verified	something@handle
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
merchantCustomerId optional	Merchant generated unique profile id for customer as passed in the request	String
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
vpa	This is a vpa for which name should be resolved	As passed in request or the VPA mapped to a UPI number
name optional	Name of the customer	String
ifsc optional	IFSC code of the account linked to this VPA	String
iin optional	IIN code of the account linked to this VPA	String
isMerchant	Flag indicating whether the VPA is of merchant or not	Boolean string
isMerchantVerified optional	Flag indicating whether merchant is verified or not	Boolean string
mcc optional	Merchant Category Code for the merchant whose VPA is passed	String
merchantType optional	Merchant Type for the merchant whose VPA is passed	JSON
udfParameters optional	Udf parameters as passed in the request	JSON string
featureTags optional	This will be an array of feature values, each having it's own significance as decided by NPCI	Array of strings

Feature Tag Values

Feature value	Account Type
01	MANDATE
05	CREDIT
06	PPIWALLET
09	UOD
10	VOUCHER
11	Special commercials 1 for RuPay Credit Card on UPI
12	Special commercials 2 for PPI on UPI
13	Special commercials 3 for Credit Line on UPI
31	Credit Line Products
14 to 30	Reserved for future use-cases

Feature Tag Clarification table

Feature value	Meaning
01	Overall Mandate is supported at this merchant at the moment.
05	Overall Credit card on UPI is not accepted at this merchant at the moment.
06	Overall PPI on UPI is not accepted at this merchant at the moment.
09	Overall UOD on UPI is not accepted at this merchant at the moment.
10	Overall VOUCHER on UPI is not accepted at this merchant at the moment.
31	Overall Credit Line on UPI is not accepted at this merchant at this moment.
05,11	Credit Card on UPI is not accepted on this merchant at the moment, however, amount up to INR 2000 is accepted (Only for Small Offline merchants)
06,12	PPI on UPI is not accepted on this merchant at the moment, however, amount up to INR 2000 is accepted (Only for Small Offline merchants)
31,13	Credit Line on UPI is not accepted on this merchant at the moment, however, amount up to INR 2000 is accepted (Only for Small Offline merchants)
11	Invalid
12	Invalid
13	Invalid

Feature value - 11,12,13 always comes in conjunction with 05,06,31 respectively

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Vpa is verified.
ZH	FAILURE	Invalid vpa.
UX	FAILURE	Expired vpa.
ZE	FAILURE	Transaction not permitted to the vpa by PSP.
ZG	FAILURE	Vpa restricted by the customer.
U17	FAILURE	PSP is not registered i.e invalid vpa handle suffix.
MM2	FAILURE	Upi Number Mapping does not exist
MM4	FAILURE	Upi Number Mapping is Disabled
Else	FAILURE	Any other reason.

Send Money

curl -L -X POST '{{host}}/api/n2/merchants/transactions/sendMoney'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-sub-merchant-id': 'SUBMERCHANT', \
  'x-sub-merchant-channel-id': 'SUBMERCHANTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "merchantRequestId": "redId1234",
  "payerVpa": "customer@handle",
  "payeeVpa": "payee@xyz",
  "payeeName": "John Doe",
  "amount:" "2.00",
  "splitDetails": [{"name": "TIPS", "value": "1.00"}, {"name": "CCONFEE", "value": "1.00"}, {"name": "PCONFEE", "value": "1.00"}],
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
  "credBlock": "{\"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|j+dtxs...1ca1o0CrjnUw==\",\"code\":\"NPCI\"}}}",
  "remarks": "Payment for order",
  "currency": "INR",
  "transactionType": "INTENT_PAY",
  "transactionReference": "P1708071422508815250029",
  "refUrl": "https://www.abcxyz.com/",
  "refCategory": "02",
  "mcc": "7299",
  "initiationMode": "00",
  "purpose": "00",
  "mPinCode": "656565",
  "location": "123 Fake Street, Anytown, Somecountry",
  "geocode": "88.888888, 88.888888",
  "udfParameters": "{}",
  "packageName": "in.amazon.mShop.android.shopping",
  "mid": "MERCHANT1234567890",
  "msid": "SUBMERCHANT123456",
  "mtid": "TXN12345678901234567890123456789012345",
  "mSubCode": "7299",
  "mType": "SMALL",
  "mGenre": "ONLINE",
  "mOnBoardingType": "AGGREGATOR",
  "mRegId": "REG1234567890",
  "mPinCode": "560001",
  "mTier": "TIER1",
  "mLoc": "India",
  "mInstCode": "INST1234",
  "mBrand": "DUMMYBRAND",
  "mLegal": "Dummy Legal Entity Pvt Ltd",
  "mFranchise": "Dummy Franchisee",
  "mOwnershipType": "PRIVATE"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "merchantRequestId": "redId1234",
    "customerMobileNumber": "919988776655",
    "payerVpa": "customervpa@bank",
    "payeeMcc": "0000",
    "payeeMerchantCustomerId": "DEMO-CUST-5678",
    "payeeName": "John Doe",
    "payeeVpa": "payee@xyz",
    "refUrl": "https://www.abcxyz.com/",
    "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
    "bankCode": "123456",
    "maskedAccountNumber": "XXXX123456",
    "amount": "2.00",
    "splitDetails": [{"name": "TIPS", "value": "1.00"}, {"name": "CCONFEE", "value": "1.00"}, {"name": "PCONFEE", "value": "1.00"}],
    "transactionType": "INTENT_PAY",
    "transactionTimestamp": "2017-06-09T17:57:49+05:30",
    "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
    "gatewayReferenceId": "809323430413",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Your transaction is successful",
    "gatewayPayerResponseCode": "00",
    "gatewayPayeeResponseCode": "00",
    "gatewayPayerReversalResponseCode": "00",
    "gatewayPayeeReversalResponseCode": "00",
    "riskScore": "00000"
  },
  "udfParameters": "{}"
}

This api will be used for completing all P2P and P2M Payment scenarios. This includes

• Incoming Intent Payment
• Scan and Pay (UPI QR & Bharat QR)
• P2P Pay (Vpa & Account+IFSC)
• Payment to PSP merchant
• Self Pay

The api can be invoked to process different types of payments. The transactionType key of request is used to identify the type of payment. Possible values are P2M_PAY, P2P_PAY, SELF_PAY, INTENT_PAY and SCAN_PAY. Depending on the payment type, some additional parameters need to be passed.

P2M_PAY is to be used for payment to a PSP merchant only. The payeeVpa should be a valid PSP generated vpa for the merchant.

INTENT_PAY and SCAN_PAY are used for the intent and qr scan transactions. Both UPI QR and Bharat QR codes are supported.

P2P_PAY is to be used for completing all other P2P payment scenarios. For direct to account transfers, payeeVpa should be of format <account-no>@<ifsc-code>.ifsc.npci like 12345@BankIFSC.ifsc.npci.

SELF_PAY is to be used for doing a self transfer between customer accounts having same vpa domain.

Below are some request parameters required to be handled specifically according to the payment scenario.

Parameter	P2M Pay	P2P Pay	Scan & Pay	Incoming Intent	Self Pay
transactionType	P2M_PAY	P2P_PAY	SCAN_PAY	INTENT_PAY	SELF_PAY
payeeVpa	Mandatory	Mandatory	pa in deeplink url	pa in deeplink url	Mandatory
payeeName	Not Required	Not required for account transfers only	pn in deeplink url	pn in deeplink url	Mandatory
amount	Mandatory	Mandatory	am in deeplink url	am in deeplink url	Mandatory
splitDetails	Not Required	Not Applicable	split in deeplink url	split in deeplink url	Not Applicable
upiRequestId	Mandatory	Mandatory	tid in deeplink url	tid in deeplink url	Mandatory
remarks	Mandatory	Mandatory	tn in deeplink url	tn in deeplink url	Mandatory
refUrl	Not Required	Not Required	url in deeplink url	url in deeplink url	Not Required
refCategory	Not Required	Not Required	category in deeplink url	category in deeplink url	Not Required
currency	INR	INR	cu in deeplink url	cu in deeplink url	INR
mcc	Mandatory	Not Required	mc in deeplink url	mc pin deeplink url	Not Required
transactionReference	Not Required	Not Required	tr in deeplink url	tr in deeplink url	Not Required
payeeBankAccountUniqueId	Not Required	Not Required	Not Required	Not Required	Mandatory
initiatingChannel	Not Required	Optional	Not Required	Not Required	Not Required
location	Optional	Optional	Optional	Optional	Optional
geocode	Optional	Optional	Optional	Optional	Optional
mid	Optional	Optional	Optional	Optional	Optional
msid	Optional	Optional	Optional	Optional	Optional
mtid	Optional	Optional	Optional	Optional	Optional
mSubCode	Optional	Optional	Optional	Optional	Optional
mType	Optional	Optional	Optional	Optional	Optional
mGenre	Optional	Optional	Optional	Optional	Optional
mOnBoardingType	Optional	Optional	Optional	Optional	Optional
mRegId	Optional	Optional	Optional	Optional	Optional
mPinCode	Optional	Optional	Optional	Optional	Optional
mTier	Optional	Optional	Optional	Optional	Optional
mLoc	Optional	Optional	Optional	Optional	Optional
mInstCode	Optional	Optional	Optional	Optional	Optional
mBrand	Optional	Optional	Optional	Optional	Optional
mLegal	Optional	Optional	Optional	Optional	Optional
mFranchise	Optional	Optional	Optional	Optional	Optional
mOwnershipType	Optional	Optional	Optional	Optional	Optional

Note

1. Validity of a payeeVpa can be verified using the Verify VPA API.
2. SERVICE_UNAVAILABLE_{entity}_{error} will be returned in case of NPCI timeout or deemed transactions.
3. splitDetails enables Tips and Convenience Fee feature, encompassing details of customer-selected supplementary expenses.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
deviceFingerPrint	Device fingerprint of the customer	String
merchantRequestId	Merchant generated id for the transaction	35 characters alphanumeric
payerVpa	VPA of the customer to be used for payment	something@handle
payeeVpa	Vpa of the payee to whom money is being sent	something@handle
payeeName optional	Name of the payee	String as returned in the Verify VPA API
amount	Amount for transaction	Numeric string with two decimals
splitDetails optional	Supplementary Expenses of the transaction	List of JSON with name (supplementary expense) in string and value (amount) as numeric string with two decimals
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
bankAccountUniqueId	Unique id for the payer selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call
payeeBankAccountUniqueId optional	Unique id for the payee selected bank account for self transfer	bankAccountUniqueId in the response of Fetch Accounts api call
credBlock	Encrypted credblock containing user mpin	As returned by Common Library
remarks	Any transaction summary	50 characters alphanumeric with space and hyphen
currency	Currency code	String - INR
transactionType	Type of payment	P2M_PAY, P2P_PAY, INTENT_PAY or SCAN_PAY
upiNumbers optional	upiNumber of payee if transaction is done using UPI Number	8-10 digit Number
transactionReference optional	Transaction reference id	String
refUrl optional	Reference url for the intent transaction	String
refCategory optional	Details for refUrl, whether it is 01 (Advertisement), 02(Invoice)	String
mcc optional	Merchant category code	String
initiationMode optional	Defines the initiation mode of the transaction	Initiation Modes
purpose optional	Defines the purpose code of the transaction	Purpose Codes
mPinCode optional	Pincode of the merchants for ICCW transactions	String
initiatingChannel optional	Defines the Device Type used in Transaction.	Initiating Channels
upiNumber optional	upiNumber of payee if transaction is done using UPI Number	String (8-10 digit Number)
udfParameters optional	Stringified JSON for udf parameters	JSON string
packageName optional	Package name of the UPI application	String
location optional	Location of the payer	String with a maximum length of 40.
geocode optional	Geocode of the payer	Numeric string
mid optional	Merchant identifier	Alphanumeric string. Maximum length is 20.
msid optional	Sub-Merchant identifier	Alphanumeric string. Maximum length is 20.
mtid optional	Merchant generated id for the transaction	35 characters alphanumeric
mSubCode optional	This is the MCC code of the Merchant	String
mType optional	Merchant's type, Ex:SMALL, LARGE	String
mGenre optional	Genre of sub-merchant	ONLINE, OFFLINE.
mOnBoardingType optional	Onboarding type of sub-merchant	BANK, AGGREGATOR
mRegId optional	Identifier for this QR scan instance, generated by the merchant/network	String
mPinCode optional	Zip code or pin code or postal code of the merchant	String
mTier optional	Denotes the tier of the city on the basis of the population Ex: TIER1, TIER2, TIER3	String
mLoc optional	Location of the Country	String
mInstCode optional	This is w.r.t to end Aggregator identification by the International Network	String
mBrand optional	Brand name of the Merchant	String
mLegal optional	Legal name of the merchant	String
mFranchise optional	Franchise agent name	String
mOwnershipType optional	Type of Ownership, Ex: PROPRIETARY, PARTNERSHIP, PRIVATE, PUBLIC, OTHERS	String

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantRequestId	Merchant generated id for the transaction	As passed in the request
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
payerVpa	Customer vpa used for the payment	As passed in the request
payeeMcc	MCC for the payee	String
payeeMerchantCustomerId optional	Merchant generated unique id for customer who received the payment. Only if it is an onus P2P transaction.	String
payeeName optional	Name of the upi user who received the payment. Only if payment is done to a non A/C+IFSC vpa.	String
payeeVpa	Vpa of the upi user who received the payment	something@handle
refUrl	Reference url for the intent transaction	String
bankAccountUniqueId	Unique id for the selected bank account	As passed in the request
bankCode	Bank code of the account which was used	Valid bank IIN
maskedAccountNumber	Masked account number of the account which was used	XXXX123456
amount	Amount for the payment	As passed in the request
splitDetails optional	Supplementary Expenses of the transaction	As passed in the request
transactionType	Type of payment	As sent in request
transactionTimestamp	Timestamp of when the transaction was attempted	YYYY-MM-DDTHH:MM:SS+05:30
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayReferenceId	Reference id returned by the gateway	String
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
gatewayPayerResponseCode optional	Response code returned by gateway	String
gatewayPayeeResponseCode optional	Response code returned by gateway	String
gatewayPayerReversalResponseCode optional	Response code returned by gateway	String
gatewayPayeeReversalResponseCode optional	Response code returned by gateway	String
riskScore optional	RiskScore shared by NPCI or Bank	String
udfParameters optional	Udf parameters as passed in the request	JSON string

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Payment Success.
Z9	FAILURE	Insufficient funds in customer (remitter) account.
Z8	FAILURE	Per transaction limit exceeded as set by remitting member.
Z7	FAILURE	Transaction frequency limit exceeded as set by remitting member.
Z6	FAILURE	Number of pin tries exceeded.
ZM	FAILURE	Invalid mpin.
Else	FAILURE	Any other reason.

Additional Error Codes

responseCode	Meaning
DUPLICATE_REQUEST	Duplicate merchantRequestId or upiRequestId used for the transaction

ICCW (Interoperable Card-less ATM Cash Withdrawal using UPI) - Send Money changes

This service shall facilitate customers who are live on UPI, to withdraw cash from ATMs (enabled for UPI-ATM (ICCW)) without using their card. ICCW transaction withdrawal is supported with initMode(18), purpose code (12,13) and mcc(6013) as received in the QR. mPinCode is required to be passed for ICCW Transactions. The transaction limit shall be applicable as per the existing NFS ATM transaction i.e. upto ₹.10,000/- per transaction. For ICCW, Issuer bank should support version 2.91.

Request Money

curl -L -X POST '{{host}}/api/n2/merchants/transactions/requestMoney'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "merchantRequestId": "TXN1234567",
  "payeeVpa": "customer@handle",
  "payerVpa": "payer@xyz",
  "payerName": "John Doe",
  "collectRequestExpiryMinutes": "30",
  "amount:" "2.00",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
  "remarks": "Requesting money for bill",
  "currency": "INR",
  "initiationMode": "00",
  "purpose": "00",
  "udfParameters": "{}",
  "packageName": "in.amazon.mShop.android.shopping"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "merchantRequestId": "TXN1234567",
    "customerMobileNumber": "919988776655",
    "amount": "2.00",
    "expiryTimestamp": "2017-06-09T18:27:49+05:30",
    "payeeVpa": "customervpa@bank",
    "payeeMcc": "0000",
    "payerVpa": "payer@xyz",
    "payerName": "John Doe",
    "refUrl": "https://www.abcxyz.com/",
    "remarks": "This is remarks",
    "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
    "bankCode": "123456",
    "maskedAccountNumber": "XXXX123456",
    "amount": "2.00",
    "transactionTimestamp": "2017-06-09T17:57:49+05:30",
    "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
    "gatewayReferenceId": "809323430413",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Collect request sent successfully"
  },
  "udfParameters": "{}"
}

This api can be used to request money from another VPA.

Note

1. Validity of a payerVpa can be verified using the Verify VPA API.
2. SERVICE_UNAVAILABLE_{entity}_{error} will be returned in case of NPCI timeout.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
deviceFingerPrint	Device fingerprint of the customer	String
merchantRequestId	Merchant generated id for the transaction	35 characters alphanumeric
payeeVpa	VPA of the customer to be used for payment	something@handle
payerVpa	Vpa of the payer to which collect request is to be sent	something@handle
payerName	Name of the payer	String as returned in the Verify VPA API
collectRequestExpiryMinutes	Minutes for which the collect request is valid	A numeric string between 1 to 64800 (both inclusive)
amount	Amount for transaction	Numeric string with two decimals
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
bankAccountUniqueId	Unique id for the selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call
remarks	Any transaction summary	50 characters alphanumeric with space and hyphen
currency	Currency code	String - INR
upiNumber optional	upiNumber of payer if transaction is done using UPI Number	String (8-10 digit Number)
initiationMode optional	Defines the initiation mode of the transaction	Initiation Modes
purpose optional	Defines the purpose code of the transaction	Purpose Codes
udfParameters optional	Stringified JSON for udf parameters	JSON string
packageName optional	Package name of the UPI application	String

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
merchantRequestId	Merchant generated id for the transaction	As passed in the request
customerMobileNumber	Customer mobile number	12 digits mobile number string
amount	Amount for transaction	As passed in the request
expiryTimestamp	Timestamp of when the collect request will expire	YYYY-MM-DDTHH:MM:SS+05:30
payeeVpa	Customer vpa used for the payment	As passed in the request
payeeMcc	MCC for the payee	String
payerVpa	Vpa of the UPI user who received the collect request	something@handle
payerName	Name of the payer to whom collect request was sent	String
refUrl	Reference url for the intent transaction	String
remarks	Remarks sent by customer for the collect request	String
bankAccountUniqueId	Unique id for the selected bank account	As passed in the request
bankCode	Bank code of the account which was used	Valid bank IIN
maskedAccountNumber	Masked account number of the account which was used	XXXX123456
transactionTimestamp	Timestamp of when the transaction was attempted	YYYY-MM-DDTHH:MM:SS+05:30
gatewayTransactionId	Transaction id returned by gateway	String
gatewayReferenceId	Reference id returned by the gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
udfParameters optional	Udf parameters as passed in the request	JSON string

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Collect sent successfully.
Else	FAILURE	Sending collect request failed.

Additional Error Codes

responseCode	Meaning
DUPLICATE_REQUEST	Duplicate merchantRequestId or upiRequestId used for the transaction

List Pending Collect Requests

curl -L -X POST '{{host}}/api/n2/merchants/transactions/listPending'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "919988776655",
    "pendingTransactions": [{
      "payerVpa": "vpa@bank",
      "payeeVpa": "swiggy@upi",
      "payeeName": "Swiggy",
      "isVerifiedPayee": "true",
      "isMarkedSpam": "true",
      "amount": "100.00",
      "payeeMcc": "1520",
      "transactionTimestamp": "2017-06-09T07:46:45+00:00",
      "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
      "gatewayReferenceId": "809323430413",
      "remarks": "REMARKS",
      "expiry": "2017-06-09T10:46:45+00:00",
      "refUrl": "https://www.asd.com",
      "refCategory": "02",
      "collectType": "MANDATE",
      "seqNumber": "2"
    }]
  },
  "udfParameters": "{}"
}

This api returns list of all the pending collect requests for the customer.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
payerVpa	Vpa of the customer/payer to which collect was sent	something@handle
payeeVpa	Customer vpa used for the payment	As passed in the request
payeeName	Name of the payee by whom collect was sent	Some name
isVerifiedPayee	Flag if the payee is a verified vpa	String
isMarkedSpam	Flag if the payee is marked as spam	String
amount	Amount for which transaction is requested	123.00
payeeMcc	Merchant Category Code of the payee vpa	4101
transactionTimestamp	Timestamp of when the transaction was attempted	YYYY-MM-DDTHH:MM:SS+05:30
gatewayTransactionId	Transaction id returned by gateway	String
gatewayReferenceId	Reference id returned by the gateway	String
remarks	Transaction remarks sent by payee	String
expiry	Timestamp of expiry of request	YYYY-MM-DDTHH:MM:SS+05:30
refUrl optional	Invoice as sent by merchant or reference to the transaction in the form of url	String
refCategory optional	Details for refUrl, whether it is 01 (Advertisement), 02(Invoice)	String
udfParameters optional	Udf parameters as passed in the request	JSON string
collectType	Differentiates between a transaction collect request (TRANSACTION) or a mandate execution collect request (MANDATE).	TRANSACTION or MANDATE
seqNumber optional	Denotes the recurring cycle of mandate execution. Will be received only during mandate executions.	String

Approve/Decline a Collect Request

curl -L -X POST '{{host}}/api/n2/merchants/transactions/collect'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "merchantRequestId": "TXN1234567",
  "payerVpa": "customer@handle",
  "payeeVpa": "payee@xyz",
  "payeeName": "John Doe",
  "amount:" "2.00",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "collectType": "TRANSACTION",
  "requestType": "APPROVE",
  "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
  "credBlock": "{\"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|j+dtxs...1ca1o0CrjnUw==\",\"code\":\"NPCI\"}}}",
  "currency": "INR",
  "location": "123 Fake Street, Anytown, Somecountry",
  "geocode": "88.888888, 88.888888",
  "udfParameters": "{}",
  "packageName": "in.amazon.mShop.android.shopping"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "merchantRequestId": "TXN1234567",
    "customerMobileNumber": "919988776655",
    "payerVpa": "customer@handle",
    "payeeMcc": "0000",
    "payeeMerchantCustomerId": "DEMO-CUST-5678",
    "payeeVpa": "payee@xyz",
    "payeeName": "John Doe",
    "refUrl": "https://www.abcxyz.com/",
    "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
    "bankCode": "123456",
    "maskedAccountNumber": "XXXX123456",
    "amount": "2.00",
    "transactionTimestamp": "2017-06-09T17:57:49+05:30",
    "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
    "gatewayReferenceId": "809323430413",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Your transaction is successful",
    "gatewayPayerResponseCode": "00",
    "gatewayPayeeResponseCode": "00",
    "gatewayPayerReversalResponseCode": "00",
    "gatewayPayeeReversalResponseCode": "00",
    "requestType": "APPROVE",
    "collectType": "TRANSACTION",
    "seqNumber": "1",
    "riskScore": "00000"
  },
  "udfParameters": "{}"
}

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 parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
deviceFingerPrint	Device fingerprint of the customer	String
merchantRequestId	Merchant generated id for the transaction	35 characters alphanumeric
payerVpa	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	Vpa of the payee to whom money is being sent	something@handle
payeeName optional	Name of the payee	String
amount	Amount for transaction	Numeric string with two decimals
upiRequestId	Unique id sent to UPI switch for the transaction	35 character alphanumeric
collectType optional	Differentiates between a transaction collect request (TRANSACTION) or a mandate execution collect request (MANDATE).	TRANSACTION or MANDATE
requestType	Action to be taken on the collect request	APPROVE or DECLINE
bankAccountUniqueId	Unique id for the selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call
credBlock optional	Encrypted credblock containing user mpin	As returned by Common Library
currency	Currency code	String - INR
udfParameters optional	Stringified JSON for udf parameters	JSON string
packageName optional	Package name of the UPI application	String
location optional	Location of the payer	String with a maximum length of 40.
geocode optional	Geocode of the payer	Numeric string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantRequestId	Merchant generated request id as passed in the collect request	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
payerVpa	If collectType is null or TRANSACTION, Vpa of the customer who received the collect request and if collectType is MANDATE, umn of the mandate.
requestType	Action to be taken on the collect request. As passed in the request body	APPROVE or DECLINE
collectType optional	Differentiates between a transaction collect request (TRANSACTION) or a mandate execution collect request (MANDATE).	TRANSACTION or MANDATE
seqNumber optional	Denotes the recurring cycle of mandate execution. Will be received only during mandate executions.	String
payeeMcc	MCC for the payee	String
payeeMerchantCustomerId optional	Merchant generated unique id for customer who received the payment. Only if it is an onus P2P transaction.	String
payeeName	Name of the upi user who received the payment. Only if payment is done to a non A/C+IFSC vpa.
payeeVpa	Vpa of the upi user who received the payment	As passed in the request
refUrl	Reference url for the intent transaction	String
bankAccountUniqueId optional	Unique id for the selected bank account	As passed in the request
bankCode optional	Bank code of the account which was used	Valid bank IIN
maskedAccountNumber optional	Masked account number of the account which was used	XXXX123456
amount	Amount for the payment	As passed in the request
transactionTimestamp	Timestamp of when the transaction was attempted	YYYY-MM-DDTHH:MM:SS+05:30
gatewayTransactionId	Transaction id returned by gateway	String
gatewayReferenceId	Reference id returned by the gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, DECLINED, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
gatewayPayerResponseCode optional	Response code returned by gateway	String
gatewayPayeeResponseCode optional	Response code returned by gateway	String
gatewayPayerReversalResponseCode optional	Response code returned by gateway	String
gatewayPayeeReversalResponseCode optional	Response code returned by gateway	String
riskScore optional	RiskScore shared by NPCI or Bank	String
udfParameters optional	Udf parameters as passed in the request	JSON string

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Collect request approved successfully.
ZA	DECLINED	Collect request declined successfully.
Z9	FAILURE	Insufficient funds in customer (remitter) account.
Z8	FAILURE	Per transaction limit exceeded as set by remitting member.
Z7	FAILURE	Transaction frequency limit exceeded as set by remitting member.
Z6	FAILURE	Number of pin tries exceeded.
ZM	FAILURE	Invalid mpin.
Else	FAILURE	Any other reason.

Transactions Status 360

curl -L -X POST '{{host}}/api/n2/merchants/transactions/status360'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-sub-merchant-id': 'SUBMERCHANT', \
  'x-sub-merchant-channel-id': 'SUBMERCHANTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "transactionType":"CUSTOMER_CREDITED_VIA_PAY",
  "transactionTimestamp": "2016-11-25T00:00:00+05:30",
  "checkWithUdir": "true",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "amount": "100.00",
    "splitDetails": [{"name": "TIPS", "value": "1.00"}, {"name": "CCONFEE", "value": "1.00"}, {"name": "PCONFEE", "value": "1.00"}],
    "bankAccountUniqueId" : "fb96f8b2b1ab0c070d0d894......",
    "bankCode" : "123456",
    "customResponse": "{}",
    "gatewayPayerResponseCode": "00",
    "gatewayPayeeResponseCode": "00",
    "gatewayPayerReversalResponseCode": "00",
    "gatewayPayeeReversalResponseCode": "00",
    "gatewayReferenceId": "806115044725",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Transaction is approved",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayTransactionId": "XYZd0c077f39c454979...",
    "maskedAccountNumber" : "XXXX123456",
    "merchantCustomerId": "DEMO-CUST-1234",
    "merchantId": "DEMOUAT01",
    "orgMandateId": "APL71f7d43bdf64d72d187317de123",
    "payeeMcc": "4121",
    "payeeMerchantCustomerId": "DEMO-CUST-1234",
    "payeeMobileNumber" : "919812388554",
    "payeeVpa" : "customer1@abc",
    "payerMerchantCustomerId": "DEMO-CUST-5678",
    "payerName": "Customer Name",
    "payerVpa": "customer@xyz",
    "refUrl": "https://www.abcxyz.com/",
    "riskScore": "00979",
    "seqNumber": "1",
    "transactionTimestamp": "2016-11-25T00:00:00+05:30",
    "type": "CUSTOMER_CREDITED_VIA_PAY",
    "umn": "ABZv1f7daa3bf64729af61b0f6d95b8dd@bankbiz"
  },
  "udfParameters":"{}"
}

This api will be used for getting the status for both P2P and P2M transaction and the response will be similar to callback response for the transactionType passed in the request.

Below are the possible values for transactionType,

transactionType	Callback Type
MERCHANT_CREDITED_VIA_PAY	Incoming Money to Merchant - Pay
CUSTOMER_CREDITED_VIA_PAY	Incoming Money to Customer - Pay
MERCHANT_CREDITED_VIA_COLLECT	Incoming Money to Merchant - Collect Status
CUSTOMER_CREDITED_VIA_COLLECT	Incoming Money to Customer - Collect Status
CUSTOMER_DEBITED_FOR_MERCHANT_VIA_PAY	Outgoing Money from a Customer
CUSTOMER_DEBITED_VIA_PAY	Outgoing Money from a Customer
CUSTOMER_DEBITED_FOR_MERCHANT_VIA_COLLECT	Outgoing Money from a Customer
CUSTOMER_DEBITED_VIA_COLLECT	Outgoing Money from a Customer
COLLECT_REQUEST_SENT	Outgoing Collect Request from Customer

Note: Merchant can pass an optional parameter transactionTimestamp. Passing this parameter will help PSP to optimize the status retrieval for the transaction.

Request parameters

Parameter	Description	Constraints
upiRequestId	Request id of the transaction whose status is to be checked.	35 character alphanumeric unique id.
transactionType	Type of transaction	String
transactionTimestamp optional	Timestamp of the upiRequestId as returned by PSP	(YYYY-MM-DDTHH:MM:SS+05:30)
checkWithUdir optional	Boolean flag for UDIR status check	String
udfParameters optional	Stringified JSON for udf parameters	JSON String

Response

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
payload	Callback data in appropriate format for the transactionType passed in the request. Refer Transaction API Callbacks section for more details.	JSON
udfParameters optional	Udf parameters as passed in the request.	JSON String

Additional Error Codes

responseCode	Meaning
REQUEST_NOT_FOUND	upiRequestId is not valid

Raise a Query

curl -L -X POST '{{host}}/api/n2/merchants/transactions/query/raise'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "upiResponseId": "809323430413",
  "queryComment": "Amount not credited",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "919988776655",
    "queryReferenceId": "QUERY123",
    "queryComment": "Amount not credited",
    "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
    "gatewayReferenceId": "809323430413",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Query raised successfully"
  },
  "udfParameters": "{}"
}

This api can be used to raise a query on a deemed transaction. The query should be raised 2 days after the transaction attempt.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
upiRequestId	Unique id sent to UPI switch for the transaction	35 character alphanumeric
upiResponseId	RRN of the transaction on which query is raised	12 digit numeric string
queryComment optional	A comment specifying the query regarding the issue	0-255 characters alphanumeric
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
queryReferenceId	PSP generated unique id for the query	QUERY123
queryComment optional	The query description as sent in the request	0-255 characters alphanumeric
gatewayTransactionId	upiRequestId as passed in request	String
gatewayReferenceId	upiResponseId as passed in request	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
udfParameters optional	Udf parameters as passed in the request	JSON string

gatewayResponseCode	gatewayResponseStatus	gatewayResponseMessage
00	SUCCESS	Query raised successfully.
Else	FAILURE	Query was not raised.

Additional Error Codes

responseCode	Meaning
INVALID_TRANSACTION_ID	upiRequestId passed on which query is to be raised is not valid
DUPLICATE_REQUEST	Query already raised for given upiRequestId

Query Status

curl -L -X POST '{{host}}/api/n2/merchants/transactions/query/status'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "upiResponseId": "809323430413",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "919988776655",
    "queryReferenceId": "QUERY123",
    "queryComment": "Amount not credited",
    "queryClosingTimestamp": "2016-11-25T00:00:00+05:30",
    "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
    "gatewayReferenceId": "809323430413",
    "gatewayResponseStatus": "CLOSED",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Query is closed"
  },
  "udfParameters": "{}"
}

This api can be used to check the status of a previously raised query.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
upiRequestId	UPI request id of the transaction on which the query was raised	35 character alphanumeric
upiResponseId	RRN of the transaction on which query is raised	12 digit numeric string
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
queryReferenceId	PSP generated unique id for the query	QUERY123
queryComment optional	The query description as sent in the request	0-255 characters alphanumeric
queryClosingTimestamp optional	Timestamp of when the query was closed	YYYY-MM-DDTHH:MM:SS+05:30
gatewayTransactionId	upiRequestId as passed in request	String
gatewayReferenceId	upiResponseId as passed in request	String
gatewayResponseStatus	Response status returend by gateway	OPEN, CLOSED
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
udfParameters optional	Udf parameters as passed in the request	JSON string

gatewayResponseCode	gatewayResponseStatus	gatewayResponseMessage	Original Transaction Status
01	OPEN	Your query is still open.	-
102	CLOSED	Your account has already been credited with Rs {amount}. Please check your balance.	Failure
103	CLOSED	Your account has already been credited with Rs {amount}. Please check your balance.	Failure
104	CLOSED	The transaction has failed, please try again after some time.	Failure
105	CLOSED	Beneficiary account has already been credited.	Success
106	CLOSED	Funds have been reversed to your bank account. Your bank shall credit in 5 working days.	Failure
107	CLOSED	Beneficiary account has already been credited.	Success
108	CLOSED	Beneficiary account has already been credited.	Success
109	CLOSED	Funds have been reversed to your bank account. Your bank shall credit in 5 working days.	Failure
144	CLOSED	Your account was not debited.	Failure
Else	CLOSED	Incase any other gatewayResponseCode is returned by TSP. Consider the transaction status as Failure.	Failure

Block and Spam a VPA

curl -L -X POST '{{host}}/api/n2/merchants/vpas/blockAndSpam'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "payeeVpa": "ayx@handle",
  "requestType": "TRANSACTION",
  "shouldBlock": "true",
  "shouldSpam": "false",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "MERCHANT",
    "merchantChannelId": "MERCHANTAPP",
    "merchantCustomerId": "MERCHANTCUST123",
    "customerMobileNumber": "919988776655",
    "payeeVpa": "ayx@handle",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Vpa blocked/spammed successfully"
  },
  "udfParameters": "{}"
}

The api can be used to block or mark a collect request as spam.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
upiRequestId	UPI request id of the collect request if requestType is TRANSACTION or mandateRequestId of the approve mandate request if requestType is MANDATE.	35 character alphanumeric
payeeVpa	Vpa that has to be blocked/spammed	String
requestType	Denotes the request type for which block and spam vpa is triggered	TRANSACTION, MANDATE
shouldBlock	Boolean flag if the payee VPA has to be blocked	String
shouldSpam	Boolean flag if the payee VPA has to be marked as spam	String
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
payeeVpa	Vpa that is blocked/spammed for the customer	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by the gateway for blocking/spamming the VPA	String
gatewayResponseMessage	Response message returned by the gateway for blocking/spamming the VPA	String
udfParameters optional	Udf parameters as passed in the request	JSON string

gatewayResponseCode	gatewayResponseStatus	gatewayResponseMessage
00	SUCCESS	Vpa blocked/spammed successfully.
Else	FAILURE	Vpa block/spam falied.

Unblock a VPA

curl -L -X POST '{{host}}/api/n2/merchants/vpas/unblock'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "payeeVpa": "ayx@handle",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "MERCHANT",
    "merchantChannelId": "MERCHANTAPP",
    "merchantCustomerId": "MERCHANTCUST123",
    "customerMobileNumber": "919988776655",
    "payeeVpa": "ayx@handle",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Vpa unblocked successfully"
  },
  "udfParameters": "{}"
}

This api will be used to unblock a vpa which was blocked earlier by the customer.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
payeeVpa	Vpa that is to be unblocked	String
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
payeeVpa	Vpa that is unblocked for the customer	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by the gateway for unblocking the VPA	String
gatewayResponseMessage	Response message returned by the gateway for unblocking the VPA	String
udfParameters optional	Udf parameters as passed in the request	JSON string

gatewayResponseCode	Description
00	Vpa unblocked successfully.
Else	Vpa unblock falied.

List Blocked VPAs

curl -L -X POST '{{host}}/api/n2/merchants/vpas/block/list'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "limit": 10,
  "offset": 0,
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "MERCHANT",
    "merchantChannelId": "MERCHANTAPP",
    "merchantCustomerId": "MERCHANTCUST123",
    "customerMobileNumber": "919988776655",
    "blockedVpas": [{
      "payeeVpa": "abc@handle",
      "name": "SOMYA DIXIT",
      "blockedAt": "2017-06-09T10:46:45+05:30",
    }]
  },
  "udfParameters": "{}"
}

This api will be used to list all the VPAs that were blocked so far by the customer.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
limit	Maximum number of rows to be returned. Used for pagination	Number > 0
offset	Offset for rows to be returned. Used for pagination	Number >= 0
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
payeeVpa	Vpa that is blocked for the customer	String
name	Name associated with the vpa that is blocked for the customer	String
blockedAt	Timestamp of when the vpa was blocked by the customer.	YYYY-MM-DDTHH:MM:SS+05:30
udfParameters optional	Udf parameters as passed in the request	JSON string

List Transactions

This API will be used to list all the transactions for a submerchant and parent merchant. Limit no of transactions starting from offset record between startTimestamp and endTimestamp will be returned in the response.

curl -L -X POST '{{host}}/api/n2/merchants/transactions/list'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-api-version': '6' \
  'x-merchant-id': 'MERCHANT', \
  'x-merchant-channel-id': 'MERCHANTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "startTimestamp: "2023-05-04T16:37:31+05:30",
  "endTimestamp": "2023-05-05T16:37:31+05:30",
  "limit": 10,
  "offset": 0,
  "callbackStatus": "PENDING",
  "status": ["SUCCESS"],
  "requestType": "SUBMERCHANT",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload": {
        "merchantChannelId": "MERCHANTAPP",
        "merchantId": "MERCHANT",
        "txnList": [
            {
                "amount": "9.00",
                "merchantRequestId": "NHSa88ad0105fb349f2a177c24",
                "payeeName": "ABC",
                "refUrl": "https://www.abcxyz.com/",
                "gatewayResponseMessage": "Your transaction is successful",
                "gatewayResponseStatus": "SUCCESS",
                "payerVpa": "abc0@xyz",
                "payerName": "Venkat",
                "payerAccBin": "1234567890",
                "payerAccType": "CREDIT",
                "gatewayResponseCode": "00",
                "gatewayReferenceId": "348936720789",
                "gatewayTransactionId": "NHSec7c037",
                "payeeVpa": "efg-1@yza",
                "initiationMode": "00"
                "transactionTimestamp": "2023-05-04T16:38:31+05:30",
                "type": "PAY",
                "remarks": "hi",
                "payerAccountHash": "301ad1eaa5279b50ca3ba2dee854747cd47d4eae7939a249c994bec43c443fda",
                "subMerchantId" : "SUBMERCHANT1",
                "subMerchantChannelId": "SUBMERCHANTAPP1"
            },
            {
                "amount": "9.00",
                "merchantRequestId": "NHSa88ad0105fb349f2a177c24",
                "payeeName": "ABC",
                "refUrl": "https://www.abcxyz.com/",
                "gatewayResponseMessage": "Your transaction is successful",
                "gatewayResponseStatus": "SUCCESS",
                "payerVpa": "abc0@xyz",
                "payerName": "Venkat",
                "payerAccBin": "1234567890",
                "payerAccType": "CREDIT",
                "gatewayResponseCode": "00",
                "gatewayReferenceId": "348936720789",
                "gatewayTransactionId": "NHSec7c037",
                "payeeVpa": "efg-1@xyz",
                "initiationMode": "00"
                "transactionTimestamp": "2023-05-04T16:38:31+05:30",
                "type": "PAY",
                "remarks": "hi",
                "payerAccountHash": "301ad1eaa5279b50ca3ba2dee854747cd47d4eae7939a249c994bec43c443fda",
                "subMerchantId" : "SUBMERCHANT2",
                "subMerchantChannelId": "SUBMERCHANTAPP2"
            }
        ]
    },
    "udfParameters": "{}"
}

Request parameters

Parameter	Description	Values
startTimestamp*	Start timestamp to be considered for querying Transactions	String in format: YYYY-MM-DDTHH:MM:SS+05:30
endTimestamp*	End timestamp to be considered for querying Transactions	String in format: YYYY-MM-DDTHH:MM:SS+05:30
limit*	Maximum number of rows to be returned	Integer (1 to 100)
offset*	Offset for rows to be returned	Integer (≥ 0)
callbackStatus	Status of callback to be fetched	SUCCESS, PENDING, ALL
status	List of status of transactions to be fetched	[SUCCESS, FAILURE, PENDING]
requestType	Whether to fetch transactions for parent, sub, or both types of merchants	PARENTMERCHANT, SUBMERCHANT, BOTH
udfParameters	JSON for UDF (user-defined) parameters	JSON object

Response paramenters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE, PENDING
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique ID for the merchant as passed in request headers	String
merchantChannelId	Unique ID for the merchant channel as passed in request headers	String
subMerchantChannelId	Unique ID for the submerchant channel via which request is made	As passed in request
subMerchantId	Unique ID for submerchant	As passed in request
amount	Amount for the transaction	Decimal (e.g., 100.00)
merchantRequestId	Merchant-generated request ID	35 character alphanumeric
payeeName	Name of the payee	String
refUrl	Invoice or reference URL for the transaction	String
gatewayResponseMessage	Response message returned by gateway	String
payerVpa	VPA of payer	String
payerName	Name of payer	String
payerAccBin (Conditional)	Credit card BIN (only if payerAccType = CREDIT)	String
payerAccType	Payer account type	String
gatewayResponseCode	Response code returned by gateway	Refer gateway response code table
gatewayReferenceId	Reference ID returned by the gateway	String
gatewayTransactionId	UPI request ID returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
payeeVpa	VPA of payee	String
initiationMode	Initiation mode of the transaction	E.g., 00 (Default), 04 (Intent)
transactionTimestamp	Timestamp when the transaction was triggered	YYYY-MM-DDTHH:MM:SS+05:30
type	Type of transaction	Pay, Collect
remarks	Remarks sent by merchant for the transaction	String
umn (Conditional)	VPA used for execution of mandate (for mandate transactions only)	String
udfParameters (Optional)	UDF parameters as passed in request	JSON string

Merchant Transaction APIs

Merchant Web Collect 360

curl -L -X POST '{{host}}/api/n2/merchants/transactions/webCollect360'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-sub-merchant-id': 'SUBMERCHANT', \
  'x-sub-merchant-channel-id': 'SUBMERCHANTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantRequestId": "ord50894574",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "payerVpa": "8123715658@upi",
  "payerName": "John Doe",
  "payeeVpa": "merchant@handle",
  "collectRequestExpiryMinutes": "10",
  "amount": "20.00",
  "purpose": "00",
  "initiationMode": "00",
  "refUrl": "https://www.abcxyz.com",
  "remarks": "This is remarks",
  "refCategory": "02",
  "platform" : "IOS",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantRequestId": "ord50894574",
    "amount": "20.00",
    "payerVpa": "8123715658@upi",
    "payerName": "John Doe",
    "payeeVpa": "merchant@handle",
    "payeeMcc": "4101",
    "refUrl": "https://www.abcxyz.com/",
    "remarks": "This is remarks",
    "transactionTimestamp": "2017-06-09T17:57:49+05:30",
    "expiryTimestamp": "2017-06-09T18:07:49+05:30",
    "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
    "gatewayReferenceId": "809323430413",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Collect request sent successfully"
  },
  "udfParameters": "{}"
}

This API will be used to send collect notification to respective PSP App of the user.

Note

1. Validity of a payerVpa can be verified using the Verify VPA API.
2. The payeeVpa should be a valid PSP generated vpa for the merchant.
3. SERVICE_UNAVAILABLE_{entity}_{error} will be returned in case of NPCI timeout.
4. If refUrl is passed in request, refCategory becomes essential for the API to work. So it's either both as combination or none.

Request parameters

Parameter	Description	Constraints
merchantRequestId	Request id for the collect request	35 character alphanumeric unique id.
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
payerVpa	Vpa on which collect request should be triggered	something@handle
payerName	Name of the payer	String as returned in the Verify VPA API
payeeVpa	VPA of the merchant to be used for payment	something@handle
collectRequestExpiryMinutes	Minutes for which request is valid.	A number between 1 to 64800, both inclusive, in String format
amount	Amount of collect request to be sent	Amount in two decimals. Decimals are mandatory.
remarks	Any transaction summary	50 characters alphanumeric with space and hyphen
purpose optional	Defines the purpose code of the transaction	Refer Request Structure section
initiationMode optional	Defines the initiation mode of the transaction	Refer Request Structure section
refUrl optional	Invoice as sent by merchant in the form of url	String
refCategory optional	Details for refUrl, whether it is 01(advertisement), 02(invoice)	String
udfParameters	Json for udf parameters	JSON
platform	Platform from which request is initiated	WEB, ANDROID,IOS

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantRequestId	Request id for the collect request	As passed in request.
amount	Amount for transaction	As passed in the request
payerVpa	Vpa on which collect request was triggered	As passed in request.
payerName	Name of the payer to whom collect request was sent	String
payeeVpa	VPA of the merchant to be used for payment	As passed in request.
payeeMcc	Merchant Category Code of the payee merchant.	4101
refUrl	Invoice as sent by merchant or reference to the transaction in the form of url.	String
remarks	Remarks sent by merchant for the collect request	String
transactionTimestamp	Timestamp of when collect request was triggered	YYYY-MM-DDTHH:MM:SS+05:30
expiryTimestamp	Timestamp of when the collect request will expire	YYYY-MM-DDTHH:MM:SS+05:30
gatewayTransactionId	UPI request id returned by gateway for the transaction.	String
gatewayReferenceId	Reference id returned by the gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway for the transaction.	00, Any valid NPCI error code
gatewayResponseMessage	Response message returned by gateway for the transaction.	String
udfParameters optional	Udf parameters as passed in the request	JSON string

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Collect sent successfully.
Else	FAILURE	Sending collect request failed.

Additional Error Codes

responseCode	Meaning
DUPLICATE_REQUEST	Duplicate merchantRequestId or upiRequestId used for the transaction

Merchant Register Intent

curl -L -X POST '{{host}}/api/n2/merchants/transactions/registerIntent'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-sub-merchant-id': 'SUBMERCHANT', \
  'x-sub-merchant-channel-id': 'SUBMERCHANTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantRequestId": "ord50894574",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "amount": "2.00",
  "splitDetails": [{"name": "CCONFEE", "value": "1.00"}, {"name": "PCONFEE", "value": "1.00"}],
  "enableTips": true,
  "intentRequestExpiryMinutes", "10",
  "remarks": "Payment for order",
  "refUrl": "www.xyz.com",
  "refCategory": "01",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantRequestId": "ord50894574",
    "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
    "orderId": "ord50894574",
    "payeeVpa": "merchant@xyz",
    "payeeName": "John Doe",
    "payeeMcc": "1520",
    "amount": "2.00",
    "splitDetails": [{"name": "CCONFEE", "value": "1.00"}, {"name": "PCONFEE", "value": "1.00"}],
    "enableTips": true,
    "currency": "INR",
    "remarks": "Payment for order",
    "refUrl": "www.xyz.com",
    "refCategory": "01"
  },
  "udfParameters": "{}"
}

This api can be used to register an merchant intent payment. The response parameters should be passed as it is in the deeplink url. Refer below table for mapping of response parameters to the deeplink url parameters.

Response Parameter	Deeplink URL Parameter
payeeVpa	pa
payeeName	pn
payeeMcc	mc
gatewayTransactionId	tid
orderId	tr
amount optional	am
splitDetails optional	split split=CCONFEE:1.00|PCONFEE:1.00
enableTips optional	enTips enTips="Y"
currency	cu
remarks optional	tn optional
refUrl optional	url optional
refCategory optional	category optional

Note:

1. This is an idempotent api.
2. splitDetails enables Tips and Convenience Fee feature, encompassing details of the supplementary expenses.
3. enableTips indicates whether tips are accepted by the merchant.

Request parameters

Parameter	Description	Constraints
merchantRequestId	Merchant generated id for the transaction	35 characters alphanumeric
upiRequestId	Unique id sent to UPI switch for the transaction	35 character alphanumeric
amount optional	Amount of intent transaction being registered	Amount in two decimals. Decimals are mandatory
splitDetails optional	Supplementary Expenses of the transaction	List of JSON with name (supplementary expense) in string and value (amount) as numeric string with two decimals
enableTips optional	Indicates whether tips are accepeted	Boolean
intentRequestExpiryMinutes (Optional)	Minutes for which intent is valid. If this value is not passed, the default value will be used from merchant configurations. if both of them aren't available, intent will never expire.	number > 0 (as string)
intentRequestExpirySeconds (Optional)	Seconds for which intent is valid. If this value is not passed, intentRequestExpiryMinutes will consider. If this value not passed. then the default value will be used from merchant configurations. if both of them aren't available, intent will never expire.	number > 0 (as string)
remarks optional	Remarks for the intent transaction being registered	String
refUrl optional	Reference url for the intent transaction being registered	String
refCategory optional	Details for refUrl for the intent transaction being registered, whether it is 01 (Advertisement), 02(Invoice)	String
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
gatewayTransactionId	Gateway transaction id to be used for the intent transaction	String as passed in the request
orderId	Transaction refernce to be used for the intent transaction	String
payeeVpa	Payee VPA to be used for the intent transaction	String
payeeName	Payee name to be used for the intent transaction	String
payeeMcc	Payee mcc to be used for the intent transaction	String
amount optional	Amount to be used for the intent transaction	String as passed in the request
splitDetails optional	Supplementary Expenses to be used for the intent transaction	List of JSON as passed in the request
enableTips optional	Indicates whether tips are accepted	Boolean
currency	Currency to be used for the intent transaction	String INR
remarks optional	Remarks to be used for the intent transaction	String as passed in the request
refUrl optional	Reference URL to be used for the intent transaction	String as passed in the request
refCategory optional	Reference URL category to be used for the intent transaction	String as passed in the request
udfParameters optional	Udf parameters as passed in the request	JSON string

Merchant Deregister Intent

curl -L -X POST '{{host}}/api/n2/merchants/transactions/deregisterIntent'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-sub-merchant-id': 'SUBMERCHANT', \
  'x-sub-merchant-channel-id': 'SUBMERCHANTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "deregisterReason": "Transaction cancelled from POS",
  "merchantRequestId": "ord50894574",
  "udfParameters": "{}"
}'


# Response: HTTP 200 OK
{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload": {
        "merchantChannelId": "TEST",
        "merchantId": "TESTAPP",
        "subMerchantId": "SUBMERCHANT",
        "subMerchantChannelId": "SUBMERCHANTAPP",
        "merchantRequestId": "ord50894574"
    },
    "udfParameters": "{}"
}

This api is called to deregister a registered intent. It can be used for cancelling a transaction initiated by merchant intent that is not yet processed.

Refer below table for possible scenarios -

Scenario	status	responseCode	responseMessage
Intent not found	INVALID_DATA	INVALID_DATA
Intent already deregistered / Intent already expired	INVALID_DATA	INVALID_DATA	Intent already expired
Transaction PENDING/SUCCES	BAD_REQUEST	BAD_REQUEST	Transaction is in PENDING/SUCCESS state

Note Merchant will be allowed to deregister intent if transaction is updated to FAILURE from PENDING

Request parameters

Parameter	Description	Constraints
deregisterReason optional	Reason for deregister	String
merchantRequestId	merchantRequestId used for register intent	35 characters alphanumeric
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
subMerchantId	merchantId of the sub-merchant	As passed while creation.
subMerchantChannelId	channelId for the sub-merchant	As passed while creation.
merchantRequestId	merchantRequestId as passed in the request	35 characters alphanumeric
udfParameters optional	Udf parameters as passed in the request	JSON string

Merchant Refund 360

curl -L -X POST '{{host}}/api/n2/merchants/transactions/refund360'
-H 'x-api-version: 2' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-sub-merchant-id': 'SUBMERCHANT', \
  'x-sub-merchant-channel-id': 'SUBMERCHANTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "originalUpiRequestId": "AUTcb313014204649ad8818933d8623abd7",
  "originalTransactionTimestamp": "2019-06-07T17:57:49+05:30",
  "refundRequestId": "refund4543843",
  "refundAmount": "19.00",
  "refundType": "ONLINE",
  "merchantRefundVpa": "abcd@xyz",
  "remarks": "OrderCancel",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantRequestId": "TXN1234567",
    "refundRequestId": "refund4543843",
    "transactionAmount": "200.00",
    "refundAmount": "19.00",
    "refundType": "ONLINE",
    "refundTimestamp": "2019-06-09T17:57:49+05:30",
    "riskScore": "00979",
    "gatewayTransactionId": "AUTcb313014204649ad8818933d8623abd7",
    "gatewayRefundReferenceId": "809323430413",
    "gatewayRefundTransactionId": "AUT732f45e1c9284b83bc602f99f0c2ffca",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Your refund is successful",
    "gatewayPayerResponseCode": "00",
    "gatewayPayeeResponseCode": "00",
    "gatewayPayerReversalResponseCode": "00",
    "gatewayPayeeReversalResponseCode": "00"
  },
  "udfParameters": "{}"
}

This api can be used to trigger a refund against a successful merchant transaction. There are two types of refunds supported - ONLINE and OFFLINE. ONLINE refunds get credited to remitter account instantly, whereas OFFLINE refunds take around 3-5 working days.

Note:

1. This is an idempotent api.
2. Use --header x-api-version: 2 to get gatewayRefundTransactionId and merchantRequestId in response.

Request parameters

Parameter	Description	Constraints
originalUpiRequestId	UPI request id for the original transaction against which refund is being initiated	35 character alphanumeric
originalTransactionTimestamp optional	Timestamp of the original transaction	As returned in the response of original transaction api, String (YYYY-MM-DDTHH:MM:SS+05:30)
refundRequestId	Merchant generated unique id for the refund	35 characters alphanumeric
refundAmount	The amount to be refunded	String with mandatory two decimals
refundType	Type of refund being initiated	OFFLINE, ONLINE
merchantRefundVpa optional	Merchant refund vpa that is to be used for online refund	mandatory for refundType = ONLINE, vpa@handle,
remarks	Remarks or reason for the refund	String
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant	As passed in request headers
merchantChannelId	Unique id for the merchant channel	As passed in request headers
refundRequestId	Merchant generated unique id for the refund	As passed in the request body
transactionAmount	The total amount for which original transaction was performed	String with mandatory two decimals
refundAmount	The amount to be refunded	As passed in the request body
refundType	Type of refund being initiated	As passed in the request body
refundTimestamp	Timestamp of when refund request was initiated	String (YYYY-MM-DDTHH:MM:SS+05:30)
riskScore optional	RiskScore shared by NPCI or Bank	String
gatewayTransactionId	UPI request id returned by gateway for the transaction	Same as originalUpiRequestId passed in request
gatewayRefundReferenceId	Reference id returned by the gateway for the refund	String
gatewayResponseStatus	Response status returned by gateway for the refund	String (SUCCESS, PENDING, DEEMED, FAILURE)
gatewayResponseCode	Response code returned by gateway for the refund	String
gatewayResponseMessage	Response message for code returned by gateway for the refund	String
gatewayPayerResponseCode optional	Response code returned by gateway	String
gatewayPayeeResponseCode optional	Response code returned by gateway	String
gatewayPayerReversalResponseCode optional	Response code returned by gateway	String
gatewayPayeeReversalResponseCode optional	Response code returned by gateway	String
udfParameters optional	Udf parameters	As passed in the request body
gatewayRefundTransactionId optional	UPI Request Id of refund transaction	String
merchantRequestId optional	Merchant Request Id of original transaction	String

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Refund accepted successfully
01	PENDING	Refund is in pending state
91	PENDING	Refund is in pending state
09	PENDING	Refund is in pending state
060	PENDING	Refund is in pending state
070	PENDING	Refund is in pending state
080	PENDING	Refund is in pending state
RB	DEEMED	Refund is in deemed state
96	DEEMED	Refund is in deemed state
Else	FAILURE	Refund failed

Merchant UDIR Refund 360

curl -L -X POST '{{host}}/api/n2/merchants/transactions/refund360'
-H 'x-api-version: 2' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-sub-merchant-id': 'SUBMERCHANT', \
  'x-sub-merchant-channel-id': 'SUBMERCHANTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "originalUpiRequestId": "XYZ6d8dda4d19624db4ab6ef68827eb16c5",
  "refundUpiRequestId": "XYZ6d8dda4d19624db4ab6ef68827eb16c5",
  "originalMerchantRequestId": "XYZ5a305bd4320a4222b4c4030",
  "originalTransactionTimestamp": "2019-06-07T17:57:49+05:30",
  "refundRequestId": "refund4543843",
  "refundAmount": "5.00",
  "refundType": "UDIR",
  "remarks": "OrderCancel",
  "iat": "1700158230380",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseMessage": "SUCCESS",
  "responseCode": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "subMerchantId": "SUBTEST",
    "subMerchantChannelId": "SUBTESTAPP",
    "originalMerchantRequestId": "XYZ5a305bd4320a4222b4c4030",
    "refundRequestId": "XYZf114563085c349cb9b6fca3",
    "refundAmount": "5.00",
    "refundType": "UDIR",
    "refundTimestamp": "2025-03-25T20:17:25+05:30",
    "remarks": "OrderCancel",
    "merchantRefundVpa": "abc@xyz",
    "riskScore": "00",
    "gatewayTransactionId": "XYZ0efa4fa999f34e23ab5a3cf",
    "gatewayRefundReferenceId": "508454647889",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Your transaction is successful",
    "gatewayRefundTransactionId": "XYZ4e955834042b4fe094aa950",
    "crn": "UPI25021721630",
    "reqAdjCode": "U008",
    "reqAdjFlag": "PBRB",
    "adjFlag": "RRC",
    "adjCode": "501"
  },
  "udfParameters": "{}"
}

This api can be used to trigger a refund against a successful complaint resolve and if the transaction is successful.

Refund360 will be used for initiating a new refund or getting the status of an existing refund. If the "refundRequestId" is present with the PSP, then the latest status of the existing refund will be returned. If not present, then a new refund will be triggered.

UDIR refunds get credited to remitter account instantly.

Note:

1. This is an idempotent api.

Request parameters

Parameter	Description	Constraints
originalUpiRequestId	UPI request id for the original transaction against which refund is being initiated	35 character alphanumeric
refundUpiRequestId optional	Upi request Id used for refund transaction	Max 35 characters alphanumeric.
originalMerchantRequestId conditional	merchantRequestId of the original transaction against which refund is being initiated.	35 character alphanumeric
originalTransactionTimestamp optional	Timestamp of the original transaction	As returned in the response of original transaction api, String (YYYY-MM-DDTHH:MM:SS+05:30)
refundRequestId	Merchant generated unique id for the refund	35 characters alphanumeric
refundAmount	The amount to be refunded	String with mandatory two decimals
refundType	Type of refund being initiated	UDIR
remarks	Remarks or reason for the refund	String
iat	Current Epoch Unix timestamp string. Has to be of 13 digit in Milliseconds	Example: 1496918882000
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant	As passed in request headers
merchantChannelId	Unique id for the merchant channel	As passed in request headers
refundRequestId	Merchant generated unique id for the refund	As passed in the request body
transactionAmount	The total amount for which original transaction was performed	String with mandatory two decimals
refundAmount	The amount to be refunded	As passed in the request body
refundType	Type of refund being initiated	As passed in the request body
refundTimestamp	Timestamp of when refund request was initiated	String (YYYY-MM-DDTHH:MM:SS+05:30)
riskScore optional	RiskScore shared by NPCI or Bank	String
gatewayTransactionId	UPI request id returned by gateway for the transaction	Same as originalUpiRequestId passed in request
gatewayRefundReferenceId	Reference id returned by the gateway for the refund	String
gatewayResponseStatus	Response status returned by gateway for the refund	String (SUCCESS, PENDING, DEEMED, FAILURE)
gatewayResponseCode	Response code returned by gateway for the refund	String
gatewayResponseMessage	Response message for code returned by gateway for the refund	String
gatewayPayerResponseCode optional	Response code returned by gateway	String
gatewayPayeeResponseCode optional	Response code returned by gateway	String
gatewayPayerReversalResponseCode optional	Response code returned by gateway	String
gatewayPayeeReversalResponseCode optional	Response code returned by gateway	String
udfParameters optional	Udf parameters	As passed in the request body
gatewayRefundTransactionId	UPI Request Id of refund transaction	String
merchantRequestId optional	Merchant Request Id of original transaction	String
subMerchantId optional	Unique id for subMerchant. Only if present as a subMerchant	String
subMerchantChannelId optional	Unique id for the channel via which request is made. Only if present as a subMerchant	String
adjFlag optional	Reason flag for complaint sent to NPCI	String
adjCode optional	Reason flag for complaint sent to NPCI	String
reqAdjFlag	Reason flag for complaint sent to NPCI	String
reqAdjCode	Reason flag for complaint sent to NPCI	String
crn optional	Complaint reference number returned by NPCI	14 to 16 characters alphanumeric
merchantRefundVpa optional	RefundVPA used for refund	String
originalMerchantRequestId optional	merchantRequestId of the original transaction against which refund is being initiated.	35 character alphanumeric
remarks optional	Remarks or reason for the refund	String

Reason codes for Refund From Beneficiary

AdjFlag	AdjCode	Description
REF	1064	Goods or Services Not Provided
REF	1084	Duplicate /Multiple Transaction
REF	1063	Customer paid by alternate means

Reason codes for Refund From NPCI

AdjFlag	AdjCode	Description
RRC	501	Success
RRC	502	Pending
RRC	UT1, UT2, UT3, UT4, UT6, UT7	Pending
RRC	UT5	Failure

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Refund accepted successfully
01	PENDING	Refund is in pending state
91	PENDING	Refund is in pending state
09	PENDING	Refund is in pending state
060	PENDING	Refund is in pending state
070	PENDING	Refund is in pending state
080	PENDING	Refund is in pending state
RB	DEEMED	Refund is in deemed state
96	DEEMED	Refund is in deemed state
Else	FAILURE	Refund failed

Push To VPA

# Sample request
curl -X POST "{{host}}/api/{{uri}}/merchants/transactions/pushToVpa"
-H "Content-Type: application/json"
-H 'x-merchant-id: TEST'
-H 'x-merchant-channel-id: TESTAPP'
-H 'x-timestamp: 1496918882000'
-H 'x-merchant-signature: 823647862547652376452378456'
-d '{
  "upiRequestId" : "AUTef1a2908395239df56663244f8c7deaa",
  "transactionReference" : "P1708071422508815250029",
  "mcc" : "1520",
  "merchantRequestId" : "809323430000",
  "customerVpa" : "abc@xyz",
  "upiNumber" : "755027711",
  "amount" : "20.00",
  "merchantVpa" : "abcd@xyz",
  "remarks" : "This is remarks",
  "isPreApproved" : "true",
  "udfParameters" : "{}"
}'

# The above command returns JSON structured like this:

{
    "status": "SUCCESS",
    "responseCode": "SUCCESS",
    "responseMessage": "SUCCESS",
    "payload": {
        "customerVpa": "abc@xyz",
        "upiNumber": "755027711",
        "merchantId": "MERCHANT",
        "merchantChannelId": "MERCHANTAPP",
        "merchantRequestId": "809323430000",
        "transactionAmount": "20.00",
        "bankAccountHash": "22f7eec6fe658743b249451e87b25923484a361bea20415b58068d9ff19dc2a3",
        "payeeAccountNumber": "98765432112",
        "payeeMaskedAccountNumber": "XXXXX7415",
        "payeeName": "John Doe",
        "payeeIfsc": "XXXXXXXXXXX",
        "gatewayReferenceId": "809323430413",
        "gatewayTransactionId": "AUTd0c077f39c454979...",
        "gatewayResponseCode": "00",
        "gatewayResponseMessage": "Your transaction is successful",
        "gatewayResponseStatus": "SUCCESS"
    },
    "udfParameters": "{}"
}

Note

1. This API hits TSP Server with a timeout of 60 seconds.
2. This api will be used for initiating a new PushToVpa to transfer money directly to the customer.

Request parameters

Parameter	Description	Constraints
upiRequestId	Unique id passed to NPCI.	35 character alphanumeric. Should always start with a unique merchant prefix
transactionReference	Required for Intent & QR	Required for Intent & QR
mcc optional	Merchant Category Code for the merchant whose VPA is passed	String
merchantRequestId	Request id for PushToVpa request	35 character alphanumeric unique id.
customerVpa	Vpa of the customer to be used for transaction.	something@handle
upiNumber optional	upiNumber of payee if transaction is done using UPI Number	String (8-10 digit Number)
amount	Amount for the transaction.	Numeric string with two decimals.
merchantVpa	Vpa of the merchant from which amount has to be deducted.	something@handle
remarks	Remarks sent by merchant for the transaction.	50 characters alphanumeric with space and hyphen
isPreApproved	If isPreApproved is true, it implies no additional debit is required from the payer’s account. if it is false the payer’s account will be debited to complete the transaction.	Boolean string
udfParameters	JSON for udf parameters	JSON

Response parameters

Parameter	Description	Values
status	Status of the API.	SUCCESS, FAILURE
responseCode	SUCCESS if call succeeded. Otherwise shows the error code.	Refer error code section
responseMessage	SUCCESS if call succeeded. Otherwise shows verbose error.	Refer error code section
customerVpa	Vpa of the customer to be used for transaction.	As passed in the request
upiNumber optional	upiNumber of payee if transaction is done using UPI Number	String (8-10 digit Number)
merchantId	Unique id for merchant.	As passed for x-merchant-id in request headers.
merchantChannelId	Unique id for the channel via which request is made.	As passed for x-merchant-channel-id in request headers.
merchantRequestId	Request id used for the transaction	String
transactionAmount	The amount for which transaction was performed	As passed in request.
bankAccountHash	A hashed version of the payee's account number	String
payeeAccountNumber	Account number for the payee	Numeric string. Maximum length is 30.
payeeMaskedAccountNumber	Masked account number for the sub-merchant	XXXX123456
payeeName optional	Name of the payee	String as returned in the Verify VPA API
payeeIfsc	Account ifsc of the customer who received the payment	String
gatewayReferenceId	RRN for the transaction.	Customer reference number (rrn) for the transaction.
gatewayTransactionId	UPI request id returned by gateway for the transaction.	String
gatewayResponseCode	Response code returned by gateway for the transaction.	00, Any valid NPCI error code
gatewayResponseMessage	Response message returned by gateway for the transaction.	String
gatewayResponseStatus	Response status returned by gateway.	SUCCESS,FAILURE,PENDING
udfParameters	JSON for udf parameters	JSON

gatewayResponseCode	Description
00	Transaction accepted successfully.
01	Transaction is in pending state.
060	Transaction is in pending state.
070	Transaction is in pending state.
080	Transaction is in pending state.
09	Transaction is in pending state.
RB	Transaction is in deemed state.
Else	Failure

Push To VPA Status

# Sample request
curl -X POST "{{host}}/api/{{uri}}/merchants/transactions/pushToVpa/status"
-H "Content-Type: application/json"
-H 'x-merchant-id: MERCHANT'
-H 'x-merchant-channel-id: MERCHANTAPP'
-H 'x-timestamp: 1496918882000'
-H 'x-merchant-signature: 823647862547652376452378456'
-d '{
  "merchantRequestId": "809323430000",
  "merchantVpa": "abcd@xyz",
  "udfParameters": null
}'

# The above command returns JSON structured like this:

{
    "status": "SUCCESS",
    "responseCode": "SUCCESS",
    "responseMessage": "SUCCESS",
    "payload": {
        "customerVpa": "abc@xyz",
        "merchantId": "MERCHANT",
        "merchantChannelId": "MERCHANTAPP",
        "merchantRequestId": "809323430000",
        "transactionAmount": "20.00",
        "gatewayReferenceId": "809323430413",
        "gatewayTransactionId": "AUTd0c077f39c454979...",
        "gatewayResponseCode": "00",
        "gatewayResponseMessage": "Your transaction is successful",
        "gatewayResponseStatus": "SUCCESS",
        "bankAccountHash": "22f7eec6fe658743b249451e87b25923484a361bea20415b58068d9ff19dc2a3",
        "payeeAccountNumber": "98765432112",
        "payeeMaskedAccountNumber": "XXXXX7415",
        "payeeName": "John Doe",
        "payeeIfsc": "XXXXXXXXXXX"
    },
    "udfParameters": null
}

Note This API hits TSP Server with a timeout of 60 seconds.

This api will be used for checking status of a pushToVpa transaction.

Request parameters

Parameter	Description	Constraints
merchantRequestId	Request id for PushToVpa request	35 character alphanumeric unique id.
merchantVpa	Vpa of the merchant with which PushToVpa request was made.	something@handle
udfParameters	JSON for udf parameters	JSON

Response parameters

Parameter	Description	Values
status	Status of the API.	SUCCESS, FAILURE
responseCode	SUCCESS if call succeeded. Otherwise shows the error code.	Refer error code section
responseMessage	SUCCESS if call succeeded. Otherwise shows verbose error.	Refer error code section
customerVpa	Vpa of the customer to be used for transaction.	As passed in the request
merchantId	Unique id for merchant.	As passed for x-merchant-id in request headers.
merchantChannelId	Unique id for the channel via which request is made.	As passed for x-merchant-channel-id in request headers.
merchantRequestId	Request id used for the transaction	String
transactionAmount	The amount for which transaction was performed	As passed in request.
gatewayReferenceId	RRN for the transaction.	String
gatewayTransactionId	UPI request id returned by gateway for the transaction.	String
gatewayResponseCode	Response code returned by gateway for the transaction.	00
gatewayResponseMessage	Response message returned by gateway for the transaction.	String
gatewayResponseStatus	Response status returned by gateway.	SUCCESS,FAILURE,PENDING
bankAccountHash	A hashed version of the payee's account number	String
payeeAccountNumber	Account number for the payee	Numeric string. Maximum length is 30.
payeeMaskedAccountNumber	Masked account number for the sub-merchant	XXXX123456
payeeName optional	Name of the payee	String as returned in the Verify VPA API
payeeIfsc	Account ifsc of the customer who received the payment	String
udfParameters	JSON for udf parameters	JSON

gatewayResponseCode	Description
00	Transaction accepted successfully.
01	Transaction is in pending state.
060	Transaction is in pending state.
070	Transaction is in pending state.
080	Transaction is in pending state.
09	Transaction is in pending state.
RB	Transaction is in deemed state.
Else	Failure

Sign URL

# Sample request
curl -X POST
-H "Content-Type: application/json"
-H 'x-merchant-channel-id: MERCHANTAPP'
-H 'x-merchant-signature: 823647862547652376452378456'
-H 'x-merchant-id: MERCHANT'
-H 'x-timestamp: 1496918882000'
-d '{
  "url": "upi://pay?pa=amazonpay@apl&pn=Purna&tn=SignedIntentTesting&am=10&mam=null&cu=INR&tr=UPITestHelper1&mode=05&orgid=109211",
  "udfParameters": "{}"
}' "{{host}}/api/{{uri}}/merchants/signURL"

# The above command returns JSON structured like this:

{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload": {
        "signature": "MEYCIQCBMm3UY8qzs1F21U/yQExt96PjzQu8ppvOr9QW7kd3PwIhALR+PV0mcE/RC11ma4RRc/yeLk34jF/bP17adGx0qfYj",
        "merchantChannelId": "AMAZONAPP",
        "merchantId": "AMAZON"
    },
    "udfParameters": "{}"
}

This API will be used to generate PSP-signed Intent/QR url for signed-intent/QR transactions.

Note PSP will sign the url when pa is not a verified merchant and orgid=PSP's orgID.

Request parameters

Parameter	Description	Constraints
url	UPI QR/Intent URL to be signed	String
udfParameters	Json for udf parameters	JSON

Response parameters

Parameter	Description	Values
status	Status of the API.	SUCCESS, FAILURE
responseCode	SUCCESS if call succeeded. Otherwise shows the error code.	Refer error code section
responseMessage	SUCCESS if call succeeded. Otherwise shows verbose error.	Refer error code section
signature	Signature of the URL that has to be appended in the URL with &sign=.	String
merchantId	Unique id for merchant.
merchantChannelId	Unique id for the channel via which request is made.
udfParameters	Json for udf parameters	JSON

Validate URL

# Sample request
curl -X POST
-H "Content-Type: application/json"
-H 'x-merchant-channel-id: MERCHANTAPP'
-H 'x-merchant-signature: 823647862547652376452378456'
-H 'x-merchant-id: MERCHANT'
-H 'x-timestamp: 1496918882000'
-d '{
  "url": "upi://pay?pa=amazonpay@apl&pn=Purna&tn=SignedIntentTesting&am=10&mam=null&cu=INR&tr=UPITestHelper1&mode=05&orgid=109211&sign=MEQCIDrDvhyTTyCEvbaCU4MNkLKWDNoonYxeWniPxQozp6P1AiBVtZEgoDEgsNkhF+JSMPQ2QNJahoaJaKv0kBWvbayUEA==",
  "udfParameters": "{}"
}' "{{host}}/api/{{uri}}/merchants/validateURL"

# The above command returns JSON structured like this:

{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload": {
        "merchantChannelId": "AMAZONAPP",
        "merchantId": "AMAZON",
        "valid": true
    },
    "udfParameters": "{}"
}

This API will be used to validate signed Intent/QR url for signed-intent/QR transactions.

Request parameters

Parameter	Description	Constraints
url	UPI QR/Intent URL to be validated	String
udfParameters	Json for udf parameters	JSON

Response parameters

Parameter	Description	Values
status	Status of the API.	SUCCESS, FAILURE
responseCode	SUCCESS if call succeeded. Otherwise shows the error code.	Refer error code section
responseMessage	SUCCESS if call succeeded. Otherwise shows verbose error.	Refer error code section
valid	If sign in the url is valid then true else false	Boolean
merchantId	Unique id for merchant.
merchantChannelId	Unique id for the channel via which request is made.
udfParameters	Json for udf parameters	JSON

Mandate Merchant APIs

Web Mandate

# Sample request

curl -X POST
-H "Content-Type: application/json"
-H 'x-merchant-channel-id: MERCHANTAPP'
-H 'x-merchant-signature: 823647862547652376452378456'
-H 'x-merchant-id: MERCHANT'
-H 'x-timestamp: 1496918882000'
-d '{
  "amount": "100.00",
  "amountRule": "EXACT",
  "blockFund": "true"
  "customerVpa": "example@handle",
  "mandateName" : "Sample Mandate",
  "mandateRequestExpiryMinutes" : "100",
  "merchantRequestId": "TXN1234567",
  "payerRevocable": "true",
  "recurrencePattern": "MONTHLY",
  "recurrenceRule" : "ON",
  "recurrenceValue": "7",
  "refCategory": "02"
  "refUrl": "https://www.abcxyz.com/",
  "remarks": "Sample Mandate Request",
  "udfParameters" : "{}"
  "upiRequestId": "APL71f7d43bdf64d72d9saddfded",
  "validityEnd": "2020/4/25",
  "validityStart": "2020/3/25",
  "platform" : "IOS"
}' "{{host}}/api/a2/merchants/mandates/webMandate"

# The above command returns JSON structured like this:

{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "amount": "100.00",
    "amountRule": "EXACT",
    "blockFund": "false",
    "customerVpa": "9962463212@bankuat1",
    "expiry": "2020-12-24T14:17:06+05:30",
    "gatewayMandateId": "APL71f7d43bdf64d72d9saddfded",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Request Mandate successfully",
    "gatewayResponseStatus": "SUCCESS",
    "mandateName": "merchant mandate",
    "mandateTimestamp": "2020-06-01T15:40:42+05:30",
    "merchantChannelId": "XYZ",
    "merchantId": "XYZ",
    "merchantRequestId": "6138ne3wswbsssddc4dddc",
    "orgMandateId": "APL71f7d43bdf64d72d187317de123",
    "payerRevocable": "true",
    "recurrencePattern": "MONTHLY",
    "recurrenceRule": "ON",
    "recurrenceValue": "5",
    "refCategory": "02",
    "refUrl": "https://www.abcxyz.com/",
    "remarks": "merchant mandate",
    "validityEnd": "2020/06/05",
    "validityStart": "2020/06/04",
  },
  "udfParameters":"{}"
}

This API hits TSP Server with a timeout of 60 seconds.

This api will be used for requesting the mandate by Merchant to the Payer.

Request parameters

Parameter	Description	Constraints
amount	Amount for which merchant requested the mandate	Amount in two decimals. Decimals are mandatory.
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.	String but only allowed values are EXACT / MAX
blockFund optional	Denotes whether customer's fund should be blocked or not. Only applicable for ONETIME mandate. For recurring mandate it should always be false, for onetime it can be true or false. Default value is false.	String - true,false
customerVpa	VPA on which request mandate should be triggered	Valid VPA
mandateName	Name of the mandate	String
mandateRequestExpiryMinutes	Minutes for which request is valid	A number between 2 to 64800, both inclusive, in String format.
merchantRequestId	Merchant generated id for the mandate	35 character alphanumeric unique id.
payerRevocable optional	Defines whether mandate is revocable by PAYER or not. Applicable only when it is ONETIME mandate and initiatedBy PAYEE. For recurring mandate it should always be true, for onetime it can be true or false. Default value is true.	String - true/false.
recurrencePattern	Recurrence Pattern for Mandate. Denotes at what frequency mandate can be executed.	ONETIME, DAILY, WEEKLY, FORTNIGHTLY,MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED
recurrenceRule conditional	Recurrence Rule for Mandate. It is not required for ONETIME, DAILY and ASPRENTED recurrencePattern.	ON, BEFORE, AFTER.
recurrenceValue conditional	Recurrence Value for Mandate. It is not required for ONETIME, DAILY and ASPRENTED recurrencePattern.	between 1-31 and depends on recurrencePattern.
refCategory optional	Details for refUrl, whether it is 01 (advertisement), 02(Invoice). If nothing is passed, a default value of "00" is set up and same will be sent back in response.	Numeric String
refUrl optional	Invoice as sesnt by merchant or reference to the mandate in the form of url. If nothing is passed then a default value is set for this tag and same will be send back in response.	String
remarks optional	Any mandate summary	String
udfParameters optional	Stringified json for udf parameters.	String "udfParameters" : "{}"
upiRequestId	Unique id passed to NPCI.	35 character alphanumeric. Should always start with a unique merchant prefix
validityEnd	Date befor which mandate can be execute	String with proper date format YYYY/MM/DD
validityStart	Date after which mandate can be executed	String with proper date format YYYY/MM/DD
platform	Platform from which request is initiated	WEB, ANDROID,IOS

Response parameters

Parameter	Description	Values
status	Status of the API.	SUCCESS, FAILURE
responseCode	SUCCESS if call succeeded. Otherwise shows the error code.	Refer error code section
responseMessage	SUCCESS if call succeeded. Otherwise shows verbose error.	Refer error code section
amount	Amount for which merchant requested the mandate	As passed in request.
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.	As passed for amountRule in request.
customerVpa	VPA on which request mandate should be triggered	As passed in request
expiry	Minutes for which request is valid	Timestamp in YYYY-MM-DDTHH:MM:SS+05:30 format, request timestamp plus expiry minutes passed in request.
gatewayMandateId	UPI request id returned by gateway for the mandate	As passed for upiRequestId in request
gatewayResponseCode	Response code returned by gateway for the transaction.	00
gatewayResponseMessage	Response message returned by gateway for the transaction.	String
gatewayResponseStatus	Response status returned by gateway.	SUCCESS, FAILURE
mandateName	Name of the mandate	As passed in request
mandateTimestamp	Timestamp of when the webMandate was initiated	(YYYY-MM-DDTHH:MM:SS+05:30)
merchantChannelId	Unique id for the channel via which request is made.	As passed in request.
merchantId	Unique id for merchant.	As passed in request.
merchantRequestId	35 character alphanumeric unique id.	As passed in request
orgMandateId	Refers to upiRequestId used during creation of mandate	As passed for upiRequestId in the request.
payerRevocable	Defines whether mandate is revocable by PAYER or not. For onetime mandate it can be true or false. Default value is true.	String - true, false
recurrencePattern	Recurrence Pattern for Mandate	As passed for recurrencePattern in request
recurrenceRule conditional	Recurrence Rule for Mandate. It will not be present for ONETIME, DAILY and ASPRESENTED recurrence pattern.	As passed for recurrenceRule in request
recurrencValue conditional	Recurrence Value for Mandate. It will not be present for ONETIME, DAILY and ASPRESENTED recurrence pattern.	As passed for recurrencValue in request.
refCategory	Details for refUrl, whether it is 01 (advertisement), 02(Invoice). It will be same value if passed in request, else a default value of "00" is sent.	Numeric String
refUrl	Reference url for the mandate. It will be same value if passed in request else it will be a default url.	String
remarks	Any mandate summary. If pssed in request, it will be same in response else a default value is send.	String
udfParameters optional	Udf parameters as passed in the web mandate request.	As passed in request
validityEnd	Date before which mandate can be executed.	As passed for validityEnd in request
validityStart	Date after which mandate can be executed.	As passed for validityStart in request

responseCode	responseMessage
SUCCESS	SUCCESS
INTERNAL_SERVER_ERROR	INTERNAL_SERVER_ERROR
BAD_REQUEST	Any Other Reason

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Mandate Creation Success. / Mandate Create Request Sent Successfully
Z6	FAILURE	Number of pin tries exceeded.
ZM	FAILURE	Invalid mpin.
Else	FAILURE	Any other reason.

Web Update

# Sample request

curl -X POST
-H "Content-Type: application/json"
-H 'x-merchant-channel-id: MERCHANTAPP'
-H 'x-merchant-signature: 823647862547652376452378456'
-H 'x-merchant-id: MERCHANT'
-H 'x-timestamp: 1496918882000'
-d '{
  "amount": "100.00",
  "makeAsync": "true",
  "mandateRequestExpiryMinutes" : "100",
  "merchantRequestId": "TXN1234567",
  "orgMandateId": "APL71f7d43bdf64d72d9saddfded",
  "remarks": "Sample Mandate Update Request",
  "requestType": "UPDATE"
  "udfParameters" : "{}"
  "upiRequestId": "APL71f7d43bdf64d72d9saddskdfjks",
  "validityEnd": "2020/4/25",
}' "{{host}}/api/a2/merchants/mandates/webUpdate"

# The above command returns JSON structured like this:

{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "amount": "100.00",
    "customerVpa": "9962463212@bankuat1",
    "expiry": "2020-12-24T14:17:06+05:30",
    "gatewayMandateId": "APL71f7d43bdf64d72d9saddfded",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Update Mandate Requested Successfully",
    "gatewayResponseStatus": "SUCCESS",
    "mandateName": "merchant mandate"
    "mandateTimestamp": "2020-06-01T15:40:42+05:30",
    "merchantChannelId": "BANKBIZTEST",
    "merchantId": "BANKBIZTEST",
    "merchantRequestId": "6138ne3wswbsssddc4dddc",
    "orgMandateId": "APL71f7d43bdf64d72d9saddfded",
    "remarks": "Merchant update mandate",
    "umn" : "ABZv1f7daa3bf64729af61b0f6d95b8dd@bankbiz"
    "validityEnd": "2020/06/05",
  },
  "udfParameters":"{}"
}

This API hits TSP Server with a timeout of 60 seconds.

This api will be used for updating or revoking the mandate which is already created by Merchant to the Payer. Only validityEnd and amount of the original mandate can be updated. Either one of the two parameters is necessary when requestType is "UPDATE".

Request parameters

Parameter	Description	Constraints
amount conditional	Amount for mandate. Only required if amount needs to be updated for mandate and requestType is UPDATE. Either one of validityEnd or amount has to be passed.	Amount in two decimals. Decimals are mandatory.
makeAsync optional	Denotes whether the API call will be done in synchronous or asynchronous manner. If it is not passed by default API call will be in synchronous. It is not required if requestType is UPDATE as it will be default async as it requires approval from Customer.	true,false
mandateRequestExpiryMinutes	Minutes for which request is valid	A number between 1 to 64800, both inclusive, in String format.
merchantRequestId	Merchant generated id for the mandate	35 character alphanumeric unique id.
orgMandateId	gatewayMandateId returned in create mandate	String and it should be corresponding Upi Request id used during webMandate
remarks optional	Any mandate summary	String
requestType	differentiate the request for UPDATE and REVOKE	String but allowed values are only UPDATE and REVOKE
udfParameters optional	Stringified json for udf parameters.	String "udfParameters" : "{}"
upiRequestId	Unique id passed to NPCI.	35 character alphanumeric. Should always start with a unique merchant prefix
validityEnd conditional	Date after which mandate cannot be executed. Only required if validity end date needs to be updated for mandate and requestType is UPDATE. Either validityEnd or amount has to be passed.	String with proper date format YYYY/MM/DD

Response parameters

Parameter	Description	Values
status	Status of the API.	SUCCESS, FAILURE
responseCode	SUCCESS if call succeeded. Otherwise shows the error code.	Refer error code section
responseMessage	SUCCESS if call succeeded. Otherwise shows verbose error.	Refer error code section
amount	Updated amount for mandate. If only validityEnd is updated then amount will be same as it was passed during creation of mandate.	Numeric String
customerVpa	VPA on which request mandate should be triggered	Vpa for which mandate was requested during webMandate
expiry	Minutes for which request is valid	Timestamp in YYYY-MM-DDTHH:MM:SS+05:30 format, request timestamp plus expiry minutes passed in request.
gatewayMandateId	UPI request id returned by gateway for the mandate	As passed for upiRequestId in request
gatewayResponseCode	Response code returned by gateway for the transaction.	00
gatewayResponseMessage	Response message returned by gateway for the transaction.	String
gatewayResponseStatus	Response status returned by gateway.	SUCCESS, FAILURE
makeAsync optional	Denotes whether the API call will be done in synchronous or asynchronous manner	Only present if passed in reqBody and same value as in request.
mandateName	Name of the mandate	Name of the mandate
mandateTimestamp	Timestamp of when the webMandate was initiated	(YYYY-MM-DDTHH:MM:SS+05:30)
merchantChannelId	Unique id for the channel via which request is made.	As passed in request.
merchantId	Unique id for merchant.	As passed in request.
merchantRequestId	35 character alphanumeric unique id.	As passed in request
orgMandateId	gatewayMandateId returned in create mandate	As passed in request
remarks	Any mandate summary. If pssed in request, it will be same in response else a default value is send.	String
udfParameters optional	Udf parameters as passed in the request.	As passed for udfParameters in request.
umn	Vpa used for execution of mandate.	String
validityEnd	Updated date before which mandate can be executed. If only amount is updated then validityEnd will be same as it was passed during creation of mandate.	String with proper date format YYYY/MM/DD.

responseCode	responseMessage
SUCCESS	SUCCESS
INTERNAL_SERVER_ERROR	INTERNAL_SERVER_ERROR
JPMR	Mandate is revoked
JPMC	Mandate is completed
JPMD	Mandate is declined by payer
JPMR	Mandate is revoked due to first execution failure
JPMR	Mandate is revoked due to first execution failure
JPMX	Mandate is expried due to no action by payer
BAD_REQUEST	Any Other Reason

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Mandate Updation Success. / Mandate Update/Revoke Request Sent Successfully
Z6	FAILURE	Number of pin tries exceeded.
ZM	FAILURE	Invalid mpin.
Else	FAILURE	Any other reason.

Web Execute

# Sample request

curl -X POST
-H "Content-Type: application/json"
-H 'x-merchant-channel-id: MERCHANTAPP'
-H 'x-merchant-signature: 823647862547652376452378456'
-H 'x-merchant-id: MERCHANT'
-H 'x-timestamp: 1496918882000'
-d '{
  "amount": "100.00",
  "collectRequestExpiryMinutes" : "100",
  "merchantRequestId" : "TXN1234567",
  "notificationMerchantRequestId" : "TXN1234567",
  "refCategory": "02",
  "refUrl": "https://www.abcxyz.com/",
  "remarks": "Sample Mandate Request",
  "udfParameters" : "{}"
  "umn" : "ABZv1f7daa3bf64729af61b0f6d95b8dd@bankbiz"
  "upiRequestId": "XYZd0c077f39c454979...",
}' "{{host}}/api/a2/merchants/mandates/webExecute"

# The above command returns JSON structured like this:

{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "amount": "10.33",
    "expiry": "2020-12-24T14:17:06+05:30",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Mandate Execution Sent Successfully",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayTransactionId": "ABZ3d0c077f39c454a...",
    "merchantChannelId": "MERCHANTAPP",
    "merchantId": "MERCHANT",
    "merchantRequestId": "HEYYOU45",
    "notificationMerchantRequestId" : "TXN1234567",
    "orgMandateId": "APL71f7d43bdf64d72d187317de123",
    "payeeMcc": "1520",
    "refCateogory": "02",
    "refUrl": "https://www.abcxyz.com/",
    "remarks": "Sample Mandate Request",
    "transactionTimestamp": "2017-06-30T17:43:40+05:30",
    "umn": "AIX7ddddaa3bf64729af618evvev9ddddd@upi",
  },
  "udfParameters":"{}"
}

This API hits TSP Server with a timeout of 60 seconds.

This api will be used for executing the mandate by Merchant to the Payer.

Request parameters

Parameter	Description	Constraints
amount	Amount for which mandate is to be executed.	Amount in two decimals. Decimals are mandatory.
collectRequestExpiryMinutes	Minutes for which request is valid	A number between 1 to 64800, both inclusive, in String format.
merchantRequestId	Merchant generated id for the mandate	35 character alphanumeric unique id.
notificationMerchantRequestId optional	merchantRequestId used during notification. Used for linking notification and execution.	35 character alphanumeric unique id.
refCategory optional	Details for refUrl, whether it is 01 (advertisement), 02(Invoice)	String
refUrl optional	Invoice as sent by merchant or reference to the mandate in the form of url.	String
remarks optional	Mandate Execute Summary	String
udfParameters optional	Stringified json for udf parameters.	String "udfParameters" : "{}"
umn	umn returned in create mandate callback	35 character alphanumeric unique id.
upiRequestId	Unique id passed to NPCI.	35 character alphanumeric. Should always start with a unique merchant prefix

Response parameters

Parameter	Description	Values
status	Status of the API.	SUCCESS, FAILURE
responseCode	SUCCESS if call succeeded. Otherwise shows the error code.	Refer error code section.
responseMessage	SUCCESS if call succeeded. Otherwise shows verbose error.	Refer error code section.
amount	Amount for which merchant requested the mandate	As passed in request.
expiry	Minutes for which request is valid	Timestamp in YYYY-MM-DDTHH:MM:SS+05:30 format, request timestamp plus expiry minutes passed in request.
gatewayResponseCode	Response code returned by gateway for the transaction.	00.
gatewayResponseMessage	Response message returned by gateway for the transaction.	String
gatewayResponseStatus	Response status returned by gateway.	SUCCESS,FAILURE,PENDING
gatewayTransactionId	UPI request id returned by gateway for the transaction	As passed for upiRequestId in request.
merchantChannelId	Unique id for the channel via which request is made.	As passed in request.
merchantId	Unique id for merchant.	As passed in request.
merchantRequestId	35 character alphanumeric unique id.	As passed in request.
notificationMerchantRequestId optional	As passed in the request.	35 character alphanumeric unique id.
orgMandateId	gatewayMandateId returned in create mandate	As passed for gatewayMandateId in webMandate request.
payeeMcc	MCC code of the merchant	4121.
refCategory	Details for refUrl, whether it is 01 (advertisement), 02(Invoice). It will be same value if passed in request, else a default value of "00" is sent.	Numeric String
refUrl	Reference url for the mandate. It will be same value if passed in request else it will be a default url.	String
remarks	Any mandate summary. If pssed in request, it will be same in response else a default value is send.	String
transactionTimestamp	Timestamp of when txn request was triggered	(YYYY-MM-DDTHH:MM:SS+05:30)
udfParameters	Udf parameters as passed in the request.	As passed in request.
umn	umn returned in create mandate callback	As passed in request.

responseCode	responseMessage
SUCCESS	SUCCESS
INTERNAL_SERVER_ERROR	INTERNAL_SERVER_ERROR
JPMR	Mandate is revoked
JPMP	Mandate is paused
JPMC	Mandate is completed
JPMD	Mandate is declined by payer
JPMR	Mandate is revoked due to first execution failure
JPMR	Mandate is revoked due to first execution failure
JPMX	Mandate is expried due to no action by payer
BAD_REQUEST	Any Other Reason

gatewayResponseCode	gatewayResponseStatus	Description
01	PENDING	Collect Request Sent Successfully
Else	FAILURE	Any other reason.

Web Notify

# Sample request

curl -X POST
-H "Content-Type: application/json"
-H 'x-merchant-channel-id: MERCHANTAPP'
-H 'x-merchant-signature: 823647862547652376452378456'
-H 'x-merchant-id: MERCHANT'
-H 'x-timestamp: 1496918882000'
-d '{
     "amount":"10.22",
     "mandateExecutionTimestamp":"2020-09-10 11:32:20.454+05:30",
     "merchantRequestId":"TXN1234567",
     "remarks":"June Bill",
     "udfParameters":"{}"
     "umn":"APL71f7d43bdf64d72d9csaddffs",
     "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa"
}' "{{host}}/api/a2/merchants/mandates/webNotify"

# The above command returns JSON structured like this:

{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "amount":"10.22",
    "gatewayResponseCode": "01",
    "gatewayResponseMessage": "Your notification is in pending state",
    "gatewayResponseStatus": "PENDING",
    "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
    "merchantChannelId" : "MERCHANTAPP",
    "merchantId" : "MERCHANT",
    "merchantRequestId" : "TXN1234567"
    "nextExecution" : "2020-09-10 11:32:20.454+05:30",
    "orgMandateId": "APL71f7d43bdf64d72d187317de123",
    "remarks": "June Bill",
    "umn":"APL71f7d43bdf64d72d9csaddffs",
  },
  "udfParameters":"{}"
}

This API hits TSP Server with a timeout of 60 seconds.

This api will be used for notifying the Payer by the Merchant prior to the execution.

Request parameters

Parameter	Description	Constraints
amount	Amount for which customer is notified for execution.	Amount in two decimals. Decimals are mandatory.
mandateExecutionTimestamp	Mandate execution timestamp (Future Timestamp on which mandate will be executed)	String with proper date format (YYYY-MM-DDTHH:MM:SS+05:30)
merchantRequestId	Merchant generated id for the mandate	35 character alphanumeric unique id.
remarks optional	Remarks sent by merchant for notify mandate	String
udfParameters optional	Stringified json for udf parameters.	String "udfParameters" : "{}"
umn	umn returned in create mandate callback	35 character alphanumeric unique id.
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.

Response parameters

Parameter	Description	Values
status	Status of the API.	SUCCESS, FAILURE
responseCode	SUCCESS if call succeeded. Otherwise shows the error code.	Refer error code section
responseMessage	SUCCESS if call succeeded. Otherwise shows verbose error.	Refer error code section
amount	Amount for which customer is notified for execution.	As passed in request
gatewayResponseCode	Response code returned by gateway for the notification.	00.
gatewayResponseMessage	Response message returned by gateway for the notification.	String.
gatewayResponseStatus	Response status returned by gateway.	PENDING, FAILURE
gateWayTransactionId	upiRequestId as passed in request
merchantChannelId	Unique id for the channel via which request is made.	As passed in request.
merchantId	Unique id for merchant.	As passed in request.
merchantRequestId	35 character alphanumeric unique id.	As passed in request
nextExecution	Mandate execution timestamp (Future Timestamp on which mandate will be executed)	As passed in request
orgMandateId	gatewayMandateId returned in create mandate	As passed for gatewayMandateId in webMandate request.
remarks	Any mandate notification summary. If pssed in request, it will be same in response else a default value is send.	String
udfParameters optional	Udf parameters as passed in the web mandate request.	As passed in request
umn	umn returned in create mandate callback	As passed in request

responseCode	responseMessage
SUCCESS	SUCCESS
INTERNAL_SERVER_ERROR	INTERNAL_SERVER_ERROR
JPMR	Mandate is revoked
JPMP	Mandate is paused
JPMC	Mandate is completed
JPMD	Mandate is declined by payer
JPMR	Mandate is revoked due to first execution failure
JPMR	Mandate is revoked due to first execution failure
JPMX	Mandate is expried due to no action by payer
BAD_REQUEST	Any Other Reason

gatewayResponseCode	gatewayResponseStatus	Description
01	PENDING	Your notification is in pending state
Else	FAILURE	Any other reason.

Check Mandate Status

# Sample request

curl -X POST
-H "Content-Type: application/json"
-H 'x-merchant-channel-id: TESTAPP'
-H 'x-merchant-signature: 823647862547652376452378456'
-H 'x-merchant-id: TEST'
-H 'x-timestamp: 1496918882000'
-d '{
  "orgMandateId": "APL71f7d43bdf64d72d9saddskdfjks",
  "role": "PAYER",
  "upiRequestId": "APL82g8d43bdf64d72d9saddskdgklt"
  "udfParameters" : "{}"
}' "{{host}}/api/n2/merchants/mandates/status"

# The above command returns JSON structured like this:

{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "amount": "100.00",
    "amountRule": "EXACT",
    "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
    "blockFund": "true",
    "expiry": "2020-12-24T14:17:06+05:30",
    "gatewayMandateId": "APLMe5c9711f1ede1f5524e2fadb48003aa0",
    "gatewayReferenceId": "806115044725",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Mandate is Successfully revoked",
    "gatewayResponseStatus": "SUCCESS",
    "initiatedBy": "PAYER",
    "mandateApprovalTimestamp": "2017-06-09T18:57:49+05:30",
    "mandateName": "Sample Name",
    "mandateTimestamp": "2018-12-24T14:17:06+05:30",
    "mandateType": "CREATE",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "merchantId": "TEST",
    "merchantRequestId": "b1a4418b4ac",
    "orgMandateId": "APLMe5c9711f1ede1f5524e2fadb480386427",
    "pauseEnd": "2021/09/20",
    "pauseStart": "2021/09/20",
    "payeeMcc": "4121",
    "payeeName": "APLTEST",
    "payeeVpa": "abcd@apl",
    "payerName": "ABC",
    "payerRevocable": "true",
    "payerVpa": "xyz@apl",
    "recurrencePattern": "WEEKLY",
    "recurrenceRule": "BEFORE",
    "recurrenceValue": "3",
    "refUrl": "https://www.google.com",
    "remarks": "Sample Remarks",
    "role": "PAYER",
    "shareToPayee": "true",
    "transactionType": "UPI_MANDATE",
    "umn": "uniqueMandateNumber@apl",
    "validityEnd": "2020/12/25",
    "validityStart": "2020/08/20"
  },
  "udfParameters":"{}"
}

This API hits TSP Server with a timeout of 60 seconds.

This api can be used by Merchant for checking the status of the mandate for both Payer and Payee side. Using this API, the recent status of the mandate / (mandate action) can be found. Recent status of the mandate is denoted by gatewayResponseStatus field in the response if upiRequestId is not passed in the requestBody. Based on different scenarios gatewayResponseStatus can have multiple values like SUCCESS, FAILURE, REVOKED, PAUSED, COMPLETED, DECLINED, EXPIRED depending upon the current status of the mandate. Refer to table below for different value of gatewayResponseCode and gatewayResponseStatus. If upiRequestId is passed in the requestBody, then gatewayResponseStatus denotes the status of that particular action (UPDATE, REVOKE, PAUSE and UNPAUSE) taken on mandate.

Request parameters

Parameter	Description	Constraints
orgMandateId	gatewayMandateId returned in create mandate	35 character alphanumeric unique id
role	Defines the role of the customer in the mandate	PAYER, PAYEE
upiRequestId optional	gatewayMandateId returned for update, revoke, pause, unpause operations. It should not be passed for create mandate status and BAD_REQUEST error will be thrown.	35 character alphanumeric unique id
udfParameters optional	Stringified json for udf parameters.	String "udfParameters" : "{}"

Response parameters

Parameter	Description	Values
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
status	PSP status of the API	SUCCESS, FAILURE
amount	Amount for mandate	Amount in two decimals. Decimals are mandatory
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.	As passed for amountRule in create mandate.
bankAccountUniqueId optional	Unique id for the selected bank account. It will not be present if role passed in request is PAYEE and payeeVpa is of merchant.	bankAccountUniqueId in the response of Fetch Accounts api call.
blockFund	Denotes whether customer's fund should be blocked or not. True for recurring mandate, for ONETIME mandate can be true or false	true / false
expiry optional	Timestamp until which mandate request is valid. It will only be present if request is pending for approval for create mandate or update mandate.	Timestamp in YYYY-MM-DDTHH:MM:SS+05:30 format.
gatewayMandateId	UPI request id returned by gateway for the particular mandate / mandate action request	String
gatewayReferenceId	Customer reference number (rrn) for the mandate / mandate action operation.	String
gatewayResponseCode	Response code returned by gateway for the mandate / mandate action operation.	Refer table below.
gatewayResponseMessage	Response message returned by gateway for the mandate / mandate action operation.	String
gatewayResponseStatus	Denotes the current status of the mandate if upiRequestId is not passed in reqBody. Denotes the status of mandate action if upiRequestId is passed in reqBody.	SUCCESS, FAILURE, PENDING, REVOKED, PAUSED, COMPLETED, DECLINED, EXPIRED
initiatedBy	Defines who has initiated the mandate	PAYER, PAYEE
mandateApprovalTimestamp Optional	Time instant at which create mandate request was approved. Only present if mandate was initiatedBy PAYEE and upiRequestId is not passed in reqBody.	YYYY-MM-DDTHH:MM:SS+05:30.
mandateName	Name of the mandate	String
mandateTimestamp	Timestamp of when the mandate / mandate action was initiated	YYYY-MM-DDTHH:MM:SS+05:30
mandateType	Defines the type of mandate operation	CREATE, UPDATE, REVOKE, PAUSE, UNPAUSE
merchantChannelId	Unique id for the merchant channel.	As passed for x-merchant-channel-id in request headers.
merchantCustomerId optional	Merchant generated unique profile id for customer. It will not be present if role passed in request is PAYEE and payeeVpa is of merchant.	Alphanumeric string with dot(.). Maximum length is 256.
merchantId	Unique id for the merchant.	As passed for x-merchant-id in request headers
merchantRequestId	Merchant generated id for the mandate / mandate action request.	String
orgMandateId	Refers to upiRequestId used during creation of mandate.	Same as upiRequestId of create mandate.
pauseEnd optional	Defines the date on which the mandate should unpause. It will only be present if mandateType is PAUSE, UNPAUSE.	Date in "YYYY/MM/DD".
pauseStart optional	Defines the date from which the mandate should pause. It will only be present if mandateType is PAUSE, UNPAUSE.	Date in "YYYY/MM/DD".
payeeMcc	Merchant Category Code of the payee merchant.
payeeName optional	Name of the Payee involved in mandate. Only present if role is PAYER in request.	String
payeeVpa	VPA of payee.	String
payerName optional	Name of the Payer involved in mandate. Only present if role is PAYEE in request.
payerRevocable	Defines whether mandate is revocable by PAYER or not. Applicable only when it is ONETIME mandate and initiatedBy PAYEE	String - true,false
payerVpa	VPA of payer.	String
recurrencePattern	Recurrence Pattern for Mandate.	Same as original mandate in create mandate response.
recurrenceRule optional	Recurrence Rule for Mandate. It will not be present for ONETIME, DAILY and ASPRESENTED recurrence pattern.	Same as original mandate in create mandate response.
recurrencValue optional	Recurrence Value for Mandate. It will not be present for ONETIME, DAILY and ASPRESENTED recurrence pattern.	Same as original mandate in create mandate response.
refUrl	Invoice as sent by merchant or reference to the mandate in the form of url.	String. As passed during creation of mandate.
remarks	Any mandate summary	As passed during create mandate response.
role	Defines the role of the customer in the mandate	PAYER, PAYEE
shareToPayee	Descibes whether mandate will be shared with payee or not. Applicable only when it is ONETIME mandate and initiatedBy PAYER	String - true,false
transactionType	Type of Mandate Operation	UPI_MANDATE, QR_MANDATE, INTENT_MANDATE, P2M_MANDATE
udfParameters optional	Udf parameters as passed in the request.	As passed for udfParameters in request
umn optional	Unique Mandate Number used for execution of the mandate. It will not be present if mandate is pending for payer's approval.	String
validityEnd	Date before which mandate can be executed	YYYY/MM/DD.
validityStart	Date after which mandate can be executed	YYYY/MM/DD.

upiRequestId in reqBody	gatewayResponseCode	gatewayResponseStatus	Description
Present	00	SUCCESS	Mandate is in active state
Present	01	PENDING	Mandate is in pending state
Present	JPMR	REVOKED	Mandate is revoked
Present	JPMP	PAUSED	Mandate is paused
Present	JPMC	COMPLETED	Mandate is completed
Present	JPMD	DECLINED	Mandate is declined by payer
Present	JPMX	EXPIRED	Mandate is expried due to no action by payer
Not Present	01	PENDING	Respective Mandate Action is in pending state
Not Present	00	SUCCESS	Corresponding Message for Mandate Action
Present / Not Present	Else	FAILURE	Any other reason.

Check Notification Status

# Sample request

curl -X POST
-H "Content-Type: application/json"
-H 'x-merchant-channel-id: MERCHANTAPP'
-H 'x-merchant-signature: 823647862547652376452378456'
-H 'x-merchant-id: MERCHANT'
-H 'x-timestamp: 1496918882000'
-d '{
  "merchantRequestId": "TXN1234567",
  "udfParameters" : "{}",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa"
}' "{{host}}/api/a2/merchants/mandates/webNotify/status"

# The above command returns JSON structured like this:

{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "amount" : "10.22",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage" : "Your notification is successful",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
    "merchantChannelId" : "MERCHANTAPP",
    "merchantId" : "MERCHANT",
    "merchantRequestId" : "TXN1234567",
    "nextExecution" : "2017-06-09T17:57:49+05:30",
    "orgMandateId": "APL71f7d43bdf64d72d929734629",
    "umn" : "APL71f7d43bdf64d72d9csaddffs@upi",
  },
  "udfParameters":"{}"
}

This API hits TSP Server with a timeout of 60 seconds.

This api will be used Merchant for checking the status of the notification of the mandate.

Request parameters

Parameter	Description	Constraints
merchantRequestId	Merchant generated id for the Web Notify API	35 character alphanumeric unique id.
udfParameters optional	Stringified json for udf parameters.	String "udfParameters" : "{}"
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.

Response parameters

Parameter	Description	Values
status	Status of the API.	SUCCESS, FAILURE
responseCode	SUCCESS if call succeeded. Otherwise shows the error code.	Refer error code section
responseMessage	SUCCESS if call succeeded. Otherwise shows verbose error.	Refer error code section
amount	Amount for which merchant requested the mandate	As passed in request
gatewayResponseCode	Response code returned by gateway for the notification.	00.
gatewayResponseMessage	Response message returned by gateway for the transaction.	String.
gatewayResponseStatus	Response message returned by gateway for the notification.
gatewayTransactionId	upiRequestId as passed on request
merchantChannelId	Unique id for the channel via which request is made.	As passed in request.
merchantId	Unique id for merchant.	As passed in request.
merchantRequestId	35 character alphanumeric unique id.	As passed in request
nextExecution	Mandate execution time in minutes from current time	String with proper date format (YYYY-MM-DDTHH:MM:SS+05:30)
orgMandateId	gatewayMandateId returned in create mandate	As passed for gatewayMandateId in webMandate request.
udfParameters optional	Udf parameters as passed in the web mandate request.	As passed in request
umn	umn returned in create mandate callback	As passed in request

responseCode	responseMessage
SUCCESS	SUCCESS
INTERNAL_SERVER_ERROR	INTERNAL_SERVER_ERROR
BAD_REQUEST	Any Other Reason

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Your notification is successful .
01	PENDING	Your notification is in pending state.
Else	FAILURE	Any other reason.

Mandate Payer APIs

Create Mandate

# Sample request

curl -X POST
-H "Content-Type: application/json"
-H 'x-merchant-channel-id: TESTAPP'
-H 'x-merchant-signature: 823647862547652376452378456'
-H 'x-merchant-id: TEST'
-H 'x-timestamp: 1496918882000'
-d '{
  "amount": "100.0",
  "amountRule": "EXACT/MAX",
  "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
  "blockFund": "true",
  "credBlock": "{\"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|j+dtxs...1ca1o0CrjnUw==\",\"code\":\"NPCI\"}}}",
  "currency": "INR",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "expiry": "10",
  "initiatedBy": "PAYER",
  "makeAsync": "true",
  "mandateName": "Sample Name",
  "mcc": "0000",
  "merchantCustomerId": "JUS14081",
  "merchantRequestId": "b1a4418b4ac",
  "payeeVpa": "abcd@test",
  "payerRevocable": "true",
  "payerVpa": "xyz@test",
  "recipientName": "abcdefg",
  "recurrencePattern": "WEEKLY",
  "recurrenceRule": "BEFORE",
  "recurrenceValue": "2",
  "refUrl": "https://www.refUrl.com",
  "remarks": "Sample Remarks",
  "shareToPayee": "true",
  "transactionType": "UPI_MANDATE",
  "udfParameters": "{}",
  "upiRequestId": "APLMe5c9711f1ede1f5524e2fadb48003aa0",
  "validityEnd": "2019/09/20",
  "validityStart": "2019/09/08",
  "refCategory": "02",
  "transactionReference": "P1708071422508815250029",
  "purpose": "00",
  "initiationMode": "00",
  "packageName" : "in.amazon.mShop.android.shopping"
}' "{{host}}/api/n2/merchants/mandates/create"

# The above command returns JSON structured like this:

{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "amount": "100.00",
    "amountRule": "EXACT",
    "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
    "blockFund": "true",
    "currency": "INR"
    "expiry": "2020-12-24T14:17:06+05:30",
    "gatewayMandateId": "APLMe5c9711f1ede1f5524e2fadb48003aa0",
    "gatewayReferenceId": "806115044725",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Your transaction is successful",
    "gatewayResponseStatus": "SUCCESS",
    "initiatedBy": "PAYER",
    "makeAsync": "true",
    "mandateApprovalTimestamp" : "2017-06-09T17:58:49+05:30",
    "mandateName": "Sample Name",
    "mcc": "0000",
    "mandateTimestamp": "2018-12-24T14:17:06+05:30",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "DEMO-CUST-1234",
    "merchantId": "TEST",
    "merchantRequestId": "b1a4418b4ac",
    "orgMandateId": "APLMe5c9711f1ede1f5524e2f92648y03aa0"
    "payeeMcc": "4121",
    "payeeName": "APLTEST",
    "payeeVpa": "abcd@test",
    "payerName": "ABC",
    "payerRevocable": "true",
    "payerVpa": "xyz@test",
    "recurrencePattern": "WEEKLY",
    "recurrenceRule": "BEFORE",
    "recurrenceValue": "2",
    "refUrl": "https://www.refUrl.com",
    "remarks": "Sample Remarks",
    "role": "PAYER",
    "shareToPayee": "true",
    "transactionType": "UPI_MANDATE",
    "umn": "uniqueMandateNumber@test",
    "validityEnd": "2019/09/20",
    "validityStart": "2019/09/08",
    "refCategory": "02",
    "transactionReference": "P1708071422508815250029",
    "purpose": "00",
    "initiationMode": "00",
  },
  "udfParameters":"{}"
}

Below are some request parameters required to be handled specifically according to the mandate creation scenario.

Parameter	P2M Mandate	P2P Mandate (Payer Initiated)	P2P Mandate (Payee Initiated)	Scan & Pay	Incoming Intent
transactionType	P2M_MANDATE	UPI_MANDATE	UPI_MANDATE	QR_MANDATE	INTENT_MANDATE
payeeVpa	Mandatory	Mandatory	Mandatory	pa in deeplink url	pa in deeplink url
recipientName	Mandatory	Mandatory	Mandatory	pn in deeplink url	pn in deeplink url
mandateName	Mandatory	Mandatory	Mandatory	mn in deeplink url	mn in deeplink url
upiRequestId	Mandatory	Mandatory	Mandatory	tid in deeplink url	tid in deeplink tid
validityStart	Mandatory	Mandatory	Mandatory	validitystart in deeplink url	validitystart in deeplink url
validityEnd	Mandatory	Mandatory	Mandatory	validityend in deeplink url	validityend in deeplink url
amount	Mandatory	Mandatory	Mandatory	am in deeplink url	am in deeplink url
amountRule	Mandatory	Mandatory	Mandatory	amrule in deeplink url	amrule in deeplink url
recurrencePattern	Mandatory	Mandatory	Mandatory	recur in deeplink url	recur in deeplink url
recurrenceValue	Optional	Optional	Optional	recurvalue in deeplink url	recurvalue in deeplink url
recurrenceRule	Optional	Optional	Optional	recurtype in deeplink url	recurtype in deeplink url
transactionReference	Required for Intent & QR	Required for Intent & QR	Required for Intent & QR	tr in deeplink url	tr in deeplink url
refUrl	Optional	Optional	Optional	url in deeplink url	url in deeplink url
currency	Required for Intent & QR	Required for Intent & QR	Required for Intent & QR	cu in deeplink url	cu in deeplink url
mcc	Required for Intent & QR	Required for Intent & QR	Required for Intent & QR	mc in deeplink url	mc in deeplink url
remarks	Optional	Optional	Optional	tn in deeplink url	tn in deeplink url
initiationMode	Required for Intent & QR	Required for Intent & QR	Required for Intent & QR	mode in deeplink url	mode in deeplink url
purpose	Required for Intent & QR	Required for Intent & QR	Required for Intent & QR	purpose in deeplink url	purpose in deeplink url
refCategory	Required for Intent & QR	Required for Intent & QR	Required for Intent & QR	NA	NA
packageName optional	Package name of the UPI application	String

This API hits TSP Server with a timeout of 60 seconds.

This api will be used for creation of a mandate. It can be initiated by both Payer as well as Payee for mandate creation. There are following scenarios :

1. When Payee creates a mandate, it requires mandate approval from Payer side. Cred block is not required for this case.

2. When Payer creates a mandate, then cred block is required and no approval is required.

Request parameters

Parameter	Description	Constraints
amount	Amount for mandate	Amount in two decimals. Decimals are mandatory.
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.	MAX,EXACT
bankAccountUniqueId	Unique id for the selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call.
blockFund optional	Denotes whether customer's fund should be blocked or not. Only applicable for ONETIME mandate. For recurring mandate it should always be false, for onetime it can be true or false. If blockFund and payerRevocable are both send false for a request then request will be rejected. Default value is false.	String - true,false
credBlock optional	Encrypted credblock containing user mpin. It is required if mandate is initiatedBy Payer.	As returned by Common Library
currency optional	Currency code	String - INR
deviceFingerPrint optional	Device fingerprint of the customer. It is required if mandate is initiatedBy Payer.	String
expiry optional	Minutes for which request is valid. Only applicable if initiatedBy PAYEE	A numeric string between 2 to 64800 (both inclusive)
initiatedBy	Describes whether PAYER or PAYEE has initiated the create mandate request.	PAYER,PAYEE
makeAsync optional	Denotes whether the API call will be done in synchronous or asynchronous manner. If it is not passed by default API call will be in synchronous. It is not required if initiatedBy PAYEE as it will be default async as it required approval from Customer.	true,false
mandateName	Name of the mandate	String
mcc optional	Merchant category code	String
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
merchantRequestId	Merchant generated id for the mandate request	35 character alphanumeric unique id.
payeeVpa	Vpa of the payee.	Valid VPA
payerRevocable optional	Defines whether mandate is revocable by PAYER or not. Applicable only when it is ONETIME mandate and initiatedBy PAYEE. For recurring mandate it should always be true, for onetime it can be true or false. If blockFund and payerRevocable are both send false for a request then request will be rejected. Default value is true.	String - true/false.
payerVpa	Vpa of the payer.	Valid VPA
recipientName	Name against which mandate is triggered. If initiatedBy is PAYER then payeeName or vice-versa. If name is not present with merchant payerVpa can be sent.	String
recurrencePattern	Recurrence Pattern for Mandate. Denotes at what frequency mandate can be executed.	ONETIME, DAILY, WEEKLY, FORTNIGHTLY,MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED
recurrenceRule optional	Recurrence Rule for Mandate. It is not required for ONETIME, DAILY and ASPRENTED recurrencePattern.	ON, BEFORE, AFTER.
recurrencValue optional	Recurrence Value for Mandate. It is not required for ONETIME, DAILY and ASPRENTED recurrencePattern.	between 1-31 and depends on recurrencePattern.
refUrl optional	Reference url for the mandate. It is mainly kept for future purpose for invoice in inbox feature, if nothing is passed then a default value is set for this tag and same will be send back in response.	String
remarks optional	Any mandate summary	String
shareToPayee optional	Descibes whether mandate will be shared with payee or not. Required only when it is ONETIME mandate and initiatedBy PAYER. For recurring mandate it should always be true, for onetime it can be true or false. Default value is true.	String - true,false
transactionType	Type of Mandate Creation. UPI_MANDATE should be used for normal requests. QR_MANDATE should be used if mandate is created using QR. INTENT_MANDATE should be used if mandate is created using intent flow. P2M_MANDATE should be used if customer is directly creating a mandate with payeeVpa of merchant.	UPI_MANDATE, QR_MANDATE, INTENT_MANDATE, P2M_MANDATE
udfParameters optional	Stringified JSON for udf parameters	JSON string
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with a unique merchant prefix. Max length is 35.
validityEnd	Date before which mandate can be execute	String with proper date format YYYY/MM/DD
validityStart	Date after which mandate can be executed	String with proper date format YYYY/MM/DD
refCategory optional	Details for refUrl, whether it is 01 (advertisement), 02(Invoice). If nothing is passed, a default value of "00" is set up and same will be sent back in response.	Numeric String
transactionReference optional	Transaction reference id	String
purpose optional	Defines the purpose code of the mandate	Numeric String
initiateionMode optional	Defines the initiationMode of the mandate	Numeric String
umn optional	Unique mandate number. Only applicable for PAYER initiated mandate. If not passed, it is autogenerated.	String

Response parameters

Parameter	Description	Values
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
status	PSP status of the API	SUCCESS, FAILURE
amount	Amount for mandate	Numeric String with two decimals. As passed for amount in request.
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.	As passed for amountRule in request.
bankAccountUniqueId	Unique id for the selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call. As passed for bankAccountUniqueId in request.
blockFund	Defines whether customer's fund should be blocked or not. For onetime mandate it can be true or false. Default value is false.	String - true, false
expiry optional	Timestamp upto which mandate creation request is valid. It will only be present if mandate is initiated by PAYEE.	Timestamp in YYYY-MM-DDTHH:MM:SS+05:30 format, request timestamp plus expiry minutes passed in request.
gatewayMandateId	UPI request id returned by gateway for the mandate	As passed for upiRequestId in request
gatewayReferenceId	Customer reference number (rrn) for the mandate operation.	String
gatewayResponseCode	Response code returned by gateway for the mandate operation.	Refer table below.
gatewayResponseMessage	Response message returned by gateway for the mandate operation.	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
initiatedBy	Describes whether PAYER or PAYEE has initiated the mandate.	As passed for initiatedBy in request.
makeAsync optional	Denotes whether the API call will be done in synchronous or asynchronous manner	Only present if passed in reqBody and same value as in request.
mandateApprovalTimestamp Optional	Time instant at which create mandate request was approved. Only present if mandate type is create and approved.	YYYY-MM-DDTHH:MM:SS+05:30.
mandateName	Name of the mandate.	As passed for mandateName in request.
mandateTimestamp	Timestamp of when this request was attempted	YYYY-MM-DDTHH:MM:SS+05:30
merchantChannelId	Unique id for the merchant channel.	As passed for x-merchant-channel-id in request headers
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256. As passed for merchantCustomerId in request.
merchantId	Unique id for the merchant.	As passed for x-merchant-id in request headers
merchantRequestId	Merchant generated id for the mandate request.	As passed for merchantRequestId in request body.
orgMandateId	upiRequestId of the create request.	As passed for upiRequestId in the request.
payeeMcc	Merchant Category Code of the payee merchant.
payeeName optional	Name of the Payee involved in mandate.
payeeVpa	VPA of payee	As passed for payeeVpa in request
payerName optional	Name of the Payer involved in mandate.
payerRevocable	Defines whether mandate is revocable by PAYER or not. For onetime mandate it can be true or false. Default value is true.	String - true, false
payerVpa	VPA of payer	As passed for payerVpa in request
recurrencePattern	Recurrence Pattern for Mandate	As passed for recurrencePattern in request
recurrenceRule conditional	Recurrence Rule for Mandate. It will not be present for ONETIME, DAILY and ASPRESENTED recurrence pattern.	As passed for recurrenceRule in request
recurrencValue conditional	Recurrence Value for Mandate. It will not be present for ONETIME, DAILY and ASPRESENTED recurrence pattern.	As passed for recurrencValue in request.
refUrl	Reference url for the mandate. It will be same value if passed in request else it will be a default url.	String
remarks optional	Any mandate summary. If pssed in request, it will be same in response else a default value is send.	String
role	Role of the customer for this mandate.	PAYER, PAYEE
shareToPayee	Descibes whether mandate will be shared with payee or not. For onetime mandate it can be true or false. Default value is true.	String - true, false.
transactionType	Type of Mandate Creation	As passed for transactionType in request.
udfParameters optional	Udf parameters as passed in the request.	As passed for udfParameters in request
umn optional	Unique Mandate Number used for execution of the mandate. Will be sent only if mandate is initiated by Payer.	String
validityEnd	Date before which mandate can be executed.	As passed for validityEnd in request
validityStart	Date after which mandate can be executed.	As passed for validityStart in request

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Mandate Creation Success. / Mandate Create Request Sent Successfully
Z6	FAILURE	Number of pin tries exceeded.
ZM	FAILURE	Invalid mpin.
Else	FAILURE	Any other reason.

Update/Revoke Mandate

# Sample request

curl -X POST
-H "Content-Type: application/json"
-H 'x-merchant-channel-id: TESTAPP'
-H 'x-merchant-signature: 823647862547652376452378456'
-H 'x-merchant-id: TEST'
-H 'x-timestamp: 1496918882000'
-d '{
  "amount": "100.00",
  "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
  "credBlock": "{\"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|j+dtxs...1ca1o0CrjnUw==\",\"code\":\"NPCI\"}}}",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "expiry": "in minutes",
  "makeAsync": "true",
  "merchantCustomerId": "JUS14081",
  "merchantRequestId": "b1a4418b4ac",
  "orgMandateId": "APLMsleiuryufhuhsoisdjfadb48003sdaa0",
  "remarks": "Sample Remarks",
  "requestType": "UPDATE",
  "udfParameters": "{}",
  "upiRequestId": "APLMe5c9711f1ede1f5524e2fadb48003aa0",
  "validityEnd": "2019/09/20",
  "packageName" : "in.amazon.mShop.android.shopping"
}' "{{host}}/api/n2/merchants/mandates/update"

# The above command returns JSON structured like this:

{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "amount": "100.00",
    "amountRule": "EXACT",
    "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
    "blockFund": "true",
    "expiry": "2020-12-24T14:17:06+05:30",
    "gatewayMandateId": "APLMe5c9711f1ede1f5524e2fadb48003aa0",
    "gatewayReferenceId": "806115044725",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Your transaction is successful",
    "gatewayResponseStatus": "SUCCESS",
    "initiatedBy": "PAYER",
    "makeAsync": "true",
    "mandateName": "Sample Name",
    "mandateTimestamp": "2018-12-24T14:17:06+05:30",
    "mandateType" : "UPDATE",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "DEMO-CUST-1234",
    "merchantId": "TEST",
    "merchantRequestId": "b1a4418b4ac",
    "orgMandateId": "APLMsleiuryufhuhsoisdjfadb48003sdaa0",
    "payeeMcc": "4121",
    "payeeName": "APLTEST",
    "payeeVpa": "abcd@apl",
    "payerName": "ABC",
    "payerRevocable": "true",
    "payerVpa": "xyz@apl",
    "recurrencePattern": "WEEKLY",
    "recurrenceRule": "BEFORE",
    "recurrenceValue": "17",
    "refUrl": "https://www.google.com",
    "remarks": "Sample Remarks",
    "role": "PAYER",
    "shareToPayee": "true",
    "transactionType": "UPI_MANDATE",
    "umn": "uniqueMandateNumber@apl",
    "validityEnd": "2019/09/20",
    "validityStart": "2019/09/08"
  },
  "udfParameters":"{}"
}

This API hits TSP Server with a timeout of 60 seconds.

This api will be used for updating / revoking a mandate. requestType can be UPDATE or REVOKE.If requestType is UPDATE then the entity (PAYER/PAYEE) whoever has initiated the create mandate request can update the mandate. If mandate is updated by PAYER then credBlock is required and when it is updated by PAYEE then approval is required by PAYER. Only amount and validityEnd can be updated. If requestType is REVOKE then mandate will be revoked. If REVOKE request is initiated by PAYEE then credBlock is not required and vice-versa.

Request parameters

Parameter	Description	Constraints
amount conditional	Amount for mandate. Only required if amount needs to be updated for mandate and requestType is UPDATE. Either one of validityEnd or amount has to be passed.	Amount in two decimals. Decimals are mandatory.
bankAccountUniqueId optional	Unique id for the selected bank account. Should be same bankId used while create or approve mandate. It is not required when initiatedBy PAYEE.	String. As passed for bankAccountUniqueId in request.
credBlock optional	Encrypted credblock containing user mpin. It is required if mandate update or revoke is initiatedBy Payer	As returned by Common Library.
deviceFingerPrint optional	Device fingerprint of the customer. It is required if mandate update or revoke is initiatedBy Payer	String
expiry optional	Minutes for which request is valid. It is required only when requestType is UPDATE.	A number between 2 to 64800, both inclusive, in String format.
makeAsync optional	Denotes whether the API call will be done in synchronous or asynchronous manner. If it is not passed by default API call will be in synchronous. It is not required if initiatedBy PAYEE and requestType is UPDATE as it will be default async as it requires approval from Customer.	true,false
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
merchantRequestId	Merchant generated request id for the mandate operation.	35 character alphanumeric unique id.
orgMandateId	gatewayMandateId of the original mandate	String.
remarks optional	Any mandate summary	String
requestType	Type of mandate operation request. If requestType is UPDATE, mandate's validityEnd and amount can be updated. If requestType is REVOKE, mandate will be revoked.	UPDATE, REVOKE
udfParameters optional	Stringified json for udf parameters.	String "udfParameters" : "{}"
upiRequestId	Unique id passed to NPCI.	35 character alphanumeric. Should always start with a unique merchant prefix.
validityEnd conditional	Date before which mandate can be executed. Only required if validity end date needs to be updated for mandate and requestType is UPDATE. Either validityEnd or amount has to be passed.	String with proper date format YYYY/MM/DD
packageName optional	Package name of the UPI application	String

Response parameters

Parameter	Description	Values
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
status	PSP status of the API	SUCCESS, FAILURE
amount	Updated amount for mandate. If only validityEnd is updated then amount will be same as it was passed during creation of mandate.	Numeric String
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.	As passed for amountRule in create mandate.
bankAccountUniqueId	Unique id for the selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call. As passed for bankAccountUniqueId in request. If not send in the request then bankAccountUniqueId that was used during creation of mandate will be send.
blockFund	Denotes whether customer's fund should be blocked or not. For onetime mandate it can be true or false. Default value is false.	String - true,false
expiry optional	Timestamp upto which mandate updation request is valid. It will only be present if mandate updation is initiated by PAYEE.	Timestamp in YYYY-MM-DDTHH:MM:SS+05:30 format, request timestamp plus expiry minutes passed in request.
gatewayMandateId	UPI request id passed in request	As passed for upiRequestId in request
gatewayReferenceId	Customer reference number (rrn) for the mandate operation.	String
gatewayResponseCode	Response code returned by gateway for the mandate operation.	Refer to table below.
gatewayResponseMessage	Response message returned by gateway for the mandate operation.	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
initiatedBy	Describes whether PAYER or PAYEE has initiated the mandate operation request.	PAYER, PAYEE
makeAsync optional	Denotes whether the API call will be done in synchronous or asynchronous manner	Only present if passed in reqBody and same value as in request.
mandateName	Name of the mandate	String. As passed during creation of mandate.
mandateTimestamp	Timestamp of when this request was attempted.	(YYYY-MM-DDTHH:MM:SS+05:30)
mandateType	Defines the type of mandate request	UPDATE, REVOKE
merchantChannelId	Unique id for the merchant channel.	As passed for x-merchant-channel-id in request headers.
merchantCustomerId	Merchant generated unique id for customer.	Alphanumeric string with dot(.). Maximum length is 256. As passed for merchantCustomerId in request.
merchantId	Unique id for the merchant.	As passed for x-merchant-id in request headers
merchantRequestId	Merchant generated id for the mandate request.	As passed for merchantRequestId in request body.
orgMandateId	gatewayMandateId returned in create mandate	As passed for orgMandateId in request
payeeMcc	Merchant Category Code of the payee merchant.
payeeName optional	Name of the Payee involved in mandate.
payeeVpa	VPA of Payee.	String. As passed during creation of mandate.
payerName optional	Name of the Payer involved in mandate.
payerRevocable	Defines whether mandate is revocable by PAYER or not. For onetime mandate it can be true or false. Default value is true.	String - true,false
payerVpa	VPA of Payer.	String. As passed during creation of mandate.
recurrencePattern	Recurrence Pattern for Mandate	String. Same as original mandate in create or list mandate response.
recurrenceRule optional	Recurrence Rule for Mandate. It will not be present for ONETIME, DAILY and ASPRESENTED recurrence pattern.	Same as original mandate in create or list mandate response.
recurrencValue optional	Recurrence Value for Mandate. It will not be present for ONETIME, DAILY and ASPRESENTED recurrence pattern.	String. Same as original mandate in create or list mandate response.
refUrl	Invoice as sent by merchant or reference to the mandate in the form of url.	String. As passed during creation of mandate.
remarks	Any mandate summary. If pssed in request, it will be same in response else a default value is send.	String
role	Role of the customer for this mandate.	PAYER, PAYEE
shareToPayee	Descibes whether mandate will be shared with payee or not. For onetime mandate it can be true or false. Default value is true.	String - true,false
transactionType	Type of Mandate Operation	UPI_MANDATE, QR_MANDATE, INTENT_MANDATE, P2M_MANDATE
udfParameters optional	Udf parameters as passed in the request.	As passed for udfParameters in request.
umn	Unique Mandate Number used for execution of the mandate.	String
validityEnd	Updated date before which mandate can be executed. If only amount is updated then validityEnd will be same as it was passed during creation of mandate.	String with proper date format YYYY/MM/DD.
validityStart	Date after which mandate can be executed	String with proper date format YYYY/MM/DD

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Mandate Updation Success. / Mandate Update Request Sent Successfully
Z6	FAILURE	Number of pin tries exceeded.
ZM	FAILURE	Invalid mpin.
Else	FAILURE	Any other reason.

Approve/Decline Mandate

# Sample request

curl -X POST
-H "Content-Type: application/json"
-H 'x-merchant-channel-id: TESTAPP'
-H 'x-merchant-signature: 823647862547652376452378456'
-H 'x-merchant-id: TEST'
-H 'x-timestamp: 1496918882000'
-d '{
  "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
  "credBlock": "{\"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|j+dtxs...1ca1o0CrjnUw==\",\"code\":\"NPCI\"}}}",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "makeAsync": "true",
  "mandateRequestId": "APLMe5c9711f1ede1f5524e2fadb48003aa0",
  "merchantCustomerId": "JUS14081",
  "merchantRequestId": "b1a4418b4ac",
  "requestType": "APPROVE/DECLINE",
  "udfParameters": "{}",
  "packageName" : "in.amazon.mShop.android.shopping"
}' "{{host}}/api/n2/merchants/mandates/approve"

# The above command returns JSON structured like this:

{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "amount": "100.00",
    "amountRule": "EXACT",
    "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
    "blockFund": "true",
    "expiry": "2020-07-25T00:30:00+05:30",
    "gatewayMandateId": "APLMe5c9711f1ede1f5524e2fadb48003aa0",
    "gatewayReferenceId": "806115044725",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Mandate Create Approve Success",
    "gatewayResponseStatus": "SUCCESS",
    "initiatedBy": "PAYER",
    "makeAsync": "true",
    "mandateApprovalTimestamp" : "2017-06-09T17:58:49+05:30",
    "mandateName": "Sample Name",
    "mandateTimestamp": "2018-12-24T14:17:06+05:30",
    "mandateType": "CREATE",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "DEMO-CUST-1234",
    "merchantId": "TEST",
    "merchantRequestId": "b1a4418b4ac",
    "orgMandateId": "APLMsleiuryufhuhsoisdjfadb48003sdaa0",
    "payeeMcc": "4121",
    "payeeName": "APLTEST",
    "payeeVpa": "abcd@apl",
    "payerName": "ABC",
    "payerRevocable": "true",
    "payerVpa": "xyz@apl",
    "recurrencePattern": "WEEKLY",
    "recurrenceRule": "BEFORE",
    "recurrenceValue": "2",
    "refUrl": "https://www.google.com",
    "remarks": "Sample Remarks",
    "role": "PAYER",
    "shareToPayee": "true",
    "transactionType": "UPI_MANDATE",
    "umn": "uniqueMandateNumber@apl",
    "validityEnd": "2019/09/20",
    "validityStart": "2019/09/08"
},
  "udfParameters":"{}"
}

This API hits TSP Server with a timeout of 60 seconds.

This api is to review and take some action on a pending mandate request. requestType can be APPROVE or DECLINE. If requestType is APPROVE, then bankAccountUniqueId and credBlock parameters are mandatory. A mandate request approve is success if gatewayResponseCode is 00. A mandate request decline is success if gatewayResponseCode is ZA if action is against a create mandate request and gatewayResponseCode is QT if action is against an update mandate. The gatewayResponseStatus for a successful decline will be DECLINED.

Request parameters

Parameter	Description	Constraints
bankAccountUniqueId optional	Unique id for the selected bank account. Should always use the same account for all operations of a single mandate. It is only required when requestType is APPROVE.	bankAccountUniqueId in the response of Fetch Accounts api call.
credBlock optional	Encrypted credblock containing user mpin. It is required when requestType is APPROVE.	As returned by Common Library
deviceFingerPrint optional	Device fingerprint of the customer. It is required when requestType is APPROVE.	String
makeAsync optional	Denotes whether the API call will be done in synchronous or asynchronous manner. If it is not passed by default API call will be in synchronous.	true,false
mandateRequestId	upiRequestId used during create or update mandate based on whether create or update mandate request is getting approved.	String
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
merchantRequestId	Merchant generated id for the mandate request	35 character alphanumeric unique id.
requestType	Action to be taken on the mandate request	APPROVE or DECLINE
udfParameters optional	Stringified json for udf parameters.	String "udfParameters" : "{}"
umn optional	Required when requestType is APPROVE and the umn of the mandate to be approved is null. Sets the umn of the mandate.	String
packageName optional	Package name of the UPI application	String

Response parameters

Parameter	Description	Values
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
status	PSP status of the API	SUCCESS, FAILURE
amount	Updated Amount for mandate	Amount in two decimals. Decimals are mandatory. As passed during creation of mandate.
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.	As passed for amountRule in create mandate.
bankAccountUniqueId optional	Unique id for the selected bank account. It will not be present if requestType is DECLINE.	bankAccountUniqueId in the response of Fetch Accounts api call. As passed for bankAccountUniqueId in request.
blockFund	Denotes whether customer's fund should be blocked or not. For onetime mandate it can be true or false. Default value is false.	String - true,false
expiry	Timestamp until which mandate request is valid	Timestamp in YYYY-MM-DDTHH:MM:SS+05:30 format.
gatewayMandateId	UPI request id passed in request	As passed for upiRequestId in request
gatewayReferenceId	Customer reference number (rrn) for the mandate operation.	String
gatewayResponseCode	Response code returned by gateway for the mandate operation.	Refer to table below.
gatewayResponseMessage	Response message returned by gateway for the mandate operation.	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE, DECLINED
initiatedBy	Describes whether PAYER or PAYEE has initiated the mandate operation request.	PAYER, PAYEE
makeAsync optional	Denotes whether the API call will be done in synchronous or asynchronous manner	Only present if passed in reqBody and same value as in request.
mandateApprovalTimestamp Optional	Time instant at which create mandate request was approved. Only present if mandate type is create and approved.	YYYY-MM-DDTHH:MM:SS+05:30.
mandateName	Name of the mandate	String. As passed during creation of mandate.
mandateTimestamp	Timestamp of when this request was created.	(YYYY-MM-DDTHH:MM:SS+05:30)
mandateType	Defines the type of mandate	CREATE, UPDATE
merchantChannelId	Unique id for the merchant channel.	As passed for x-merchant-channel-id in request headers.
merchantCustomerId	Merchant generated unique id for customer.	Alphanumeric string with dot(.). Maximum length is 256. As passed for merchantCustomerId in request.
merchantId	Unique id for the merchant.	As passed for x-merchant-id in request headers
merchantRequestId	Merchant generated id for the mandate request.	As passed for merchantRequestId in request body.
orgMandateId	gatewayMandateId returned in create mandate.	String
payeeMcc	Merchant Category Code of the payee merchant.
payeeName optional	Name of the Payee involved in mandate.
payeeVpa	VPA of Payee.	String. As passed during creation of mandate.
payerName optional	Name of the Payer involved in mandate.
payerRevocable	Defines whether mandate is revocable by PAYER or not. For onetime mandate it can be true or false. Default value is true.	String - true,false
payerVpa	VPA of Payer.	String. As passed during creation of mandate.
recurrencePattern	Recurrence Pattern for Mandate	String. Same as original mandate in create or list mandate response.
recurrenceRule optional	Recurrence Rule for Mandate. It will not be present for ONETIME, DAILY and ASPRESENTED recurrence pattern.	Same as original mandate in create or list mandate response.
recurrencValue optional	Recurrence Value for Mandate. It will not be present for ONETIME, DAILY and ASPRESENTED recurrence pattern.	String. Same as original mandate in create or list mandate response.
refUrl	Invoice as sent by merchant or reference to the mandate in the form of url.	String. As passed during creation of mandate.
remarks	Any mandate summary. It will be the same value that was used during create mandate response.	String
role	Role of the customer for this mandate.	PAYER, PAYEE
shareToPayee	Descibes whether mandate will be shared with payee or not. For onetime mandate it can be true or false. Default value is true.	String - true,false
transactionType	Type of Mandate Operation	UPI_MANDATE, QR_MANDATE, INTENT_MANDATE, P2M_MANDATE
udfParameters optional	Udf parameters as passed in the request.	As passed for udfParameters in request.
umn	Unique Mandate Number used for execution of the mandate.	String
validityEnd	Date before which mandate can be executed.	String with proper date format YYYY/MM/DD
validityStart	Date after which mandate can be executed	String with proper date format YYYY/MM/DD

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Mandate Approve Success / Mandate Approve Request Sent Successfully.
ZA	DECLINED	Create Mandate Decline Success.
QT	DECLINED	Update Mandate Decline Success.
Z6	FAILURE	Number of pin tries exceeded.
ZM	FAILURE	Invalid mpin.
Else	FAILURE	Any other reason.

Pause/Unpause Mandate

# Sample request

curl -X POST
-H "Content-Type: application/json"
-H 'x-merchant-channel-id: TESTAPP'
-H 'x-merchant-signature: 823647862547652376452378456'
-H 'x-merchant-id: TEST'
-H 'x-timestamp: 1496918882000'
-d '{
  "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
  "credBlock": "{\"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|j+dtxs...1ca1o0CrjnUw==\",\"code\":\"NPCI\"}}}",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "merchantCustomerId": "JUS14081",
  "merchantRequestId": "71236761237",
  "orgMandateId": "APLMsleiuryufhuhsoisdjfadb48003sdaa0",
  "pauseEnd": "2019/09/19",
  "pauseStart": "2019/09/17",
  "remarks": "Sample Remarks",
  "requestType": "PAUSE",
  "udfParameters": "{}",
  "upiRequestId": "APLMe5c9711f1ede1f5524e2fadb48003aa0",
  "packageName" : "in.amazon.mShop.android.shopping"
}' "{{host}}/api/n2/merchants/mandates/pause"

# The above command returns JSON structured like this:

{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "amount": "100.00",
    "amountRule": "EXACT",
    "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
    "blockFund": "true",
    "gatewayMandateId": "APLMe5c9711f1ede1f5524e2fadb48003aa0",
    "gatewayReferenceId": "806115044725",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Your transaction is successful",
    "gatewayResponseStatus": "SUCCESS",
    "initiatedBy": "PAYER",
    "mandateName": "Sample Name",
    "mandateTimestamp": "2018-12-24T14:17:06+05:30",
    "mandateType" : "PAUSE",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "DEMO-CUST-1234",
    "merchantId": "TEST",
    "merchantRequestId": "b1a4418b4ac",
    "orgMandateId": "APLMsleiuryufhuhsoisdjfadb48003sdaa0",
    "pauseEnd": "2019/09/19",
    "pauseStart": "2019/09/17",
    "payeeMcc": "4121",
    "payeeName": "APLTEST",
    "payeeVpa": "abcd@apl",
    "payerName": "ABC",
    "payerRevocable": "true",
    "payerVpa": "xyz@apl",
    "recurrencePattern": "WEEKLY",
    "recurrenceRule": "BEFORE",
    "recurrenceValue": "17",
    "refUrl": "https://www.google.com",
    "remarks": "Sample Remarks",
    "role": "PAYER",
    "shareToPayee": "true",
    "transactionType": "UPI_MANDATE",
    "umn": "uniqueMandateNumber@apl",
    "validityEnd": "2019/09/20",
    "validityStart": "2019/09/08"
  },
  "udfParameters":"{}"
}

This API hits TSP Server with a timeout of 60 seconds.

This api will be used for PAUSE/UNPAUSE an active mandate. requestType can be PAUSE or UNPAUSE. If requestType is PAUSE then pauseStart, pauseEnd are required. pauseStart and pauseEnd are not required when requestType is UNPAUSE. Pause and Unpause request can always be initiatedBy Payer. credBlock is required for both during PAUSE and UNPAUSE.

Request parameters

Parameter	Description	Constraints
bankAccountUniqueId	Unique id for the selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call.
credBlock	Encrypted credblock containing user mpin	As returned by Common Library
deviceFingerPrint	Device fingerprint of the customer	String
makeAsync optional	Denotes whether the API call will be done in synchronous or asynchronous manner. If it is not passed by default API call will be in synchronous.	true,false
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
merchantRequestId	Merchant generated id for the mandate	35 character alphanumeric unique id.
orgMandateId	gatewayMandateId returned during create mandate	String and it should be corresponding Upi Request id used during create mandate.
pauseEnd optional	Defines the date on which the mandate should unpause. Only required when requestType is PAUSE	Date in "YYYY/MM/DD".
pauseStart optional	Defines the date from which the mandate should pause. Only required when requestType is PAUSE	Date in "YYYY/MM/DD".
remarks optional	Any mandate summary	String
requestType	Type of Mandate Request	PAUSE, UNPAUSE.
udfParameters optional	Stringified json for udf parameters.	String "udfParameters" : "{}"
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with a unique merchant prefix.
packageName optional	Package name of the UPI application	String

Response parameters

Parameter	Description	Values
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
status	PSP status of the API	SUCCESS, FAILURE
amount	Amount for mandate	Amount in two decimals. Decimals are mandatory. As passed during creation of mandate.
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.	As passed for amountRule in create mandate.
bankAccountUniqueId	Unique id for the selected bank account as passed in request. It should be same as the one that was used during creation of mandate.	bankAccountUniqueId in the response of Fetch Accounts api call.
blockFund	Denotes whether customer's fund should be blocked or not. For onetime mandate it can be true or false. Default value is false.	String - true, false
gatewayMandateId	upiRequestId passed in the request.	As passed for upiRequestId in request.
gatewayReferenceId	Customer reference number (rrn) for the mandate operation.	String
gatewayResponseCode	Response code returned by gateway for the mandate operation.	Refer table below.
gatewayResponseMessage	Response message returned by gateway for the mandate operation.	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
initiatedBy	Describes whether PAYER or PAYEE has initiated the mandate operation request.	PAYER, PAYEE
makeAsync optional	Denotes whether the API call will be done in synchronous or asynchronous manner	Only present if passed in reqBody and same value as in request.
mandateName	Name of the mandate	String. As passed during creation of mandate.
mandateTimestamp	Timestamp of when this request was attempted.	(YYYY-MM-DDTHH:MM:SS+05:30)
mandateType	Defines the type of mandate request	UPDATE, REVOKE
merchantChannelId	Unique id for the merchant channel.	As passed for x-merchant-channel-id in request headers
merchantCustomerId	Merchant generated unique id for customer.	Alphanumeric string with dot(.). Maximum length is 256. As passed for merchantCustomerId in the request.
merchantId	Unique id for the merchant.	As passed for x-merchant-id in request headers
merchantRequestId	Merchant generated id for the mandate request.	As passed for merchantRequestId in request body.
orgMandateId	gatewayMandateId returned in create mandate	As passed for orgMandateId in request.
pauseEnd optional	Defines the date on which the mandate should unpause. It will only be present if requestType is PAUSE.	As passed in request.
pauseStart optional	Defines the date from which the mandate should pause. It will only be present if requestType is PAUSE.	As passed in request.
payeeMcc	Merchant Category Code of the payee merchant.
payeeName optional	Name of the Payee involved in mandate.
payeeVpa	VPA of Payee.	String. As passed during creation of mandate.
payerName optional	Name of the Payer involved in mandate.
payerRevocable	Defines whether mandate is revocable by PAYER or not. For onetime mandate it can be true or false. Default value is true.	String - true,false
payerVpa	VPA of Payer.	String. As passed during creation of mandate
recurrencePattern	Recurrence Pattern for Mandate.	Same as original mandate in create or list mandate response
recurrenceRule optional	Recurrence Rule for Mandate. It will not be present for ONETIME, DAILY and ASPRESENTED recurrence pattern.	Same as original mandate in create or list mandate response.
recurrencValue optional	Recurrence Value for Mandate. It will not be present for ONETIME, DAILY and ASPRESENTED recurrence pattern.	Same as original mandate in create or list mandate response.
refUrl	Invoice as sent by merchant or reference to the mandate in the form of url.	String. As passed during creation of mandate.
remarks	Any mandate summary. If pssed in request, it will be same in response else a default value is send.	String
role	Role of the customer for this mandate.	PAYER, PAYEE
shareToPayee	Descibes whether mandate will be shared with payee or not. For onetime mandate it can be true or false. Default value is true.	String - true,false
transactionType	Type of Mandate Operation	UPI_MANDATE, QR_MANDATE, INTENT_MANDATE, P2M_MANDATE
udfParameters optional	Udf parameters as passed in the request.	As passed for udfParameters in request
umn	Unique Mandate Number used for execution of the mandate.	String
validityEnd	Date before which mandate can be executed	Date in "YYYY/MM/DD"
validityStart	Date after which mandate can be executed	Date in "YYYY/MM/DD"

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Mandate Pause/Unpause Success / Mandate Pause/Unpause Request Sent Successfully.
Z6	FAILURE	Number of pin tries exceeded.
ZM	FAILURE	Invalid mpin.
Else	FAILURE	Any other reason.

List Mandate

# Sample request

curl -X POST
-H "Content-Type: application/json"
-H 'x-merchant-channel-id: TESTAPP'
-H 'x-merchant-signature: 823647862547652376452378456'
-H 'x-merchant-id: TEST'
-H 'x-timestamp: 1496918882000'
-d '{
  "limit": "20",
  "merchantCustomerId": "DEMO-CUST-1234",
  "offset": "5",
  "status": "PENDING",
  "udfParameters": "{}"
}' "{{host}}/api/n2/merchants/mandates/list"

# The above command returns JSON structured like this:

{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "merchantCustomerId" : "DEMO-CUST-1234",
  "payload": {
    "merchantChannelId": "TESTAPP",
    "merchantId": "TEST",
    "mandates": [
      {
        "amount": "100.00",
        "amountRule": "EXACT",
        "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
        "blockFund": "true",
        "expiry": "2020-12-24T14:17:06+05:30",
        "gatewayMandateId": "APLMe5c9711f1ede1f5524e2fadb48003aa0",
        "gatewayReferenceId": "806115044725",
        "gatewayResponseCode": "00",
        "gatewayResponseMessage": "Mandate is Successfully revoked",
        "gatewayResponseStatus": "SUCCESS",
        "initiatedBy": "PAYER",
        "isMarkedSpam": "true",
        "isVerifiedPayee": "true",
        "mandateApprovalTimestamp": "2017-06-09T18:57:49+05:30",
        "mandateName": "Sample Name",
        "mandateTimestamp": "2018-12-24T14:17:06+05:30",
        "mandateType": "CREATE",
        "merchantCustomerId": "APL123",
        "merchantRequestId": "b1a4418b4ac",
        "orgMandateId": "APLMe5c9711f1ede1f5524e2fadb48003aa0",
        "payeeMcc": "4121",
        "payeeName": "APLTEST",
        "payeeVpa": "abcd@apl",
        "payerName": "ABC",
        "payerRevocable": "true",
        "payerVpa": "xyz@apl",
        "recurrencePattern": "WEEKLY",
        "recurrenceRule": "BEFORE",
        "recurrenceValue": "3",
        "refUrl": "https://www.google.com",
        "remarks": "Sample Remarks",
        "role": "PAYER",
        "shareToPayee": "true",
        "transactionType": "UPI_MANDATE",
        "umn": "uniqueMandateNumber@apl",
        "validityEnd": "2020/12/25",
        "validityStart": "2020/08/20"
      }
    ]
  }
  "udfParameters" : "{}"
}

This API hits TSP Server with a timeout of 60 seconds.

This api will be used for getting all the mandates with the requested status. status PENDING means all the mandate requests that requires action. ONGOING mandates means all the mandates that are currently in active state.

COMPLETED means either ONETIME mandate is executed or validityEnd over for the mandate.

PAUSED means the mandate that are currently paused.

INACTIVE means the mandate that are in FAILURE, EXPIRED, DECLINED, etc.

This API returns an array of mandates for the status as passed in the request.

Request parameters

Parameter	Description	Constraints
limit optional	limits the number of mandates	Numeric String
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
offset optional	leaves that many number of mandates starting from the beginning	Numeric String
status	status for which mandates should be listed. PENDING means all the mandate requests that requires action. ONGOING mandates means all the mandates that are currently in active state. COMPLETED means mandate that is either executed for ONETIME mandate or validityEnd over for the mandate. PAUSED means the mandate that are currently paused. INACTIVE means the mandate that are in FAILURE, EXPIRED, DECLINED, etc.	PENDING, ONGOING, COMPLETED, PAUSED, INACTIVE.
udfParameters optional	Stringified json for udf parameters	String

Response parameters

Parameter	Description	Values
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
status	PSP status of the API	SUCCESS, FAILURE
amount	Amount for mandate	Amount in two decimals. Decimals are mandatory
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.	As passed for amountRule in create mandate.
bankAccountUniqueId	Unique id for the selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call.
blockFund	Denotes whether customer's fund should be blocked or not. For onetime mandate it can be true or false. Default value is false.	String - true, false
expiry optional	Timestamp until which mandate request is valid. It will only be present if request is pending for approval for create or update mandate.	Timestamp in YYYY-MM-DDTHH:MM:SS+05:30 format.
gatewayMandateId	UPI request id returned by gateway for the particular mandate request	String
gatewayReferenceId	Customer reference number (rrn) for the mandate operation.	String
gatewayResponseCode	Response code returned by gateway for the mandate operation.	Refer table below.
gatewayResponseMessage	Response message returned by gateway for the mandate operation.	String
gatewayResponseStatus	When status is passed as PENDING it can denote status of create or update pending requests otherwise it denotes the current status of the mandate.	SUCCESS, FAILURE, PENDING, REVOKED, PAUSED, COMPLETED, DECLINED, EXPIRED
initiatedBy	Defines who has initiated the mandate request.	PAYER, PAYEE
isMarkedSpam optional	Flag if the payeeVpa is marked as spam. It will be present if and only if gatewayResponseStatus is PENDING and mandateType is CREATE.	true, false
isVerifiedPayee optional	Flag if the payeeVpa is a verified vpa. It will be present if and only if gatewayResponseStatus is PENDING and mandateType is CREATE.	true, false
mandateApprovalTimestamp Optional	Time instant at which create mandate request was approved. Only present if mandate was initiatedBy PAYEE.	YYYY-MM-DDTHH:MM:SS+05:30.
mandateName	Name of the mandate	String
mandateTimestamp	Timestamp of when the mandate request was initiated. When status is passed as PENDING in request it can be the timestamp of when create or update mandate request was initiated depending on the mandateType field , but for every other status it will be timestamp of when mandate was created.	YYYY-MM-DDTHH:MM:SS+05:30.
mandateType	Defines the type of mandate	CREATE, UPDATE
merchantChannelId	Unique id for the merchant channel.	As passed for x-merchant-channel-id in request headers.
merchantCustomerId	Merchant generated unique id for customer.	Alphanumeric string with dot(.). Maximum length is 256. As passed for merchantCustomerId in request.
merchantId	Unique id for the merchant.	As passed for x-merchant-id in request headers
merchantRequestId optional	Merchant generated id for the mandate request. It will not be present if status is passed as PENDING as initiatedBy is PAYEE.	As passed for merchantRequestId in request body.
orgMandateId	Refers to upiRequestId used during creation of mandate.	Same as upiRequestId of create mandate.
payeeMcc	Merchant Category Code of the payee merchant.
payeeName optional	Name of the Payee involved in mandate.
payeeVpa	VPA of payee.	String
payerName optional	Name of the Payer involved in mandate.
payerRevocable	Defines whether mandate is revocable by PAYER or not. For onetime mandate it can be true or false. Default value is true.	String - true,false
payerVpa	VPA of payer.	String
recurrencePattern	Recurrence Pattern for Mandate.	Same as original mandate in create mandate response.
recurrenceRule optional	Recurrence Rule for Mandate. It will not be present for ONETIME, DAILY and ASPRESENTED recurrence pattern.	Same as original mandate in create mandate response.
recurrencValue optional	Recurrence Value for Mandate. It will not be present for ONETIME, DAILY and ASPRESENTED recurrence pattern.	Same as original mandate in create mandate response.
refUrl	Invoice as sent by merchant or reference to the mandate in the form of url.	String. As passed during creation of mandate.
remarks	Any mandate summary	As passed during mandate operation request.
role	Defines the role of the customer in the mandate	PAYER, PAYEE
shareToPayee	Descibes whether mandate will be shared with payee or not. For onetime mandate it can be true or false. Default value is true.	String - true,false
transactionType	Type of Mandate Operation	UPI_MANDATE, QR_MANDATE, INTENT_MANDATE, P2M_MANDATE
udfParameters optional	Udf parameters as passed in the request.	As passed in request
umn optional	Unique Mandate Number used for execution of the mandate. It will not be present if mandate is pending for payer approval and payee's merchantCustomerId is passed in the request.	String
validityEnd	Date before which mandate can be executed	YYYY/MM/DD.
validityStart	Date after which mandate can be executed	YYYY/MM/DD.

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Mandate is in active state
01	PENDING	Mandate is in pending state
JPMR	REVOKED	Mandate is revoked
JPMP	PAUSED	Mandate is paused
JPMC	COMPLETED	Mandate is completed
JPMD	DECLINED	Mandate is declined by payer
JPMX	EXPIRED	Mandate is expried due to no action by payer
Else	FAILURE	Any other reason.

Webhooks and Callbacks

Headers

{
  "content-type": "application/json",
  "x-merchant-payload-signature": "26b339a48db62a..."
}

All the callbacks we send will have following headers.

Header Name	Header Value
content-type	application/json
x-merchant-payload-signature	This is a signature over the payload. Refer Signature Validation section for more details.

Signature Validation

String input = RequestBody in String UTF-8 encoding
String signature = headers["x-merchant-payload-signature"]

Signature rsa = Signature.getInstance("SHA256withRSA");
rsa.initVerify(getPublic(keyFile));
rsa.update(input.getBytes("utf-8"));

boolean isSignatureSame = rsa.verify(Hex.decode(signature));

At the time of onboarding, PSP will share a public key with the merchant. The algorithm used for creating the signature is SHA256 RSA with PSS padding. Following snippet shows how merchant has to validate the signature at their end.

Note

1. The keys in request JSON body will be in alphabetically sorted order.
2. Merchants are required to share the callback URLs and whitelist the PSP IP from which callbacks will be sent.

Registraion API Callbacks

Device Binding

{
  "customerMobileNumber": "919988776655",
  "customResponse": "{}",
  "merchantChannelId": "TESTAPP",
  "merchantCustomerId": "test-merchantcustomer-1",
  "merchantId": "TEST",
  "smsContent": "UPIACT ad56ef90396348bac56099"
  "status": "VERIFIED",
  "type": "CUSTOMER_DEVICE_BINDING"
}

This callback will be sent to merchant when the PSP receives a confirmation from the VMN aggregator on the customer mobile number and sms token.

status	Description
VERIFIED	Confirmation recieved from VMN ontime. Merchant can call Bind Device API to complete the device binding process.
DECLINED	Device binding process declined due to fraud.
EXPIRED	Confirmation recieved from VMN was delayed. Device binding expired.

Transaction API Callbacks

Incoming Money to Merchant - Collect Status

# A callback with following POST data will be sent to the endpoint configured for "MERCHANT_CREDITED_VIA_COLLECT"

{
  "amount": "100.00",
  "autoUpdateNote" : "TCC|102",
  "customResponse": "{}",
  "expiry": "2016-11-25T00:10:00+05:30",
  "gatewayPayerResponseCode": "00",
  "gatewayPayeeResponseCode": "00",
  "gatewayPayerReversalResponseCode": "00",
  "gatewayPayeeReversalResponseCode": "00",
  "gatewayReferenceId": "806115044725",
  "gatewayResponseCode": "00",
  "gatewayResponseMessage": "Transaction is approved",
  "gatewayResponseStatus": "SUCCESS",
  "gatewayTransactionId": "XYZd0c077f39c454979...",
  "gstAmount": "0.54",
  "mdrAmount": "3.00",
  "merchantChannelId": "DEMOUATAPP",
  "merchantId": "DEMOUAT01",
  "merchantRequestId": "TXN1234567",
  "netSettlementAmount": "96.46",
  "payeeMcc": "4121",
  "payeeVpa" : "merchant@abc",
  "payerAccBin" : "6071530000",
  "payerActype" : "CREDIT"
  "payerIfsc" : "BankIFSC",
  "payerMerchantCustomerId": "DEMO-CUST-5678"
  "payerName": "Customer Name",
  "payerVpa": "customer@xyz",
  "refUrl": "https://www.abcxyz.com/",
  "riskScore": "00979",
  "transactionTimestamp": "2016-11-25T00:00:00+05:30",
  "type": "MERCHANT_CREDITED_VIA_COLLECT",
  "udfParameters": "{}"
}

This callback is given when a collect request is initiated from merchant website or app and the same gets approved/declined/expired by a upi user.

Note: This callback is also sent after mandate execution instead of the MERCHANT_OUTGOING_EXECUTE_MANDATE if the merchantFlag merchantCreditedViaCollectForMandateExecute is set to true.

Parameter	Description
amount	Amount for which merchant initiated the collect request.
autoUpdateNote optional	adjFlag and adjCode separated by "|"
customResponse	Stringified JSON parameter for future use.
expiry	Expiry timestamp for the collect request.
gatewayPayerResponseCode optional	Response code returned by gateway
gatewayPayeeResponseCode optional	Response code returned by gateway
gatewayPayerReversalResponseCode optional	Response code returned by gateway
gatewayPayeeReversalResponseCode optional	Response code returned by gateway
gatewayReferenceId	Customer reference number (rrn) for the transaction.
gatewayResponseCode	Response code returned by gateway for the transaction. Refer below.
gatewayResponseMessage	Verbose response message returned by gateway for the transaction.
gatewayResponseStatus	Response status returned by gateway
gatewayTransactionId	UPI request id returned by gateway for the transaction.
gstAmount	Gst applied on the MDR charged
mdrAmount	MDR applied on the total transaction amount
merchantChannelId	Unique id for the channel via which request is made.
merchantId	Unique id for merchant.
merchantRequestId	Merchant generated request id as passed in web collect request.
netSettlementAmount	Net amount which needs to be settled (netSettlementAmount = txnAmount - (mdrAmount + gstAmount))
payeeMcc	Merchant Category Code of the payee merchant.
payeeVpa	Vpa of the merchant who initiated the collect request.
payerAccBin optional	Only if payerActype = "CREDIT" , will share 10 digits bin of the credit account .If BIN is 6 digits, then remaining 4 digits shall be zero. If BIN is 8 digits, then remaining 2 digits will be zero.
payerActype optional	Account type of the customer who received the payment.
payerIfsc optional	Account's ifsc of the customer who received the payment.
payerMerchantCustomerId optional	Merchant generated unique id for customer who received the collect request. Only if it is an onus transaction.
payerName optional	Name of the upi user who received the collect request. Only if gatewayResponseCode is "00".
payerVpa	Vpa of the upi user who received the collect request.
refUrl	Invoice as sent by merchant or reference to the transaction in the form of url.
riskScore optional	RiskScore shared by NPCI or Bank
seqNumber	optional
transactionTimestamp	Timestamp of when the web collect was initiated. (YYYY-MM-DDTHH:MM:SS+05:30)
type	Event type of the callback - MERCHANT_CREDITED_VIA_COLLECT.
udfParameters optional	Udf parameters as passed in the web collect request.
umn optional	Umn of the mandate. Will be received only during mandate execution.

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Payment Success.
01	PENDING	Payment is in pending state.
ZA	DECLINED	Decline Success.
U69	EXPIRED	Collect request expired.
Else	FAILURE	Any other reason.

Incoming Money to Merchant - Pay

# A callback with following POST data will be sent to the endpoint configured for "MERCHANT_CREDITED_VIA_PAY"

{
  "amount": "100.00",
  "splitDetails": [{"name": "TIPS", "value": "1.00"}, {"name": "CCONFEE", "value": "1.00"}, {"name": "PCONFEE", "value": "1.00"}],
  "autoUpdateNote" : "TCC|102",
  "customResponse": "{}",
  "gatewayPayerResponseCode": "00",
  "gatewayPayeeResponseCode": "00",
  "gatewayPayerReversalResponseCode": "00",
  "gatewayPayeeReversalResponseCode": "00",
  "gatewayReferenceId": "806115044725",
  "gatewayResponseCode": "00",
  "gatewayResponseMessage": "Transaction is approved",
  "gatewayResponseStatus": "SUCCESS",
  "gatewayTransactionId": "XYZd0c077f39c454979...",
  "gstAmount": "0.54",
  "mdrAmount": "3.00",
  "merchantChannelId": "DEMOUATAPP",
  "merchantId": "DEMOUAT01",
  "merchantRequestId": "TXN1234567",
  "netSettlementAmount": "96.46",
  "payeeMcc": "4121",
  "payeeVpa" : "merchant@abc",
  "payerAccBin" : "6071530000",
  "payerActype" : "CREDIT"
  "payerIfsc" : "BankIFSC",
  "payerMerchantCustomerId": "DEMO-CUST-5678",
  "payerName": "Customer Name",
  "payerVpa": "customer@xyz",
  "refUrl": "https://www.abcxyz.com/",
  "riskScore": "00979",
  "transactionTimestamp": "2016-11-25T00:00:00+05:30",
  "type": "MERCHANT_CREDITED_VIA_PAY",
  "subMerchantId": "SUBMERCHANT01",
  "subMerchantChannelId": "SUBMERCHANTAPP",
  "udfParameters": "{}"
}

This callback is given to merchant when a customer pays for his order on merchant app using the sdk pay api.

Parameter	Description
amount	Amount for the transaction.
splitDetails optional	Supplementary Expenses involved in the transaction
autoUpdateNote optional	adjFlag and adjCode separated by "|"
customResponse	Stringified JSON parameter for future use.
gatewayPayerResponseCode optional	Response code returned by gateway
gatewayPayeeResponseCode optional	Response code returned by gateway
gatewayPayerReversalResponseCode optional	Response code returned by gateway
gatewayPayeeReversalResponseCode optional	Response code returned by gateway
gatewayReferenceId	Customer reference number (rrn) for the transaction.
gatewayResponseCode	Response code returned by gateway for the transaction. Refer below.
gatewayResponseMessage	Verbose response message returned by gateway for the transaction.
gatewayResponseStatus	Response status returned by gateway
gatewayTransactionId	UPI request id returned by gateway for the transaction.
gstAmount	Gst applied on the MDR charged
mdrAmount	MDR applied on the total transaction amount
merchantChannelId	Unique id for the channel via which request is made.
merchantId	Unique id for merchant.
merchantRequestId	Merchant generated request id as passed in the pay request.
netSettlementAmount	Net amount which needs to be settled (netSettlementAmount = txnAmount - (mdrAmount + gstAmount))
payeeMcc	Merchant Category Code of the payee merchant.
payeeVpa	Vpa of the merchant who received the payment.
payerAccBin optional	Only if payerActype = "CREDIT" , will share 10 digits bin of the credit account .If BIN is 6 digits, then remaining 4 digits shall be zero. If BIN is 8 digits, then remaining 2 digits will be zero.
payerActype optional	Account type of the customer who received the payment.
payerIfsc optional	Account's ifsc of the customer who received the payment.
payerName	Name of the customer who sent the payment.
payerMerchantCustomerId optional	Merchant generated unique id for customer who sent the payment. Only if it is an onus transaction.
payerVpa	Vpa of the customer who sent the payment.
refUrl	Invoice as sent by merchant or reference to the transaction in the form of url.
riskScore optional	RiskScore shared by NPCI or Bank
transactionTimestamp	Timestamp of when the sdk pay was initiated. (YYYY-MM-DDTHH:MM:SS+05:30)
type	Event type of the callback - MERCHANT_CREDITED_VIA_PAY.
subMerchantId optional	Unique id for subMerchant. Only if present as a subMerchant.
subMerchantChannelId optional	Unique id for the channel via which request is made. Only if present as a subMerchant.
udfParameters optional	Udf parameters as passed in the pay request.

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Payment Success.
01	PENDING	Payment is in pending state.
Else	FAILURE	Any other reason.

Incoming Money to Customer - Collect Status

# A callback with following POST data will be sent to the endpoint configured for "CUSTOMER_CREDITED_VIA_COLLECT"

{
  "amount": "100.00",
  "autoUpdateNote" : "TCC|102",
  "bankAccountUniqueId" : "fb96f8b2b...1ab0c070d0d894",
  "bankCode" : "123456",
  "customResponse": "{}",
  "expiry": "2016-11-25T00:10:00+05:30",
  "gatewayPayerResponseCode": "00",
  "gatewayPayeeResponseCode": "00",
  "gatewayPayerReversalResponseCode": "00",
  "gatewayPayeeReversalResponseCode": "00",
  "gatewayReferenceId": "806115044725",
  "gatewayResponseCode": "00",
  "gatewayResponseMessage": "Transaction is approved",
  "gatewayResponseStatus": "SUCCESS",
  "gatewayTransactionId": "XYZd0c077...f39c454979",
  "maskedAccountNumber" : "XXXX123456",
  "merchantChannelId": "DEMOUATAPP",
  "merchantCustomerId": "DEMO-CUST-1234",
  "merchantId": "DEMOUAT01",
  "merchantRequestId": "TXN1234567",
  "payeeMcc": "4121",
  "payeeMerchantCustomerId": "DEMO-CUST-1234",
  "payeeMobileNumber" : "919812388554",
  "payeeVpa" : "customer1@abc",
  "payerMerchantCustomerId": "DEMO-CUST-5678"
  "payerName": "Customer Name",
  "payerVpa": "customer@xyz",
  "refUrl": "https://www.abcxyz.com/",
  "remarks" : "Sample remarks",
  "riskScore": "00979",
  "transactionTimestamp": "2016-11-25T00:00:00+05:30",
  "type": "CUSTOMER_CREDITED_VIA_COLLECT",
  "udfParameters": "{}"
}

This callback is given when the customer sends a collect request to any upi user and when the same gets approved/declined/expired.

Note: Merchant can get multiple callbacks for the same event type till the transaction status reaches a terminal state. Terminal states for a transaction are SUCCESS, FAILURE, EXPIRED, DECLINED.

Parameter	Description
amount	Amount for which customer initiated the collect request.
autoUpdateNote optional	adjFlag and adjCode separated by "|"
bankAccountUniqueId optional	Unique hash for the customer bank account used for transaction. Only if gatewayResponseCode is "00".
bankCode optional	IIN for the customer bank account used for transaction. Only if gatewayResponseCode is "00".
customResponse	Stringified JSON parameter for future use.
expiry	Expiry timestamp for the collect request.
gatewayPayerResponseCode optional	Response code returned by gateway
gatewayPayeeResponseCode optional	Response code returned by gateway
gatewayPayerReversalResponseCode optional	Response code returned by gateway
gatewayPayeeReversalResponseCode optional	Response code returned by gateway
gatewayReferenceId	Customer reference number (rrn) for the transaction.
gatewayResponseCode	Response code returned by gateway for the transaction. Refer below.
gatewayResponseMessage	Verbose response message returned by gateway for the transaction.
gatewayResponseStatus	Response status returned by gateway
gatewayTransactionId	UPI request id returned by gateway for the transaction.
maskedAccountNumber optional	Masked account number for the customer bank account used for transaction. Only if gatewayResponseCode is "00".
merchantChannelId	Unique id for the channel via which request is made.
merchantCustomerId	Merchant generated unique id for customer who initiated the collect request.
merchantId	Unique id for merchant.
merchantRequestId	Merchant generated request id as passed in the collect request.
payeeMcc	Merchant Category Code of the payee merchant.
payeeMerchantCustomerId	Merchant generated unique id for customer who initiated the collect request.
payeeMobileNumber	Mobile number of the customer who initiated the collect request.
payeeVpa	Vpa of the customer who initiated the collect request.
payerMerchantCustomerId optional	Merchant generated unique id for customer who received the collect request. Only if it is an onus transaction.
payerName	Name of the upi user who received the collect request.
payerVpa	Vpa of the upi user who received the collect request.
refUrl	Invoice as sent by merchant or reference to the transaction in the form of url.
remarks	Remarks passed when intiating the collect request.
riskScore optional	RiskScore shared by NPCI or Bank
transactionTimestamp	Timestamp of when the collect was initiated. (YYYY-MM-DDTHH:MM:SS+05:30)
type	Event type of the callback - CUSTOMER_CREDITED_VIA_COLLECT.
udfParameters optional	Udf parameters as passed in the collect request.

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Payment Success.
01	PENDING	Payment is in pending state.
ZA	DECLINED	Decline Success.
U69	EXPIRED	Collect request expired.
Z9	FAILURE	Insufficient funds in customer (remitter) account.
Z8	FAILURE	Per transaction limit exceeded as set by remitting member.
Z7	FAILURE	Transaction frequency limit exceeded as set by remitting member.
Z6	FAILURE	Number of pin tries exceeded.
ZM	FAILURE	Invalid mpin.
RB	DEEMED	Transaction went into deemed state.
96	DEEMED	Transaction went into deemed state.
96	FAILURE	Transaction failed.
Else	FAILURE	Any other reason.

Incoming Money to Customer - Pay

# A callback with following POST data will be sent to the endpoint configured for "CUSTOMER_CREDITED_VIA_PAY"

{
  "amount": "100.00",
  "autoUpdateNote" : "TCC|102",
  "bankAccountUniqueId" : "fb96f8b2b1ab0c070d0d894......",
  "bankCode" : "123456",
  "customResponse": "{}",
  "gatewayPayerResponseCode": "00",
  "gatewayPayeeResponseCode": "00",
  "gatewayPayerReversalResponseCode": "00",
  "gatewayPayeeReversalResponseCode": "00",
  "gatewayReferenceId": "806115044725",
  "gatewayResponseCode": "00",
  "gatewayResponseMessage": "Transaction is approved",
  "gatewayResponseStatus": "SUCCESS",
  "gatewayTransactionId": "XYZd0c077f39c454979...",
  "maskedAccountNumber" : "XXXX123456",
  "merchantCustomerId": "DEMO-CUST-1234",
  "merchantId": "DEMOUAT01",
  "payeeMcc": "4121",
  "payeeMerchantCustomerId": "DEMO-CUST-1234",
  "payeeMobileNumber" : "919812388554",
  "payeeVpa" : "customer1@abc",
  "payerMerchantCustomerId": "DEMO-CUST-5678",
  "payerName": "Customer Name",
  "payerVpa": "customer@xyz",
  "refUrl": "https://www.abcxyz.com/",
  "riskScore": "00979",
  "transactionTimestamp": "2016-11-25T00:00:00+05:30",
  "type": "CUSTOMER_CREDITED_VIA_PAY",
  "udfParameters": "{}"
}

This callback is given when the customer receives money from any upi user.

Note: Merchant can get multiple callbacks for the same event type till the transaction status reaches a terminal state. Terminal states for a transaction are SUCCESS, FAILURE, EXPIRED, DECLINED.

Parameter	Description
amount	Amount for which customer received the payment.
autoUpdateNote optional	adjFlag and adjCode separated by "|"
bankAccountUniqueId optional	Unique hash for the customer bank account used for transaction. Only if gatewayResponseCode is "00".
bankCode optional	IIN for the customer bank account used for transaction. Only if gatewayResponseCode is "00".
customResponse	Stringified JSON parameter for future use.
gatewayPayerResponseCode optional	Response code returned by gateway
gatewayPayeeResponseCode optional	Response code returned by gateway
gatewayPayerReversalResponseCode optional	Response code returned by gateway
gatewayPayeeReversalResponseCode optional	Response code returned by gateway
gatewayReferenceId	Customer reference number (rrn) for the transaction.
gatewayResponseCode	Response code returned by gateway for the transaction. Refer below.
gatewayResponseMessage	Verbose response message returned by gateway for the transaction.
gatewayResponseStatus	Response status returned by gateway
gatewayTransactionId	UPI request id returned by gateway for the transaction.
maskedAccountNumber optional	Masked account number for the customer bank account used for transaction. Only if gatewayResponseCode is "00".
merchantCustomerId	Merchant generated unique id for customer who received the payment.
merchantId	Unique id for merchant.
payeeMcc	Merchant Category Code of the payee merchant.
payeeMerchantCustomerId	Merchant generated unique id for customer who received the payment.
payeeMobileNumber	Mobile number of the customer who received the payment.
payeeVpa	Vpa of the customer who received the payment.
payerMerchantCustomerId optional	Merchant generated unique id for customer who sent the payment. Only if it is an onus transaction.
payerName	Name of the upi user who sent the payment.
payerVpa	Vpa of the upi user who sent the payment.
refUrl	Invoice as sent by merchant or reference to the transaction in the form of url.
riskScore optional	RiskScore shared by NPCI or Bank
transactionTimestamp	Timestamp of when the payment was received. (YYYY-MM-DDTHH:MM:SS+05:30)
type	Event type of the callback - CUSTOMER_CREDITED_VIA_PAY.
udfParameters optional	Udf parameters as passed in the pay request.

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Payment Success.
01	PENDING	Payment is in pending state.
RB	DEEMED	Transaction went into deemed state.
96	DEEMED	Transaction went into deemed state.
96	FAILURE	Transaction failed.
Else	FAILURE	Any other reason.

Outgoing Money from a Customer

# A callback with following POST data will be sent to the endpoint configured for the event

{
  "amount": "10.00",
  "splitDetails": [{"name": "TIPS", "value": "1.00"}, {"name": "CCONFEE", "value": "1.00"}, {"name": "PCONFEE", "value": "1.00"}],
  "autoUpdateNote" : "TCC|102",
  "bankAccountUniqueId": "4536baef...32cdba67",
  "bankCode" : "123456",
  "customResponse": "{}",
  "gatewayPayerResponseCode": "00",
  "gatewayPayeeResponseCode": "00",
  "gatewayPayerReversalResponseCode": "00",
  "gatewayPayeeReversalResponseCode": "00",
  "gatewayReferenceId": "806115044725",
  "gatewayResponseCode": "00",
  "gatewayResponseMessage": "Transaction is approved",
  "gatewayResponseStatus": "SUCCESS",
  "gatewayTransactionId": "DEMOUATAPP01TXNfo897fHVTiYq51739",
  "maskedAccountNumber" : "XXXXXXX9988",
  "merchantChannelId": "DEMOUATAPP",
  "merchantCustomerId": "DEMO-CUST-1234",
  "merchantId": "MERCHANT",
  "merchantRequestId": "TXN1234567",
  "orgMandateId": "APL71f7d43bdf64d72d187317de123",
  "payeeMcc": "4121",
  "payeeMerchantCustomerId": "DEMO-CUST-5678",
  "payeeName": "Customer Name",
  "payeeVpa": "customer@xyz",
  "payerMerchantCustomerId": "DEMO-CUST-1234",
  "payerMobileNumber" : "919812388554",
  "payerVpa": "customer1@abc",
  "requestType": "APPROVE",
  "collectType" : "MANDATE",
  "seqNumber" : "1",
  "refUrl": "https://www.abcxyz.com/",
  "riskScore": "00979",
  "transactionTimestamp": "2016-11-25T00:00:00+05:30",
  "type": "<SEE TABLE BELOW>",
  "udfParameters": "{}",
  "umn": "ABZv1f7daa3bf64729af61b0f6d95b8dd@bankbiz"
}

This callback is given when the customer pays

• for his merchant order using Collect Approve
• for his merchant order using the SDK Pay
• to another UPI user by using Collect Approve
• to another UPI user using vpa, A/C+IFSC, Scan&Pay, Intent

Note: Merchant can get multiple callbacks for the same event type till the transaction status reaches a terminal state. Terminal states for a transaction are SUCCESS, FAILURE, EXPIRED, DECLINED.

Parameter	Description
amount	Amount for which customer made the payment.
splitDetails optional	Supplementary Expenses involved in the transaction
autoUpdateNote optional	adjFlag and adjCode separated by "|"
bankAccountUniqueId optional	Unique hash for the customer bank account used for transaction. Only if gatewayResponseCode is non "U69".
bankCode optional	IIN for the customer bank account used for transaction. Only if gatewayResponseCode is non "U69".
customResponse	Stringified JSON parameter for future use.
gatewayPayerResponseCode optional	Response code returned by gateway
gatewayPayeeResponseCode optional	Response code returned by gateway
gatewayPayerReversalResponseCode optional	Response code returned by gateway
gatewayPayeeReversalResponseCode optional	Response code returned by gateway
gatewayReferenceId	Customer reference number (rrn) for the transaction.
gatewayResponseCode	Response code returned by gateway for the transaction. Refer below.
gatewayResponseMessage	Verbose response message returned by gateway for the transaction.
gatewayResponseStatus	Response status returned by gateway
gatewayTransactionId	UPI request id returned by gateway for the transaction.
maskedAccountNumber optional	Masked account number for the customer bank account used for transaction. Only if gatewayResponseCode is non "U69".
merchantChannelId	Unique id for the channel via which request is made.
merchantCustomerId	Merchant generated unique id for customer who sent the payment.
merchantId	Unique id for merchant.
merchantRequestId optional	Merchant generated request id as passed in the collect request. Only if gatewayResponseCode is not "U69". Only given to the party which initiates the transaction
orgMandateId optional applicable only for collect mandate	Refers to upiRequestId used during creation of mandate.
payeeMcc	Merchant Category Code of the payee merchant.
payeeMerchantCustomerId optional	Merchant generated unique id for customer who received the payment. Only if it is an onus P2P transaction.
payeeName optional	Name of the upi user who received the payment. Only if payment is done to a non A/C+IFSC vpa.
payeeVpa	Vpa of the upi user who received the payment.
payerMerchantCustomerId	Merchant generated unique id for customer who sent the payment.
payerMobileNumber	Mobile number of the customer who made the payment.
payerVpa	If collectType is null or TRANSACTION, Vpa of the customer who received the collect request and if collectType is MANDATE, umn of the mandate.
requestType optional	Action which was taken on the collect request. Will not be present in case of EXPIRED callback.
collectType optional	Differentiates between a transaction collect request (TRANSACTION) or a mandate execution collect request (MANDATE). It will only be present in case of mandate request.
seqNumber optional applicable only for collect mandate	Denotes the recurring cycle of mandate execution. Will be received only during mandate executions. It will only be present in case of mandate request.
refUrl	Invoice as sent by merchant or reference to the transaction in the form of url.
riskScore optional	RiskScore shared by NPCI or Bank
transactionTimestamp	Timestamp of when the payment was received. (YYYY-MM-DDTHH:MM:SS+05:30)
type	Event type of the callback. Refer below.
udfParameters optional	Udf parameters as passed in the original payment request.
umn optional applicable only for collect mandate	Vpa used for execution of mandate.

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Payment Success.
01	PENDING	Payment is in pending state.
ZA	DECLINED	Decline Success.
U69	EXPIRED	Collect request expired.
Z9	FAILURE	Insufficient funds in customer (remitter) account.
Z8	FAILURE	Per transaction limit exceeded as set by remitting member.
Z7	FAILURE	Transaction frequency limit exceeded as set by remitting member.
Z6	FAILURE	Number of pin tries exceeded.
ZM	FAILURE	Invalid mpin.
RB	DEEMED	Transaction went into deemed state.
96	DEEMED	Transaction went into deemed state.
96	FAILURE	Transaction failed.
Else	FAILURE	Any other reason.

type	Description
CUSTOMER_DEBITED_FOR_MERCHANT_VIA_COLLECT	Outgoing money from a customer to merchant via collect
CUSTOMER_DEBITED_FOR_MERCHANT_VIA_PAY	Outgoing money from a customer to merchant via pay
CUSTOMER_DEBITED_VIA_COLLECT	Outgoing money from a customer to a UPI user via collect
CUSTOMER_DEBITED_VIA_PAY	Outgoing money from a customer to a UPI user via pay

Incoming Collect Request to Customer

# A callback with following POST data will be sent to the endpoint configured for COLLECT_REQUEST_RECEIVED

{
  "amount": "100.00",
  "customResponse": "{}",
  "expiry": "2016-11-25T00:30:00+05:30",
  "gatewayReferenceId": "806115044725",
  "gatewayTransactionId": "XYZd0c077f39c454979...",
  "isVerifiedPayee": "true",
  "isMarkedSpam": "true",
  "merchantCustomerId": "DEMO-CUST-1234",
  "merchantId": "DEMOUAT01",
  "payeeMcc": "4121",
  "payeeMerchantCustomerId": "DEMO-CUST-5678",
  "payeeName": "Customer Name",
  "payeeVpa": "customer@xyz",
  "payerMerchantCustomerId": "DEMO-CUST-1234",
  "payerVpa": "customer1@abc",
  "collectType" : "MANDATE",
  "seqNumber" : "1",
  "refUrl": "https://www.abcxyz.com/",
  "remarks": "This is remarks",
  "riskScore": "00979",
  "transactionTimestamp": "2016-11-25T00:00:00+05:30",
  "type": "COLLECT_REQUEST_RECEIVED"
}

This callback is given when a customer receives a collect request from any UPI user. This enables merchant server to notify the customer, so that she can take action on the request.

Parameter	Description
amount	Amount for which customer received the collect request.
customResponse	Stringified JSON parameter for future use.
expiry	Expiry timestamp for the collect request.
gatewayReferenceId	Customer reference number (rrn) for the transaction.
gatewayTransactionId	UPI request id returned by gateway for the transaction.
isVerifiedPayee	Stringified boolean flag if the payee is a verified vpa.
isMarkedSpam	Stringified boolean flag if the payee is marked as spam.
merchantCustomerId	Merchant generated unique id for customer who received the collect request.
merchantId	Unique id for merchant.
payeeMcc	Merchant Category Code of the payee merchant.
payeeMerchantCustomerId	Merchant generated unique id for customer who initiated the collect request.
payeeName	Name of the upi user who sent the collect request.
payeeVpa	Vpa of the upi user who sent the collect request.
payerMerchantCustomerId	Merchant generated unique id for customer who received the collect request.
payerVpa	If collectType is null or TRANSACTION, Vpa of the customer who received the collect request and if collectType is MANDATE, umn of the mandate.
collectType optional	Differentiates between a transaction collect request (TRANSACTION) or a mandate execution collect request (MANDATE).
seqNumber optional	Denotes the recurring cycle of mandate execution. Will be received only during mandate executions.
refUrl	Invoice as sent by merchant or reference to the transaction in the form of url.
remarks	Remarks sent by upi user for the collect request.
riskScore optional	RiskScore shared by NPCI or Bank
transactionTimestamp	Timestamp of when the collect request was received. (YYYY-MM-DDTHH:MM:SS+05:30)
type	Event type of the callback - COLLECT_REQUEST_RECEIVED.

Outgoing Collect Request from Customer

# A callback with following POST data will be sent to the endpoint configured for COLLECT_REQUEST_SENT

{
  "amount": "100.00",
  "bankAccountUniqueId": "4536baef...32cdba67",
  "bankCode" : "123456",
  "customResponse": "{}",
  "expiry": "2016-11-25T00:30:00+05:30",
  "gatewayReferenceId": "806115044725",
  "gatewayResponseCode": "00",
  "gatewayResponseMessage": "Collect request sent successfully",
  "gatewayResponseStatus": "SUCCESS",
  "gatewayTransactionId": "XYZd0c077f39c454979...",
  "maskedAccountNumber" : "XXXXXXX9988",
  "merchantChannelId": "DEMOUAT01",
  "merchantCustomerId": "DEMO-CUST-1234",
  "merchantId": "DEMOUAT01",
  "merchantRequestId": "TXN1234567",
  "payeeMcc": "4121",
  "payeeMerchantCustomerId": "DEMO-CUST-1234",
  "payeeMobileNumber": "919876543210",
  "payeeVpa": "customer@xyz",
  "payerName": "Customer Name",
  "payerVpa": "customer1@abc",
  "refUrl": "https://www.abcxyz.com/",
  "remarks": "This is remarks",
  "riskScore": "00979",
  "transactionTimestamp": "2016-11-25T00:00:00+05:30",
  "type": "COLLECT_REQUEST_SENT",
  "udfParameters": "{}"
}

This callback is given when a customer sends a collect request to any UPI user. This enables merchant server to notify the customer, that his collect request is send successfully.

Parameter	Description
amount	Amount for which customer sent the collect request.
bankAccountUniqueId optional	Unique hash for the customer bank account used for transaction. Only if gatewayResponseCode is "00".
bankCode optional	IIN for the customer bank account used for transaction. Only if gatewayResponseCode is "00".
customResponse	Stringified JSON parameter for future use.
expiry	Expiry timestamp for the collect request.
gatewayReferenceId	Customer reference number (rrn) for the transaction.
gatewayResponseCode	Response code returned by gateway for the transaction. Refer below.
gatewayResponseMessage	Verbose response message returned by gateway for the transaction.
gatewayResponseStatus	Response status returned by gateway
gatewayTransactionId	UPI request id returned by gateway for the transaction.
maskedAccountNumber optional	Masked account number for the customer bank account used for transaction. Only if gatewayResponseCode is "00".
merchantChannelId	Unique channel id for merchant.
merchantCustomerId	Merchant generated unique id for customer who sent the collect request.
merchantId	Unique id for merchant.
merchantRequestId	Merchant generated request id as passed in the collect request.
payeeMcc	Merchant Category Code of the payee merchant.
payeeMerchantCustomerId	Merchant generated unique id for customer who sent the collect request.
payeeMobileNumber	Mobile number of the customer who sent the collect request.
payeeVpa	Vpa of the customer who sent the collect request.
payerName	Name of the payer to whom collect request was sent.
payerVpa	Vpa of the UPI user who received the collect request.
refUrl	Invoice as sent by merchant or reference to the transaction in the form of url.
remarks	Remarks sent by customer for the collect request.
riskScore optional	RiskScore shared by NPCI or Bank
transactionTimestamp	Timestamp of when the collect request was sent. (YYYY-MM-DDTHH:MM:SS+05:30)
type	Event type of the callback - COLLECT_REQUEST_SENT.
udfParameters optional	Udf parameters as passed in the request money api call.

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Collect request sent successfully.
01	PENDING	Sending collect request timed out.
Else	FAILURE	Sending collect request failed.

Query Closing

# A callback with following POST data will be sent to the configured url :

{
  "merchantChannelId": "MERCHANTAPP",
  "merchantId": "MERCHANT",
  "queries": [
    {
      "gatewayReferenceId" : "809323430413",
      "gatewayResponseCode": "105",
      "gatewayResponseMessage": "Beneficiary account has already been credited.",
      "gatewayTransactionId": "BankNameSDKV3d0c077f39c454979a010ff7ada",
      "merchantCustomerId": "MERCHANTCUST123",
      "queryClosingTimestamp": "2016-11-25T00:00:00+05:30",
      "queryComment": "Amount not credited",
      "queryReferenceId": "QUERY123",
      "udfParameters": "{}"
    },
    ...
  ]
}

Server sends a callback to the url configured when queries are closed. In case of more than 100 queries closed in a given day, multiple callbacks will be sent in batches of 100 queries per callback.

Parameter	Description
merchantId	Unique id for merchant.
merchantChannelId	Unique id for the channel via which request is made.
merchantCustomerId	Merchant generated unique id for customer on whose transaction the query was raised.
queryReferenceId	PSP generated unique id for the query
queryComment optional	The query description as was sent in the request while raising the query. Will only come if it was passed while raising the query.
queryClosingTimestamp	Timestamp of when the query was closed.
gatewayTransactionId	UPI request id that was passed in the request while raising the query
gatewayResponseCode	Response code returned by the gateway about the query status
gatewayResponseMessage	Response message returned by the gateway about the query status
gatewayReferenceId	RRN of the transaction whose query is being closed
udfParameters optional	Stringified json for udf parameters.

gatewayResponseCode	gatewayResponseMessage	Original Transaction Status
102	Your account has already been credited with Rs {amount}. Please check your balance.	Failure
103	Your account has already been credited with Rs {amount}. Please check your balance.	Failure
104	The transaction has failed, please try again after some time.	Failure
105	Beneficiary account has already been credited.	Success
106	Funds have been reversed to your bank account. Your bank shall credit in 5 working days.	Failure
107	Beneficiary account has already been credited.	Success
108	Beneficiary account has already been credited.	Success
109	Funds have been reversed to your bank account. Your bank shall credit in 5 working days.	Failure
144	Your account was not debited.	Failure
Else	Incase any other gatewayResponseCode is returned by TSP. Consider the transaction status as Failure.	Failure

Refund Status

# A callback with following POST data will be sent to the endpoint configured for "MERCHANT_DEBITED_VIA_REFUND"

{
  "customResponse": "{}",
  "gatewayRefundReferenceId": "809323430413",
  "gatewayResponseCode": "00",
  "gatewayResponseMessage": "Your refund is successful",
  "gatewayResponseStatus": "SUCCESS",
  "gatewayTransactionId": "AUTcb313014204649ad8818933d8623abd7",
  "merchantChannelId": "TESTAPP",
  "merchantId": "TEST",
  "refundAmount": "19.00",
  "refundRequestId": "refund4543843",
  "refundTimestamp": "2019-06-09T17:57:49+05:30",
  "refundType": "ONLINE",
  "transactionAmount": "200.00",
  "type": "MERCHANT_DEBITED_VIA_REFUND",
  "udfParameters": "{}"
}

This callback is given when the merchant initiates a refund and when the same gets success/failure.

Note: Merchant can get multiple callbacks for the same event type till the refund status reaches a terminal state. Terminal states for a refund are SUCCESS and FAILURE.

Parameter	Description
customResponse	Stringified JSON parameter for future use.
gatewayRefundReferenceId	Reference id returned by the gateway for the refund
gatewayResponseCode	Response code returned by gateway for the refund
gatewayResponseMessage	Response message for code returned by gateway for the refund
gatewayResponseStatus	Response status returned by gateway for the refund
gatewayTransactionId	UPI request id returned by gateway for the transaction
merchantChannelId	Unique id for the merchant channel as passed in request headers
merchantId	Unique id for the merchant as passed in request headers
refundAmount	The amount to be refunded as passed in the request body
refundRequestId	Merchant generated unique id for the refund as passed in the request body
refundTimestamp	Timestamp of when refund request was initiated
refundType	Type of refund being initiated as passed in the request body
transactionAmount	The total amount for which original transaction was performed
type	Event type of the callback - MERCHANT_DEBITED_VIA_REFUND
udfParameters optional	Udf parameters as passed in the request

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Refund accepted successfully
01	PENDING	Refund is in pending state
91	PENDING	Refund is in pending state
09	PENDING	Refund is in pending state
060	PENDING	Refund is in pending state
070	PENDING	Refund is in pending state
080	PENDING	Refund is in pending state
RB	DEEMED	Refund is in deemed state
96	DEEMED	Refund is in deemed state
Else	FAILURE	Refund failed

Mandate Merchant API Callbacks

Outgoing Create Mandate From Merchant

# A callback with following POST data will be sent to the configured url :

{
  "amount": "100.00",
  "amountRule": "EXACT",
  "blockFund": "true",
  "expiry": "2020-07-25T00:30:00+05:30",
  "gatewayMandateId": "APL71f7d43bdf64d72d9saddfded",
  "gatewayReferenceId": "809323430413"
  "gatewayResponseCode": "00",
  "gatewayResponseMessage": "Mandate is successfully created",
  "gatewayResponseStatus": "SUCCESS",
  "initiatedBy": "PAYEE",
  "mandateApprovalTimestamp" : "2017-06-09T17:58:49+05:30",
  "mandateName": "merchant mandate",
  "mandateTimestamp": "2020-06-01T15:40:42+05:30",
  "merchantChannelId": "AMAZON",
  "merchantId": "AMAZON",
  "merchantRequestId": "6138ne3wswbsssddc4dddc",
  "orgMandateId": "APLMsleiuryufhuhsoisdjfadb48003sdaa0",
  "payeeMcc": "4121",
  "payeeVpa": "test@apl",
  "payerName": "ABC",
  "payerRevocable": "true",
  "payerVpa": "9962463212@apl",
  "recurrencePattern": "MONTHLY",
  "recurrenceRule": "ON",
  "recurrenceValue": "5",
  "refUrl": "https://www.abcxyz.com/",
  "remarks": "Sample Remarks",
  "role": "PAYEE",
  "shareToPayee": "true",
  "transactionType": "UPI_MANDATE",
  "type": "MERCHANT_OUTGOING_CREATE_MANDATE",
  "udfParameters" : "{}"
  "umn": "uniqueMandateNumber@apl",
  "validityEnd": "2020/06/05",
  "validityStart": "2020/06/04"
}

Server sends a callback to Merchant to the url configured when mandate is created.

Parameter	Description
amount	Amount of Mandate. Numeric string with two decimals.
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.
blockFund	Denotes whether customer's fund should be blocked or not. For Onetime mandate, value can be true or false and for recurring mandate it is always false.
expiry	Timestamp until which create mandate request is valid. It will be present only when payee has initiated the mandate.
gatewayMandateId	upiRequestId passed in the request.
gatewayReferenceId	Customer reference number (rrn).
gatewayResponseCode	Response code returned by gateway for the mandate.
gatewayResponseMessage	Response message returned by gateway for the mandate.
gatewayResponseStatus	Response status returned by gateway.
initiatedBy	Describes whether PAYER or PAYEE has initiated the mandate.
mandateApprovalTimestamp	Time instant at which create mandate request was approved. Only present if mandate was initiatedBy Payee. Timestamp in YYYY-MM-DDTHH:MM:SS+05:30 format.
mandateName	Name of the mandate.
mandateTimestamp	Timestamp of when the mandate request was attempted. Timestamp in YYYY-MM-DDTHH:MM:SS+05:30 format.
merchantChannelId	Unique id for the channel via which request is made.
merchantId	Unique id for merchant.
merchantRequestId	Request id used for the mandate. It is merchantRequestId that is passed during initiation of mandate.
orgMandateId	Refers to upiRequestId used during creation of mandate.
payeeMcc	Merchant Category Code of the payee merchant. If Payee is a customer it will be "0000" else it will be a 4 digit numeric string.
payeeVpa	Vpa of the payee.
payerName	Name of the Payer involved in mandate.
payerRevocable	Denotes whether mandate can be revoke by payer or not. If while requesting mandate Payee passes this flag is true, mandate can be revoked by Payer else it cannot be revoked by Payer. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
payerVpa	Vpa of the payer.
recurrencePattern	Recurrence Pattern for Mandate. Possible values are ONETIME, DAILY, WEEKLY, FORTNIGHTLY,MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED
recurrenceRule conditional	Recurrence Rule for Mandate. Possible values are ON, BEFORE, AFTER. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
recurrencValue conditional	Recurrence Value for Mandate. Possible values are 1-31 and depends on the recurrencePattern. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
refUrl	Invoice as sent by merchant or reference to the mandate in the form of url. This is a field which is majorly for future purpose and is send by the Payee.
remarks	Any mandate summary
role	Role of the customer for this mandate. PAYER,PAYEE
shareToPayee	Denotes whether mandate should be shared with payee or not. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
transactionType	Type of Mandate Creation
type	Event type of the callback
udfParameters optional	Stringified json for udf parameters. It will be present only if passed during web mandate API request.
umn optional	Vpa used for execution of mandate. It will not be present if gatewayResponseStatus is EXPIRED or if it is not received from NPCI due to validation failure at Payer PSP during approve mandate.
validityEnd	Date until which mandate can be executed.
validityStart	Date after which mandate can be executed.

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Mandate Created Successfully.
UM3	EXPIRED	Mandate request expired.
ZA	DECLINED	Mandate request Declined by Payer.
Else	FAILURE	Any other reason.

Outgoing Update Mandate From Merchant

# A callback with following POST data will be sent to the configured url :

{
  "amount": "100.00",
  "amountRule": "EXACT",
  "blockFund": "true",
  "expiry": "2020-07-25T00:30:00+05:30",
  "gatewayMandateId": "APL71f7d43bdf64d72d9saddfded",
  "gatewayReferenceId": "809323430413"
  "gatewayResponseCode": "00",
  "gatewayResponseMessage": "Mandate is successfully updated",
  "gatewayResponseStatus": "SUCCESS",
  "initiatedBy": "PAYER",
  "mandateName": "merchant mandate",
  "mandateTimestamp": "2020-06-01T15:40:42+05:30",
  "mandateType" : "UPDATE",
  "merchantChannelId": "AMAZON",
  "merchantId": "AMAZON",
  "merchantRequestId": "6138ne3wswbsssddc4dddc",
  "orgMandateId": "APLMsleiuryufhuhsoisdjfadb48003sdaa0",
  "payeeMcc": "4121",
  "payeeVpa": "test@apl",
  "payerName": "ABC",
  "payerRevocable": "true",
  "payerVpa": "9962463212@apl",
  "recurrencePattern": "MONTHLY",
  "recurrenceRule": "ON",
  "recurrenceValue": "5",
  "refUrl": "https://www.abcxyz.com/",
  "remarks": "Sample Remarks",
  "role": "PAYER",
  "shareToPayee": "true",
  "transactionType": "UPI_MANDATE",
  "type": "MERCHANT_OUTGOING_UPDATE_MANDATE",
  "udfParameters" : "{}"
  "umn": "uniqueMandateNumber@apl",
  "validityEnd": "2020/06/05",
  "validityStart": "2020/06/04"
}

Server sends a callback to Merchant to the url configured when mandate is updated.

Parameter	Description
amount	Amount of Mandate. Numeric string with two decimals.
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.
blockFund	Denotes whether customer's fund should be blocked or not. For Onetime mandate, value can be true or false and for recurring mandate it is always false.
expiry	Timestamp until which create mandate request is valid. It will be present only when payee has initiated the mandate.
gatewayMandateId	upiRequestId passed in the request.
gatewayReferenceId	Customer reference number (rrn).
gatewayResponseCode	Response code returned by gateway for the mandate.
gatewayResponseMessage	Response message returned by gateway for the mandate.
gatewayResponseStatus	Response status returned by gateway.
initiatedBy	Describes whether PAYER or PAYEE has initiated the mandate.
mandateName	Name of the mandate.
mandateTimestamp	Timestamp of when the mandate request was attempted.
mandateType	Denotes the type of mandate operation. Values can be UPDATE/REVOKE.
merchantChannelId	Unique id for the channel via which request is made.
merchantId	Unique id for merchant.
merchantRequestId	Request id used for the mandate. It is merchantRequestId that is passed during initiation of mandate request.
orgMandateId	Refers to upiRequestId used during creation of mandate.
payeeMcc	Merchant Category Code of the payee merchant. If Payee is a customer it will be "0000" else it will be a 4 digit numeric string.
payeeVpa	Vpa of the payee.
payerName	Name of the Payer involved in mandate.
payerRevocable	Denotes whether mandate can be revoke by payer or not. If while requesting mandate Payee passes this flag is true, mandate can be revoked by Payer else it cannot be revoked by Payer. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
payerVpa	Vpa of the payer.
recurrencePattern	Recurrence Pattern for Mandate. Possible values are ONETIME, DAILY, WEEKLY, FORTNIGHTLY,MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED
recurrenceRule conditional	Recurrence Rule for Mandate. Possible values are ON, BEFORE, AFTER. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
recurrencValue conditional	Recurrence Value for Mandate. Possible values are 1-31 and depends on the recurrencePattern. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
refUrl	Invoice as sent by merchant or reference to the mandate in the form of url. This is a field which is majorly for future purpose and is send by the Payee.
remarks	Any mandate summary
role	Role of the customer for this mandate. PAYER,PAYEE
shareToPayee	Denotes whether mandate should be shared with payee or not. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
transactionType	Type of Mandate Creation
type	Event type of the callback
udfParameters optional	Stringified json for udf parameters. It will be present only if passed during web update API request.
umn	Vpa used for execution of mandate.
validityEnd	Date until which mandate can be executed.
validityStart	Date after which mandate can be executed.

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Mandate updated successfully.
UM3	EXPIRED	Mandate request expired.
QT	DECLINED	Mandate request Declined by Payer.
Else	FAILURE	Any other reason.

Incoming Pause Mandate For Merchant

# A callback with following POST data will be sent to the configured url :

{
  "amount": "100.00",
  "amountRule": "EXACT",
  "blockFund": "true",
  "gatewayMandateId": "APL71f7d43bdf64d72d9saddfded",
  "gatewayReferenceId": "809323430413"
  "gatewayResponseCode": "00",
  "gatewayResponseMessage": "Mandate is successfully paused",
  "gatewayResponseStatus": "SUCCESS",
  "initiatedBy" : "PAYER",
  "mandateName": "merchant mandate",
  "mandateTimestamp": "2020-06-01T15:40:42+05:30",
  "mandateType" : "PAUSE",
  "merchantChannelId": "AMAZON",
  "merchantId": "AMAZON",
  "merchantRequestId": "6138ne3wswbsssddc4dddc",
  "orgMandateId": "APLMsleiuryufhuhsoisdjfadb48003sdaa0",
  "pauseEnd": "2019/09/19",
  "pauseStart": "2019/09/17",
  "payeeMcc": "4121",
  "payeeVpa": "test@apl",
  "payerName": "ABC",
  "payerRevocable": "true",
  "payerVpa": "9962463212@apl",
  "recurrencePattern": "MONTHLY",
  "recurrenceRule": "ON",
  "recurrenceValue": "5",
  "refUrl": "https://www.abcxyz.com/",
  "remarks": "Sample Remarks",
  "role": "PAYER",
  "shareToPayee": "true",
  "transactionType": "UPI_MANDATE",
  "type": "MERCHANT_INCOMING_PAUSE_MANDATE",
  "umn": "uniqueMandateNumber@apl",
  "validityEnd": "2020/06/05",
  "validityStart": "2020/06/04"
}

Server sends a callback to Merchant to the url configured when mandate is paused.

Parameter	Description
amount	Amount of Mandate. Numeric string with two decimals.
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.
blockFund	Denotes whether customer's fund should be blocked or not. For Onetime mandate, value can be true or false and for recurring mandate it is always false.
gatewayMandateId	upiRequestId passed in the request.
gatewayReferenceId	Customer reference number (rrn).
gatewayResponseCode	Response code returned by gateway for the mandate.
gatewayResponseMessage	Response message returned by gateway for the mandate.
gatewayResponseStatus	Response status returned by gateway.
initiatedBy	Describes whether PAYER or PAYEE has initiated the mandate.
mandateName	Name of the mandate.
mandateTimestamp	Timestamp of when the mandate request was attempted.
mandateType	Denotes the type of mandate operation. Values can be PAUSE/UNPAUSE.
merchantChannelId	Unique id for the channel via which request is made.
merchantId	Unique id for merchant.
merchantRequestId	Request id used for the mandate operation. It is merchantRequestId that is passed during initiation of mandate request.
orgMandateId	Refers to upiRequestId used during creation of mandate.
pauseEnd	Date until which mandate is paused
pauseStart	Date from which mandate is paused
payeeMcc	Merchant Category Code of the payee merchant. If Payee is a customer it will be "0000" else it will be a 4 digit numeric string.
payeeVpa	Vpa of the payee.
payerName	Name of the Payer involved in mandate. It will be present if role is PAYEE
payerRevocable	Denotes whether mandate can be revoke by payer or not. If while requesting mandate Payee passes this flag is true, mandate can be revoked by Payer else it cannot be revoked by Payer. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
payerVpa	Vpa of the payer.
recurrencePattern	Recurrence Pattern for Mandate. Possible values are ONETIME, DAILY, WEEKLY, FORTNIGHTLY,MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED
recurrenceRule conditional	Recurrence Rule for Mandate. Possible values are ON, BEFORE, AFTER. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
recurrencValue conditional	Recurrence Value for Mandate. Possible values are 1-31 and depends on the recurrencePattern. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
refUrl	Invoice as sent by merchant or reference to the mandate in the form of url. This is a field which is majorly for future purpose and is send by the Payee.
remarks	Any mandate summary
role	Role of the customer for this mandate. PAYER,PAYEE
shareToPayee	Denotes whether mandate should be shared with payee or not. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
transactionType	Type of Mandate Creation
type	Event type of the callback
umn	Vpa used for execution of mandate.
validityEnd	Date until which mandate can be executed.
validityStart	Date after which mandate can be executed.

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Payment Success.
Else	FAILURE	Any other reason.

Incoming Create Mandate For Merchant

# A callback with following POST data will be sent to the configured url :

{
  "amount": "100.00",
  "amountRule": "EXACT",
  "blockFund": "true",
  "gatewayMandateId": "APL71f7d43bdf64d72d9saddfded",
  "gatewayReferenceId": "809323430413"
  "gatewayResponseCode": "00",
  "gatewayResponseMessage": "Mandate is successfully created",
  "gatewayResponseStatus": "SUCCESS",
  "initiatedBy": "PAYER",
  "mandateName": "merchant mandate",
  "mandateTimestamp": "2020-06-01T15:40:42+05:30",
  "merchantChannelId": "APL",
  "merchantId": "APL",
  "merchantRequestId": "6138ne3wswbsssddc4dddc",
  "orgMandateId": "APLMsleiuryufhuhsoisdjfadb48003sdaa0",
  "payeeMcc": "4121",
  "payeeVpa": "test@apl",
  "payerName": "ABC",
  "payerRevocable": "true",
  "payerVpa": "9962463212@apl",
  "recurrencePattern": "MONTHLY",
  "recurrenceRule": "ON",
  "recurrenceValue": "5",
  "refUrl": "https://www.abcxyz.com/",
  "remarks": "Sample Remarks",
  "role": "PAYER",
  "shareToPayee": "true",
  "transactionType": "UPI_MANDATE",
  "type": "MERCHANT_INCOMING_CREATE_MANDATE",
  "umn": "uniqueMandateNumber@apl",
  "validityEnd": "2020/06/05",
  "validityStart": "2020/06/04"
}

Server sends a callback to Merchant to the url configured when an mandate creation request is received. As mandate is initiated by PAYER the mandateTimestamp should be considered as mandateApprovalTimestamp.

Parameter	Description
amount	Amount of Mandate. Numeric string with two decimals.
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.
blockFund	Denotes whether customer's fund should be blocked or not. For Onetime mandate, value can be true or false and for recurring mandate it is always false.
gatewayMandateId	upiRequestId passed in the request.
gatewayReferenceId	Customer reference number (rrn).
gatewayResponseCode	Response code returned by gateway for the mandate.
gatewayResponseMessage	Response message returned by gateway for the mandate.
gatewayResponseStatus	Response status returned by gateway.
initiatedBy	Describes whether PAYER or PAYEE has initiated the mandate.
mandateName	Name of the mandate.
mandateTimestamp	Timestamp of when the mandate request was attempted. Timestamp in YYYY-MM-DDTHH:MM:SS+05:30 format.
merchantChannelId	Unique id for the channel via which request is made.
merchantId	Unique id for merchant.
merchantRequestId	Request id used for the mandate. It will be merchantRequestId that is passed during approve mandate if mandate is initiated by Payee else it will be refId that is received from NPCI for Payer initiated mandate.
orgMandateId	Refers to upiRequestId used during creation of mandate.
payeeMcc	Merchant Category Code of the payee merchant. If Payee is a customer it will be "0000" else it will be a 4 digit numeric string.
payeeVpa	Vpa of the payee.
payerName	Name of the Payer involved in mandate. It will be present if role is PAYEE
payerRevocable	Denotes whether mandate can be revoke by payer or not. If while requesting mandate Payee passes this flag is true, mandate can be revoked by Payer else it cannot be revoked by Payer. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
payerVpa	Vpa of the payer.
recurrencePattern	Recurrence Pattern for Mandate. Possible values are ONETIME, DAILY, WEEKLY, FORTNIGHTLY,MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED
recurrenceRule conditional	Recurrence Rule for Mandate. Possible values are ON, BEFORE, AFTER. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
recurrencValue conditional	Recurrence Value for Mandate. Possible values are 1-31 and depends on the recurrencePattern. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
refUrl	Invoice as sent by merchant or reference to the mandate in the form of url. This is a field which is majorly for future purpose and is send by the Payee.
remarks	Any mandate summary
role	Role of the customer for this mandate. PAYER,PAYEE
shareToPayee	Denotes whether mandate should be shared with payee or not. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
transactionType	Type of Mandate Creation
type	Event type of the callback
umn	Vpa used for execution of mandate.
validityEnd	Date until which mandate can be executed.
validityStart	Date after which mandate can be executed.

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Mandate Created Successfully.
UM3	EXPIRED	Mandate request expired.
ZA	DECLINED	Mandate request Declined by Payer.
Else	FAILURE	Any other reason.

Incoming Update Mandate For Merchant

# A callback with following POST data will be sent to the configured url :

{
  "amount": "100.00",
  "amountRule": "EXACT",
  "blockFund": "true",
  "gatewayMandateId": "APL71f7d43bdf64d72d9saddfded",
  "gatewayReferenceId": "809323430413"
  "gatewayResponseCode": "00",
  "gatewayResponseMessage": "Mandate is successfully updated",
  "gatewayResponseStatus": "SUCCESS",
  "initiatedBy": "PAYER",
  "mandateName": "merchant mandate",
  "mandateTimestamp": "2020-06-01T15:40:42+05:30",
  "mandateType" : "UPDATE",
  "merchantChannelId": "APL",
  "merchantId": "APL",
  "merchantRequestId": "6138ne3wswbsssddc4dddc",
  "orgMandateId": "APLMsleiuryufhuhsoisdjfadb48003sdaa0",
  "payeeMcc": "4121",
  "payeeVpa": "test@apl",
  "payerName": "ABC",
  "payerRevocable": "true",
  "payerVpa": "9962463212@apl",
  "recurrencePattern": "MONTHLY",
  "recurrenceRule": "ON",
  "recurrenceValue": "5",
  "refUrl": "https://www.abcxyz.com/",
  "remarks": "Sample Remarks",
  "role": "PAYEE",
  "shareToPayee": "true",
  "transactionType": "UPI_MANDATE",
  "type": "MERCHANT_INCOMING_UPDATE_MANDATE",
  "umn": "uniqueMandateNumber@apl",
  "validityEnd": "2020/06/05",
  "validityStart": "2020/06/04"
}

Server sends a callback to Merchant to the url configured when an mandate update/revoke request is received.

Parameter	Description
amount	Amount of Mandate. Numeric string with two decimals.
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.
blockFund	Denotes whether customer's fund should be blocked or not. For Onetime mandate, value can be true or false and for recurring mandate it is always false.
gatewayMandateId	upiRequestId passed in the request.
gatewayReferenceId	Customer reference number (rrn).
gatewayResponseCode	Response code returned by gateway for the mandate.
gatewayResponseMessage	Response message returned by gateway for the mandate.
gatewayResponseStatus	Response status returned by gateway.
initiatedBy	Describes whether PAYER or PAYEE has initiated the mandate.
mandateName	Name of the mandate.
mandateTimestamp	Timestamp of when the mandate request was attempted.
mandateType	Denotes the type of mandate operation. Values can be UPDATE/REVOKE.
merchantChannelId	Unique id for the channel via which request is made.
merchantId	Unique id for merchant.
merchantRequestId	Request id used for the mandate. It will be merchantRequestId that is passed during approve mandate if mandate update request is initiated by Payee else it will be refId that is received from NPCI for Payer initiated update mandate.
orgMandateId	Refers to upiRequestId used during creation of mandate.
payeeMcc	Merchant Category Code of the payee merchant. If Payee is a customer it will be "0000" else it will be a 4 digit numeric string.
payeeVpa	Vpa of the payee.
payerName	Name of the Payer involved in mandate.
payerRevocable	Denotes whether mandate can be revoke by payer or not. If while requesting mandate Payee passes this flag is true, mandate can be revoked by Payer else it cannot be revoked by Payer. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
payerVpa	Vpa of the payer.
recurrencePattern	Recurrence Pattern for Mandate. Possible values are ONETIME, DAILY, WEEKLY, FORTNIGHTLY,MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED
recurrenceRule conditional	Recurrence Rule for Mandate. Possible values are ON, BEFORE, AFTER. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
recurrencValue conditional	Recurrence Value for Mandate. Possible values are 1-31 and depends on the recurrencePattern. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
refUrl	Invoice as sent by merchant or reference to the mandate in the form of url. This is a field which is majorly for future purpose and is send by the Payee.
remarks	Any mandate summary
role	Role of the customer for this mandate. PAYER,PAYEE
shareToPayee	Denotes whether mandate should be shared with payee or not. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
transactionType	Type of Mandate Creation
type	Event type of the callback
umn	Vpa used for execution of mandate.
validityEnd	Date until which mandate can be executed.
validityStart	Date after which mandate can be executed.

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Mandate Updated Successfully.
UM3	EXPIRED	Mandate request expired.
ZA	DECLINED	Mandate request Declined by Payer.
Else	FAILURE	Any other reason.

Outgoing Execute Mandate From Merchant

# A callback with following POST data will be sent to the configured url :

{
  "amount" : "9.00",
  "expiry": "2016-11-25T00:10:00+05:30",
  "gatewayReferenceId" : "809323430413",
  "gatewayResponseCode" : "00",
  "gatewayResponseMessage" : "Mandate is successfully executed",
  "gatewayTransactionId" : "ABZ0f018ee5bc8b428fb979cb4a53ea9bde",
  "gstAmount": "0.05",
  "mdrAmount": ".27",
  "merchantChannelId": "DEMOUATAPP",
  "merchantId": "DEMOUAT01",
  "merchantRequestId": "TXN1234567",
  "netSettlementAmount": "8.68",
  "orgMandateId": "ABZ0f018ee5bc8b428fb9jgdfjwhg392",
  "payeeMcc" : "0000",
  "payeeVpa" : "abcd@bankbiz",
  "payerName": "ABC",
  "payerVpa" : "xyz@bankbiz",
  "refUrl" : "https://www.abcxyz.com/",
  "riskScore": "00979",
  "seqNumber": "1",
  "transactionTimestamp" : "2017-06-09T17:57:49+05:30",
  "type" : "MERCHANT_OUTGOING_EXECUTE_MANDATE",
  "udfParameters" : "{}"
  "umn" : "customervpa@bank",
}

Server sends a callback to the Merchant to the url configured when mandate is executed.

Note: If the merchantFlag merchantCreditedViaCollectForMandateExecute is set to true, the MERCHANT_CREDITED_VIA_COLLECT callback is sent instead.

Parameter	Description
amount	Amount of Mandate.
expiry	Expiry timestamp for the collect request.
gatewayReferenceId	Customer reference number (rrn).
gatewayResponseCode	Response code returned by gateway for the transaction.
gatewayResponseMessage	Response message returned by gateway for the transaction.
gatewayResponseStatus	Response status returned by gateway.
gatewayTransactionId	UPI request id returned by gateway for the transaction.
gstAmount	Gst applied on the MDR charged
mdrAmount	MDR applied on the total transaction amount
merchantChannelId	Unique id for the channel via which request is made.
merchantId	Unique id for merchant.
merchantRequestId	Request id used for the mandate transaction.
netSettlementAmount	Net amount which needs to be settled (netSettlementAmount = txnAmount - (mdrAmount + gstAmount))
orgMandateId	Refers to upiRequestId used during creation of mandate.
payeeMcc	Merchant Category Code of the payee merchant.
payeeVpa	Vpa of the Merchant
payerVpa	Vpa of the customer
refUrl	Invoice as sent by merchant or reference to the mandate in the form of url.
seqNumber optional applicable only for collect mandate	Denotes the recurring cycle of mandate execution. Will be received only during mandate executions. It will only be present in case of mandate request.
riskScore optional	RiskScore shared by NPCI or Bank
transactionTimestamp	Timestamp of when the transaction was attempted.
type	Event type of the callback
udfParameters optional	Stringified json for udf parameters.
umn	Vpa used for execution of mandate.

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Mandate Executed Successfully
QA	FAILURE	MANDATE IS PAUSED
QB	FAILURE	MANDATE IS ALREADY HONOURED
QC	FAILURE	MANDATE IS REVOKED
QD	FAILURE	MANDATE HAS EXPIRED
Z6	FAILURE	Number of pin tries exceeded.
ZM	FAILURE	Invalid mpin.
01	PENDING	Comes when the NPCI API call times out, use status check API to update the transaction status.
U69	EXPIRED	execute request expired
Else	FAILURE	Any other reason.

Outgoing Notification Mandate From Merchant

# A callback with following POST data will be sent to the configured url :

{
  "amount" : "9.00",
  "gatewayReferenceId" : "809323430413",
  "gatewayResponseCode" : "00",
  "gatewayResponseMessage" : "Notification is successful",
  "gatewayResponseStatus": "SUCCESS",
  "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
  "merchantChannelId" : "MERCHANTAPP",
  "merchantId" : "MERCHANT",
  "merchantRequestId": "TXN1234567",
  "nextExecution" : "2017-06-09T17:57:49+05:30",
  "orgMandateId" : "ABZ0f018ee5bc8b428fb979cb4a53ea9bde",
  "type": "MERCHANT_NOTIFICATION_MANDATE"
  "udfParameters" : "{}"
  "umn" : "customervpa@bank",
}

Server sends a callback to the Merchant to the url configured when mandate is notified prior to execution.

Parameter	Description
amount	Amount of Mandate.
gatewayReferenceId	Customer reference number (rrn)
gatewayResponseCode	Response code returned by gateway for the mandate.
gatewayResponseMessage	Response message returned by gateway for the transaction.
gatewayResponseStatus	Response status returned by gateway.
gatewayTransactionId	upiRequestId as passed on request
merchantChannelId	Unique id for the channel via which request is made.
merchantId	Unique id for merchant.
merchantRequestId	Request id used for the mandate notification.
nextExecution	Time at which the corresponding execution of mandate will take place
orgMandateId	gatewayMandateId passed in the response of webMandate.
type	Event type of the callback
udfParameters	Stringified json for udf parameters.
umn	Vpa used for execution of mandate.

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Mandate successfully notified.
Else	FAILURE	Any other reason.

Mandate Status Update

# A callback with following POST data will be sent to the configured url :

{
  "amount": "100.00",
  "amountRule": "EXACT",
  "blockFund": "true",
  "gatewayMandateId": "APL71f7d43bdf64d72d9saddfded",
  "gatewayReferenceId": "809323430413"
  "gatewayResponseCode": "00",
  "gatewayResponseMessage": "Mandate Validity End is Over"
  "gatewayResponseStatus": "SUCCESS",
  "initiatedBy" : "PAYER",
  "mandateName": "merchant mandate",
  "mandateTimestamp": "2020-06-01T15:40:42+05:30",
  "merchantChannelId": "APL",
  "merchantId": "APL",
  "orgMandateId": "APLMsleiuryufhuhsoisdjfadb48003sdaa0",
  "pauseEnd": "2019/09/19",
  "pauseStart": "2019/09/17",
  "payeeMcc": "4121",
  "payeeName": "APLTEST",
  "payeeVpa": "test@apl",
  "payerName": "ABC",
  "payerRevocable": "true",
  "payerVpa": "9962463212@apl",
  "recurrencePattern": "MONTHLY",
  "recurrenceRule": "ON",
  "recurrenceValue": "5",
  "refUrl": "https://www.abcxyz.com/",
  "remarks": "Mandate Validity Over",
  "role": "PAYER",
  "shareToPayee": "true",
  "status": "COMPLETED",
  "transactionType": "UPI_MANDATE",
  "type": "MANDATE_STATUS_UPDATE"
  "umn": "uniqueMandateNumber@apl",
  "validityEnd": "2020/06/05",
  "validityStart": "2020/06/04"
}

Server sends a callback to the Merchant to the url configured when mandate status gets updated. This status update is internal and does not depends on NPCI. It will be sent in the following scenarios :

1. When ONETIME mandate gets executed successfully or three attempts to execute ONETIME mandate gets over, then this callback will be sent with the value of status field as COMPLETED.

2. When validityEnd of a mandate passes the specified date, then this callback will be sent with the value of status field as COMPLETED.

3. When a mandate is in PAUSE state and the pauseEnd date passes the specified date, then this callback will be sent with the value of status field as SUCCESS. So, this callback denotes that mandate was UNPAUSED after pauseEnd got over. The status SUCCESS denotes that mandate is resumed and can be excecuted.

4. When a future pauseStart date is given during the Pause request, then this callback will be sent with the value of status field as PAUSE when the current date matches with the specified pauseStartDate. The status PAUSE denotes that mandate is currently Paused and cannot be excecuted.

Parameter	Description
amount	Amount of Mandate. Numeric string with two decimals.
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.
blockFund	Denotes whether customer's fund should be blocked or not. For Onetime mandate, value can be true or false and for recurring mandate it is always false.
gatewayMandateId	UPI request id returned by gateway for the mandate request. It will be same gatewayMandateId returned during create mandate.
gatewayReferenceId	Customer reference number (rrn) for the mandate operation. It will be same gatewayReferenceId returned during create mandate.
gatewayResponseCode	Response code returned by gateway for the mandate. Refer the table below for all possible values.
gatewayResponseMessage	Response message returned by gateway for the mandate.
gatewayResponseStatus	Denotes the current status of the mandate. Refer the table below for all possible values.
initiatedBy	Describes whether PAYER or PAYEE has initiated the mandate request. Its value will be PAYER or PAYEE depending to whom this callback is being send. If it is send to PAYER, value will PAYER and same for PAYEE. It will have same value as role.
mandateName	Name of the mandate.
mandateTimestamp	Timestamp of when the mandate request was attempted.
merchantChannelId	Unique id for the channel via which request is made.
merchantId	Unique id for merchant.
orgMandateId	gatewayMandateId passed in the response of webMandate or create mandate.
pauseEnd conditional	Date until which mandate is paused. It will only be present if status is "SUCCESS" or "PAUSE"
pauseStart conditional	Date from which mandate is paused. It will only be present if status is "SUCCESS" or "PAUSE"
payeeMcc	Merchant Category Code of the payee merchant. If Payee is a customer it will be "0000" else it will be a 4 digit numeric string.
payeeName optioanl	Name of the Payee involved in mandate. It will be present if role is PAYER
payeeVpa	Vpa of the payee.
payerName optional	Name of the Payer involved in mandate. It will be present if role is PAYEE
payerRevocable	Denotes whether mandate can be revoke by payer or not. If while requesting mandate Payee passes this flag is true, mandate can be revoked by Payer else it cannot be revoked by Payer. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
payerVpa	Vpa of the payer.
recurrencePattern	Recurrence Pattern for Mandate. Possible values are ONETIME, DAILY, WEEKLY, FORTNIGHTLY,MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED
recurrenceRule conditional	Recurrence Rule for Mandate. Possible values are ON, BEFORE, AFTER. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
recurrencValue conditional	Recurrence Value for Mandate. Possible values are 1-31 and depends on the recurrencePattern. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
refUrl	Invoice as sent by merchant or reference to the mandate in the form of url. This is a field which is majorly for future purpose and is send by the Payee.
remarks	Any mandate summary
role	Role of the customer for this mandate.
shareToPayee	Denotes whether mandate should be shared with payee or not. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
status	Updated Status of the mandate. It will be COMPLETED if mandate validity end gets over or if Onetime mandate gets executed. It will be PAUSE if mandate is paused because of future date passed during Pause Mandate API and it will be SUCCESS if mandate is Unpaused because of PauseEnd date getting passed. Various fields in this callback like gatewayMandateId, gatewayReferenceId, merchantRequest depends on the value of status.
transactionType	Type of Mandate Creation.
type	Event type of the callback.
umn	Vpa used for execution of mandate.
validityEnd	Date until which mandate can be executed.
validityStart	Date after which mandate can be executed.

gatewayResponseCode	gatewayResponseStatus	Description
JPMUP	UNPAUSE	Mandate is Unpaused.
JPMP	PAUSED	Mandate is paused.
JPMC	COMPLETED	Mandate is completed.
Else	FAILURE	Any other reason.

Mandate Payer API Callbacks

Incoming Create Mandate Request For Customer

# A callback with following POST data will be sent to the configured url :

{
  "amount": "100.00",
  "amountRule": "EXACT",
  "blockFund": "true",
  "expiry": "2020-07-25T00:30:00+05:30",
  "gatewayMandateId": "APL71f7d43bdf64d72d9saddfded",
  "gatewayReferenceId": "809323430413",
  "initiatedBy": "PAYER",
  "isMarkedSpam": "true",
  "isVerifiedPayee": "true",
  "mandateName": "merchant mandate",
  "mandateTimestamp": "2020-06-01T15:40:42+05:30",
  "merchantChannelId": "APL",
  "merchantCustomerId": "DEMO-CUST-1234",
  "merchantId": "APL",
  "orgMandateId": "APLMsleiuryufhuhsoisdjfadb48003sdaa0",
  "payeeMcc": "4121",
  "payeeName": "APLTEST",
  "payeeVpa": "test@apl",
  "payerRevocable": "true",
  "payerVpa": "9962463212@apl",
  "recurrencePattern": "MONTHLY",
  "recurrenceRule": "ON",
  "recurrenceValue": "5",
  "refUrl": "https://www.abcxyz.com/",
  "remarks": "Sample Remarks",
  "role": "PAYER",
  "shareToPayee": "true",
  "transactionType": "UPI_MANDATE",
  "type": "CUSTOMER_INCOMING_MANDATE_CREATE_REQUEST_RECEIVED",
  "umn": "uniqueMandateNumber@apl",
  "validityEnd": "2020/06/05",
  "validityStart": "2020/06/04"
}

Server sends a callback to the PAYER to the url configured when mandate creation request is received. This callback is only received when a mandate is requested by Payee and it has to be either approved or declined by Payer.

Parameter	Description
amount	Amount of Mandate. Numeric string with two decimals.
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.
blockFund	Denotes whether customer's fund should be blocked or not. For Onetime mandate, value can be true or false and for recurring mandate it is always false.
expiry	Timestamp until which create mandate request is valid.
gatewayMandateId	upiRequestId passed in the request.
gatewayReferenceId	Customer reference number (rrn)
initiatedBy	Describes whether PAYER or PAYEE has initiated the mandate.
isMarkedSpam	Flag if the payeeVpa is marked as spam. true, false
isVerifiedPayee	Flag if the payeeVpa is a verified vpa. true, false
mandateName	Name of the mandate.
mandateTimestamp	Timestamp of when the mandate request was attempted.
merchantChannelId	Unique id for the channel via which request is made.
merchantCustomerId	Merchant generated unique id for customer
merchantId	Unique id for merchant.
orgMandateId	Refers to upiRequestId used during creation of mandate.
payeeMcc	Merchant Category Code of the payee merchant. If Payee is a customer it will be "0000" else it will be a 4 digit numeric string.
payeeName optional	Name of the Payee involved in mandate. It will be present if role is PAYER
payeeVpa	Vpa of the payee.
payerRevocable	Denotes whether mandate can be revoke by payer or not. If while requesting mandate Payee passes this flag is true, mandate can be revoked by Payer else it cannot be revoked by Payer. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
payerVpa	Vpa of the payer.
recurrencePattern	Recurrence Pattern for Mandate. Possible values are ONETIME, DAILY, WEEKLY, FORTNIGHTLY,MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED
recurrenceRule conditional	Recurrence Rule for Mandate. Possible values are ON, BEFORE, AFTER. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
recurrencValue conditional	Recurrence Value for Mandate. Possible values are 1-31 and depends on the recurrencePattern. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
refUrl	Invoice as sent by merchant or reference to the mandate in the form of url. This is a field which is majorly for future purpose and is send by the Payee.
remarks	Any mandate summary
role	Role of the customer for this mandate. PAYER,PAYEE
shareToPayee	Denotes whether mandate should be shared with payee or not. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
transactionType	Type of Mandate Creation
type	Event type of the callback
umn optional	Vpa used for execution of mandate. It will be not present, if the merchantGeneratedUmn flag is set to true.
validityEnd	Date until which mandate can be executed.
validityStart	Date after which mandate can be executed.

Incoming Create Mandate For Customer

# A callback with following POST data will be sent to the configured url :

{
  "amount": "100.00",
  "amountRule": "EXACT",
  "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070"
  "blockFund": "true",
  "expiry": "2020-07-25T00:30:00+05:30",
  "gatewayMandateId": "APL71f7d43bdf64d72d9saddfded",
  "gatewayReferenceId": "809323430413"
  "gatewayResponseCode": "00",
  "gatewayResponseMessage": "Mandate is successfully created"
  "gatewayResponseStatus": "SUCCESS",
  "initiatedBy": "PAYER",
  "mandateApprovalTimestamp" : "2017-06-09T17:58:49+05:30",
  "mandateName": "merchant mandate",
  "mandateTimestamp": "2020-06-01T15:40:42+05:30",
  "merchantChannelId": "APL",
  "merchantCustomerId": "DEMO-CUST-1234",
  "merchantId": "APL",
  "merchantRequestId": "6138ne3wswbsssddc4dddc",
  "orgMandateId": "APLMsleiuryufhuhsoisdjfadb48003sdaa0",
  "payeeMcc": "4121",
  "payeeName": "APLTEST",
  "payeeVpa": "test@apl",
  "payerName": "ABC",
  "payerRevocable": "true",
  "payerVpa": "9962463212@apl",
  "recurrencePattern": "MONTHLY",
  "recurrenceRule": "ON",
  "recurrenceValue": "5",
  "refUrl": "https://www.abcxyz.com/",
  "remarks": "Sample Remarks",
  "role": "PAYER",
  "shareToPayee": "true",
  "transactionType": "UPI_MANDATE",
  "type": "CUSTOMER_INCOMING_MANDATE_CREATED",
  "udfParameters" : "{}"
  "umn": "uniqueMandateNumber@apl",
  "validityEnd": "2020/06/05",
  "validityStart": "2020/06/04"
}

Server sends a callback to the customer (PAYER/PAYEE) to the url configured when mandate is created. This callback is sent in the following two cases.

1. It is sent to Payer when a Payer approves the mandate request from Payee and the final response of mandate creation is received from NPCI. It is sent when Payer approves the mandate and not when Payer Declines the mandate.

2. It is sent to Payee when a Payer creates a mandate and final status of mandate creation is received from NPCI.

Parameter	Description
amount	Amount of Mandate. Numeric string with two decimals.
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.
bankAccountUniqueId	Unique id for the bank account to be linked
blockFund	Denotes whether customer's fund should be blocked or not. For Onetime mandate, value can be true or false and for recurring mandate it is always false.
expiry optional	Timestamp until which create mandate request is valid. It will be present only when payee has initiated the mandate.
gatewayMandateId	upiRequestId passed in the request.
gatewayReferenceId	Customer reference number (rrn).
gatewayResponseCode	Response code returned by gateway for the mandate.
gatewayResponseMessage	Response message returned by gateway for the mandate.
gatewayResponseStatus	Response status returned by gateway.
initiatedBy	Describes whether PAYER or PAYEE has initiated the mandate.
mandateApprovalTimestamp Optional	Time instant at which create mandate request was approved. Only present if mandate was initiatedBy Payee. Timestamp in YYYY-MM-DDTHH:MM:SS+05:30 format.
mandateName	Name of the mandate.
mandateTimestamp	Timestamp of when the mandate request was attempted. Timestamp in YYYY-MM-DDTHH:MM:SS+05:30 format.
merchantChannelId	Unique id for the channel via which request is made.
merchantCustomerId	Merchant generated unique id for customer.
merchantId	Unique id for merchant.
merchantRequestId optional	Request id used for the mandate. It will be merchantRequestId that is passed during approve mandate if mandate is initiated by Payee else it will be refId that is received from NPCI for Payer initiated mandate. It will not be present if gatewayResponseStatus is expired.
orgMandateId	Refers to upiRequestId used during creation of mandate.
payeeMcc	Merchant Category Code of the payee merchant. If Payee is a customer it will be "0000" else it will be a 4 digit numeric string.
payeeName optioanl	Name of the Payee involved in mandate. It will be present if role is PAYER
payeeVpa	Vpa of the payee.
payerName optional	Name of the Payer involved in mandate. It will be present if role is PAYEE
payerRevocable	Denotes whether mandate can be revoke by payer or not. If while requesting mandate Payee passes this flag is true, mandate can be revoked by Payer else it cannot be revoked by Payer. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
payerVpa	Vpa of the payer.
recurrencePattern	Recurrence Pattern for Mandate. Possible values are ONETIME, DAILY, WEEKLY, FORTNIGHTLY,MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED
recurrenceRule conditional	Recurrence Rule for Mandate. Possible values are ON, BEFORE, AFTER. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
recurrencValue conditional	Recurrence Value for Mandate. Possible values are 1-31 and depends on the recurrencePattern. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
refUrl	Invoice as sent by merchant or reference to the mandate in the form of url. This is a field which is majorly for future purpose and is send by the Payee.
remarks	Any mandate summary
role	Role of the customer for this mandate. PAYER,PAYEE
shareToPayee	Denotes whether mandate should be shared with payee or not. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
transactionType	Type of Mandate Creation
type	Event type of the callback
udfParameters optional	Stringified json for udf parameters. It will be present only if passed during Approve mandate API request.
umn	Vpa used for execution of mandate.
validityEnd	Date until which mandate can be executed.
validityStart	Date after which mandate can be executed.

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Payment Success.
UM3	EXPIRED	Mandate request expired.
Else	FAILURE	Any other reason.

Outgoing Create Mandate From Customer

# A callback with following POST data will be sent to the configured url :

{
  "amount": "100.00",
  "amountRule": "EXACT",
  "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070"
  "blockFund": "true",
  "expiry": "2020-07-25T00:30:00+05:30",
  "gatewayMandateId": "APL71f7d43bdf64d72d9saddfded",
  "gatewayReferenceId": "809323430413"
  "gatewayResponseCode": "00",
  "gatewayResponseMessage": "Mandate is successfully created"
  "gatewayResponseStatus": "SUCCESS",
  "initiatedBy": "PAYER",
  "mandateApprovalTimestamp" : "2017-06-09T17:58:49+05:30",
  "mandateName": "merchant mandate",
  "mandateTimestamp": "2020-06-01T15:40:42+05:30",
  "merchantChannelId": "APL",
  "merchantCustomerId": "DEMO-CUST-1234",
  "merchantId": "APL",
  "merchantRequestId": "6138ne3wswbsssddc4dddc",
  "orgMandateId": "APLMsleiuryufhuhsoisdjfadb48003sdaa0",
  "payeeMcc": "4121",
  "payeeName": "APLTEST",
  "payeeVpa": "test@apl",
  "payerName": "ABC",
  "payerRevocable": "true",
  "payerVpa": "9962463212@apl",
  "recurrencePattern": "MONTHLY",
  "recurrenceRule": "ON",
  "recurrenceValue": "5",
  "refUrl": "https://www.abcxyz.com/",
  "remarks": "Sample Remarks",
  "role": "PAYEE",
  "shareToPayee": "true",
  "transactionType": "UPI_MANDATE",
  "type": "CUSTOMER_OUTGOING_MANDATE_CREATED",
  "udfParameters" : "{}"
  "umn": "uniqueMandateNumber@apl",
  "validityEnd": "2020/06/05",
  "validityStart": "2020/06/04"
}

Server sends a callback to the customer (PAYER/PAYEE) to the url configured when the final status of mandate creation is received from NPCI. It is sent to the same entity whoever has initiated the mandate.

Parameter	Description
amount	Amount of Mandate. Numeric string with two decimals.
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.
bankAccountUniqueId	Unique id for the bank account to be linked
blockFund	Denotes whether customer's fund should be blocked or not. For Onetime mandate, value can be true or false and for recurring mandate it is always false.
expiry optional	Timestamp until which create mandate request is valid. It will be present only when payee has initiated the mandate.
gatewayMandateId	upiRequestId passed in the request.
gatewayReferenceId	Customer reference number (rrn).
gatewayResponseCode	Response code returned by gateway for the mandate.
gatewayResponseMessage	Response message returned by gateway for the mandate.
gatewayResponseStatus	Response status returned by gateway.
initiatedBy	Describes whether PAYER or PAYEE has initiated the mandate.
mandateApprovalTimestamp Optional	Time instant at which create mandate request was approved. Only present if mandate was initiatedBy Payee. Timestamp in YYYY-MM-DDTHH:MM:SS+05:30 format.
mandateName	Name of the mandate.
mandateTimestamp	Timestamp of when the mandate request was attempted. Timestamp in YYYY-MM-DDTHH:MM:SS+05:30 format.
merchantChannelId	Unique id for the channel via which request is made.
merchantCustomerId	Merchant generated unique id for customer.
merchantId	Unique id for merchant.
merchantRequestId	Request id used for the mandate. It is merchantRequestId that is passed during initiation of mandate.
orgMandateId	Refers to upiRequestId used during creation of mandate.
payeeMcc	Merchant Category Code of the payee merchant. If Payee is a customer it will be "0000" else it will be a 4 digit numeric string.
payeeName optioanl	Name of the Payee involved in mandate. It will be present if role is PAYER
payeeVpa	Vpa of the payee.
payerName optional	Name of the Payer involved in mandate. It will be present if role is PAYEE
payerRevocable	Denotes whether mandate can be revoke by payer or not. If while requesting mandate Payee passes this flag is true, mandate can be revoked by Payer else it cannot be revoked by Payer. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
payerVpa	Vpa of the payer.
recurrencePattern	Recurrence Pattern for Mandate. Possible values are ONETIME, DAILY, WEEKLY, FORTNIGHTLY,MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED
recurrenceRule conditional	Recurrence Rule for Mandate. Possible values are ON, BEFORE, AFTER. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
recurrencValue conditional	Recurrence Value for Mandate. Possible values are 1-31 and depends on the recurrencePattern. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
refUrl	Invoice as sent by merchant or reference to the mandate in the form of url. This is a field which is majorly for future purpose and is send by the Payee.
remarks	Any mandate summary
role	Role of the customer for this mandate. PAYER,PAYEE
shareToPayee	Denotes whether mandate should be shared with payee or not. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
transactionType	Type of Mandate Creation
type	Event type of the callback
udfParameters optional	Stringified json for udf parameters. It will be present only if passed during create mandate API request.
umn optional	Vpa used for execution of mandate. It will not be present if gatewayResponseStatus is EXPIRED or if it is not received from NPCI due to validation failure at Payer PSP during approve mandate.
validityEnd	Date until which mandate can be executed.
validityStart	Date after which mandate can be executed.

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Payment Success.
UM3	EXPIRED	Mandate request expired.
ZA	DECLINED	Mandate request Declined by Payer.
Else	FAILURE	Any other reason.

Incoming Update Mandate Request For Customer

# A callback with following POST data will be sent to the configured url :

{
  "amount": "100.00",
  "amountRule": "EXACT",
  "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070"
  "blockFund": "true",
  "expiry": "2020-07-25T00:30:00+05:30",
  "gatewayMandateId": "APL71f7d43bdf64d72d9saddfded",
  "gatewayReferenceId": "809323430413"
  "initiatedBy": "PAYER",
  "mandateName": "merchant mandate",
  "mandateTimestamp": "2020-06-01T15:40:42+05:30",
  "mandateType" : "UPDATE",
  "merchantChannelId": "APL",
  "merchantCustomerId": "DEMO-CUST-1234",
  "merchantId": "APL",
  "orgMandateId": "APLMsleiuryufhuhsoisdjfadb48003sdaa0",
  "payeeMcc": "4121",
  "payeeName": "APLTEST",
  "payeeVpa": "test@apl",
  "payerName": "ABC",
  "payerRevocable": "true",
  "payerVpa": "9962463212@apl",
  "recurrencePattern": "MONTHLY",
  "recurrenceRule": "ON",
  "recurrenceValue": "5",
  "refUrl": "https://www.abcxyz.com/",
  "remarks": "Sample Remarks",
  "role": "PAYER",
  "shareToPayee": "true",
  "transactionType": "UPI_MANDATE",
  "type": "CUSTOMER_INCOMING_MANDATE_UPDATE_REQUEST_RECEIVED",
  "umn": "uniqueMandateNumber@apl",
  "validityEnd": "2020/06/05",
  "validityStart": "2020/06/04"
}

Server sends a callback to the PAYER to the url configured when mandate updation request is received. This callback is only received when a update mandate is requested by Payee and it has to be either approved or declined by Payer.

Parameter	Description
amount	Amount of Mandate. Numeric string with two decimals.
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.
bankAccountUniqueId	Unique id for the bank account to be linked
blockFund	Denotes whether customer's fund should be blocked or not. For Onetime mandate, value can be true or false and for recurring mandate it is always false.
expiry	Timestamp until which create mandate request is valid.
mandateName	Name of the mandate.
mandateTimestamp	Timestamp of when the mandate request was attempted.
gatewayMandateId	upiRequestId passed in the request.
gatewayReferenceId	Customer reference number (rrn)
initiatedBy	Describes whether PAYER or PAYEE has initiated the mandate.
mandateTimestamp	Timestamp of when the mandate request was attempted.
mandateType	Denotes the type of mandate operation. Values can be UPDATE/REVOKE.
merchantChannelId	Unique id for the channel via which request is made.
merchantCustomerId	Merchant generated unique id for customer
merchantId	Unique id for merchant.
orgMandateId	Refers to upiRequestId used during creation of mandate.
payeeMcc	Merchant Category Code of the payee merchant. If Payee is a customer it will be "0000" else it will be a 4 digit numeric string.
payeeName optioanl	Name of the Payee involved in mandate. It will be present if role is PAYER
payeeVpa	Vpa of the payee.
payerName optional	Name of the Payer involved in mandate. It will be present if role is PAYEE
payerRevocable	Denotes whether mandate can be revoke by payer or not. If while requesting mandate Payee passes this flag is true, mandate can be revoked by Payer else it cannot be revoked by Payer. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
payerVpa	Vpa of the payer.
recurrencePattern	Recurrence Pattern for Mandate. Possible values are ONETIME, DAILY, WEEKLY, FORTNIGHTLY,MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED
recurrenceRule conditional	Recurrence Rule for Mandate. Possible values are ON, BEFORE, AFTER. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
recurrencValue conditional	Recurrence Value for Mandate. Possible values are 1-31 and depends on the recurrencePattern. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
refUrl	Invoice as sent by merchant or reference to the mandate in the form of url. This is a field which is majorly for future purpose and is send by the Payee.
remarks	Any mandate summary
role	Role of the customer for this mandate. PAYER,PAYEE
shareToPayee	Denotes whether mandate should be shared with payee or not. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
transactionType	Type of Mandate Creation
type	Event type of the callback
umn	Vpa used for execution of mandate.
validityEnd	Date until which mandate can be executed.
validityStart	Date after which mandate can be executed.

Incoming Update Mandate For Customer

# A callback with following POST data will be sent to the configured url :

{
  "amount": "100.00",
  "amountRule": "EXACT",
  "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070"
  "blockFund": "true",
  "expiry": "2020-07-25T00:30:00+05:30",
  "gatewayMandateId": "APL71f7d43bdf64d72d9saddfded",
  "gatewayReferenceId": "809323430413"
  "gatewayResponseCode": "00",
  "gatewayResponseMessage": "Mandate is successfully updated"
  "gatewayResponseStatus": "SUCCESS",
  "initiatedBy": "PAYER",
  "mandateName": "merchant mandate",
  "mandateTimestamp": "2020-06-01T15:40:42+05:30",
  "mandateType" : "UPDATE",
  "merchantChannelId": "APL",
  "merchantCustomerId": "DEMO-CUST-1234",
  "merchantId": "APL",
  "merchantRequestId": "6138ne3wswbsssddc4dddc",
  "orgMandateId": "APLMsleiuryufhuhsoisdjfadb48003sdaa0",
  "payeeMcc": "4121",
  "payeeName": "APLTEST",
  "payeeVpa": "test@apl",
  "payerName": "ABC",
  "payerRevocable": "true",
  "payerVpa": "9962463212@apl",
  "recurrencePattern": "MONTHLY",
  "recurrenceRule": "ON",
  "recurrenceValue": "5",
  "refUrl": "https://www.abcxyz.com/",
  "remarks": "Sample Remarks",
  "role": "PAYEE",
  "shareToPayee": "true",
  "transactionType": "UPI_MANDATE",
  "type": "CUSTOMER_INCOMING_MANDATE_UPDATED",
  "udfParameters" : "{}"
  "umn": "uniqueMandateNumber@apl",
  "validityEnd": "2020/06/05",
  "validityStart": "2020/06/04"
}

Server sends a callback to the customer (PAYER/PAYEE) to the url configured when mandate is created. This callback is sent in the following two cases.

1. It is sent to Payer when a Payer approves the mandate update request from Payee and the final response of mandate updation is received from NPCI. It is sent when Payer approves the mandate request and not when Payer Declines the mandate request.

2. It is sent to Payee when a Payer update a mandate and final status of mandate updation is received from NPCI.

Parameter	Description
amount	Amount of Mandate. Numeric string with two decimals.
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.
bankAccountUniqueId	Unique id for the bank account to be linked
blockFund	Denotes whether customer's fund should be blocked or not. For Onetime mandate, value can be true or false and for recurring mandate it is always false.
expiry optional	Timestamp until which update mandate request is valid. It will be present only when payee has initiated the update mandate.
gatewayMandateId	upiRequestId passed in the request.
gatewayReferenceId	Customer reference number (rrn).
gatewayResponseCode	Response code returned by gateway for the mandate.
gatewayResponseMessage	Response message returned by gateway for the mandate.
gatewayResponseStatus	Response status returned by gateway.
initiatedBy	Describes whether PAYER or PAYEE has initiated the mandate.
mandateName	Name of the mandate.
mandateTimestamp	Timestamp of when the mandate request was attempted.
mandateType	Denotes the type of mandate operation. Values can be UPDATE/REVOKE.
merchantChannelId	Unique id for the channel via which request is made.
merchantCustomerId	Merchant generated unique id for customer.
merchantId	Unique id for merchant.
merchantRequestId optional	Request id used for the mandate. It will be merchantRequestId that is passed during approve mandate if mandate update request is initiated by Payee else it will be refId that is received from NPCI for Payer initiated update mandate. It will not be present if gatewayResponseStatus is expired.
orgMandateId	Refers to upiRequestId used during creation of mandate.
payeeMcc	Merchant Category Code of the payee merchant. If Payee is a customer it will be "0000" else it will be a 4 digit numeric string.
payeeName optioanl	Name of the Payee involved in mandate. It will be present if role is PAYER
payeeVpa	Vpa of the payee.
payerName optional	Name of the Payer involved in mandate. It will be present if role is PAYEE
payerRevocable	Denotes whether mandate can be revoke by payer or not. If while requesting mandate Payee passes this flag is true, mandate can be revoked by Payer else it cannot be revoked by Payer. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
payerVpa	Vpa of the payer.
recurrencePattern	Recurrence Pattern for Mandate. Possible values are ONETIME, DAILY, WEEKLY, FORTNIGHTLY,MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED
recurrenceRule conditional	Recurrence Rule for Mandate. Possible values are ON, BEFORE, AFTER. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
recurrencValue conditional	Recurrence Value for Mandate. Possible values are 1-31 and depends on the recurrencePattern. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
refUrl	Invoice as sent by merchant or reference to the mandate in the form of url. This is a field which is majorly for future purpose and is send by the Payee.
remarks	Any mandate summary
role	Role of the customer for this mandate. PAYER,PAYEE
shareToPayee	Denotes whether mandate should be shared with payee or not. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
transactionType	Type of Mandate Creation
type	Event type of the callback
udfParameters optional	Stringified json for udf parameters. It will be present only if passed during Approve mandate for update request.
umn	Vpa used for execution of mandate.
validityEnd	Date until which mandate can be executed.
validityStart	Date after which mandate can be executed.

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Payment Success.
UM3	EXPIRED	Mandate request expired.
Else	FAILURE	Any other reason.

Outgoing Update Mandate From Customer

# A callback with following POST data will be sent to the configured url :

{
  "amount": "100.00",
  "amountRule": "EXACT",
  "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070"
  "blockFund": "true",
  "expiry": "2020-07-25T00:30:00+05:30",
  "gatewayMandateId": "APL71f7d43bdf64d72d9saddfded",
  "gatewayReferenceId": "809323430413"
  "gatewayResponseCode": "00",
  "gatewayResponseMessage": "Mandate is successfully updated"
  "gatewayResponseStatus": "SUCCESS",
  "initiatedBy": "PAYER",
  "mandateName": "merchant mandate",
  "mandateTimestamp": "2020-06-01T15:40:42+05:30",
  "mandateType" : "UPDATE",
  "merchantChannelId": "APL",
  "merchantCustomerId": "DEMO-CUST-1234",
  "merchantId": "APL",
  "merchantRequestId": "6138ne3wswbsssddc4dddc",
  "orgMandateId": "APLMsleiuryufhuhsoisdjfadb48003sdaa0",
  "payeeMcc": "4121",
  "payeeName": "APLTEST",
  "payeeVpa": "test@apl",
  "payerName": "ABC",
  "payerRevocable": "true",
  "payerVpa": "9962463212@apl",
  "recurrencePattern": "MONTHLY",
  "recurrenceRule": "ON",
  "recurrenceValue": "5",
  "refUrl": "https://www.abcxyz.com/",
  "remarks": "Sample Remarks",
  "role": "PAYER",
  "shareToPayee": "true",
  "transactionType": "UPI_MANDATE",
  "type": "CUSTOMER_OUTGOING_MANDATE_UPDATED",
  "udfParameters" : "{}"
  "umn": "uniqueMandateNumber@apl",
  "validityEnd": "2020/06/05",
  "validityStart": "2020/06/04"
}

Server sends a callback to the customer (PAYER/PAYEE) to the url configured when the final status of mandate updation is received from NPCI. It is sent to the same entity whoever has initiated the mandate request.

Parameter	Description
amount	Amount of Mandate. Numeric string with two decimals.
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.
bankAccountUniqueId	Unique id for the bank account to be linked
blockFund	Denotes whether customer's fund should be blocked or not. For Onetime mandate, value can be true or false and for recurring mandate it is always false.
expiry optional	Timestamp until which create mandate request is valid. It will be present only when payee has initiated the mandate.
gatewayMandateId	upiRequestId passed in the request.
gatewayReferenceId	Customer reference number (rrn).
gatewayResponseCode	Response code returned by gateway for the mandate.
gatewayResponseMessage	Response message returned by gateway for the mandate.
gatewayResponseStatus	Response status returned by gateway.
initiatedBy	Describes whether PAYER or PAYEE has initiated the mandate.
mandateName	Name of the mandate.
mandateTimestamp	Timestamp of when the mandate request was attempted.
mandateType	Denotes the type of mandate operation. Values can be UPDATE/REVOKE.
merchantChannelId	Unique id for the channel via which request is made.
merchantCustomerId	Merchant generated unique id for customer.
merchantId	Unique id for merchant.
merchantRequestId	Request id used for the mandate. It is merchantRequestId that is passed during initiation of mandate request.
orgMandateId	Refers to upiRequestId used during creation of mandate.
payeeMcc	Merchant Category Code of the payee merchant. If Payee is a customer it will be "0000" else it will be a 4 digit numeric string.
payeeName optioanl	Name of the Payee involved in mandate. It will be present if role is PAYER
payeeVpa	Vpa of the payee.
payerName optional	Name of the Payer involved in mandate. It will be present if role is PAYEE
payerRevocable	Denotes whether mandate can be revoke by payer or not. If while requesting mandate Payee passes this flag is true, mandate can be revoked by Payer else it cannot be revoked by Payer. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
payerVpa	Vpa of the payer.
recurrencePattern	Recurrence Pattern for Mandate. Possible values are ONETIME, DAILY, WEEKLY, FORTNIGHTLY,MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED
recurrenceRule conditional	Recurrence Rule for Mandate. Possible values are ON, BEFORE, AFTER. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
recurrencValue conditional	Recurrence Value for Mandate. Possible values are 1-31 and depends on the recurrencePattern. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
refUrl	Invoice as sent by merchant or reference to the mandate in the form of url. This is a field which is majorly for future purpose and is send by the Payee.
remarks	Any mandate summary
role	Role of the customer for this mandate. PAYER,PAYEE
shareToPayee	Denotes whether mandate should be shared with payee or not. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
transactionType	Type of Mandate Creation
type	Event type of the callback
udfParameters optional	Stringified json for udf parameters. It will be present only if passed during update mandate API request.
umn	Vpa used for execution of mandate.
validityEnd	Date until which mandate can be executed.
validityStart	Date after which mandate can be executed.

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Payment Success.
UM3	EXPIRED	Mandate request expired.
QT	DECLINED	Mandate request Declined by Payer.
Else	FAILURE	Any other reason.

Outgoing Pause Mandate From Customer

# A callback with following POST data will be sent to the configured url :

{
  "amount": "100.00",
  "amountRule": "EXACT",
  "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070"
  "blockFund": "true",
  "gatewayMandateId": "APL71f7d43bdf64d72d9saddfded",
  "gatewayReferenceId": "809323430413"
  "gatewayResponseCode": "00",
  "gatewayResponseMessage": "Mandate is successfully paused"
  "gatewayResponseStatus": "SUCCESS",
  "initiatedBy" : "PAYER",
  "mandateName": "merchant mandate",
  "mandateTimestamp": "2020-06-01T15:40:42+05:30",
  "mandateType" : "PAUSE",
  "merchantChannelId": "APL",
  "merchantCustomerId": "DEMO-CUST-1234",
  "merchantId": "APL",
  "merchantRequestId": "6138ne3wswbsssddc4dddc",
  "orgMandateId": "APLMsleiuryufhuhsoisdjfadb48003sdaa0",
  "pauseEnd": "2019/09/19",
  "pauseStart": "2019/09/17",
  "payeeMcc": "4121",
  "payeeName": "APLTEST",
  "payeeVpa": "test@apl",
  "payerName": "ABC",
  "payerRevocable": "true",
  "payerVpa": "9962463212@apl",
  "recurrencePattern": "MONTHLY",
  "recurrenceRule": "ON",
  "recurrenceValue": "5",
  "refUrl": "https://www.abcxyz.com/",
  "remarks": "Sample Remarks",
  "role": "PAYER",
  "shareToPayee": "true",
  "transactionType": "UPI_MANDATE",
  "type": "CUSTOMER_OUTGOING_MANDATE_PAUSED",
  "udfParameters" : "{}"
  "umn": "uniqueMandateNumber@apl",
  "validityEnd": "2020/06/05",
  "validityStart": "2020/06/04"
}

Server sends a callback to the Payer to the url configured when the final status of mandate PAUSE/UNPAUSE request is received from NPCI. It is always sent to the Payer as mandate Pause request can be initiated by Payer only.

Parameter	Description
amount	Amount of Mandate. Numeric string with two decimals.
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.
bankAccountUniqueId	Unique id for the bank account to be linked
blockFund	Denotes whether customer's fund should be blocked or not. For Onetime mandate, value can be true or false and for recurring mandate it is always false.
gatewayMandateId	upiRequestId passed in the request.
gatewayReferenceId	Customer reference number (rrn).
gatewayResponseCode	Response code returned by gateway for the mandate.
gatewayResponseMessage	Response message returned by gateway for the mandate.
gatewayResponseStatus	Response status returned by gateway.
initiatedBy	Describes whether PAYER or PAYEE has initiated the mandate.
mandateName	Name of the mandate.
mandateTimestamp	Timestamp of when the mandate request was attempted.
mandateType	Denotes the type of mandate operation. Values can be PAUSE/UNPAUSE.
merchantChannelId	Unique id for the channel via which request is made.
merchantCustomerId	Merchant generated unique id for customer.
merchantId	Unique id for merchant.
merchantRequestId	Request id used for the mandate operation. It is merchantRequestId that is passed during initiation of mandate request.
orgMandateId	Refers to upiRequestId used during creation of mandate.
pauseEnd	Date until which mandate is paused
pauseStart	Date from which mandate is paused
payeeMcc	Merchant Category Code of the payee merchant. If Payee is a customer it will be "0000" else it will be a 4 digit numeric string.
payeeName optioanl	Name of the Payee involved in mandate. It will be present if role is PAYER
payeeVpa	Vpa of the payee.
payerName optional	Name of the Payer involved in mandate. It will be present if role is PAYEE
payerRevocable	Denotes whether mandate can be revoke by payer or not. If while requesting mandate Payee passes this flag is true, mandate can be revoked by Payer else it cannot be revoked by Payer. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
payerVpa	Vpa of the payer.
recurrencePattern	Recurrence Pattern for Mandate. Possible values are ONETIME, DAILY, WEEKLY, FORTNIGHTLY,MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED
recurrenceRule conditional	Recurrence Rule for Mandate. Possible values are ON, BEFORE, AFTER. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
recurrencValue conditional	Recurrence Value for Mandate. Possible values are 1-31 and depends on the recurrencePattern. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
refUrl	Invoice as sent by merchant or reference to the mandate in the form of url. This is a field which is majorly for future purpose and is send by the Payee.
remarks	Any mandate summary
role	Role of the customer for this mandate. PAYER,PAYEE
shareToPayee	Denotes whether mandate should be shared with payee or not. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
transactionType	Type of Mandate Creation
type	Event type of the callback
udfParameters optional	Stringified json for udf parameters. It will be present only if passed during pause mandate API request.
umn	Vpa used for execution of mandate.
validityEnd	Date until which mandate can be executed.
validityStart	Date after which mandate can be executed.

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Payment Success.
Else	FAILURE	Any other reason.

Incoming Pre Payement Notification Mandate For Customer

# A callback with following POST data will be sent to the configured url :

{
  "amount" : "9.00",
  "gatewayMandateId" : "APL0f018ee5bc8b428fb979cb4a53ea9bde",
  "gatewayReferenceId" : "809323430413",
  "gatewayResponseCode": "00",
  "gatewayResponseMeassage": "Mandate Notification Received Successfully",
  "gatewayResponseStatus": "SUCCESS",
  "merchantChannelId" : "MERCHANTAPP",
  "merchantCustomerId" : "DEMO_CUST-1234",
  "merchantId" : "MERCHANT",
  "merchantRequestId" : "TXN1234567",
  "nextExecution" : "2017-06-09T17:57:49+05:30",
  "orgMandateId" : "APL0f018ee5b832468779cb4a53ea9bde".
  "seqNumber" : "1",
  "type": "CUSTOMER_INCOMING_PRE_PAYMENT_NOTIFICATION_MANDATE_RECEIVED",
  "umn" : "customervpa@bank",
}

Server sends a callback to the Payer to the url configured when pre-payment notification is received prior to mandate execution for the particular recurring cycle denoted by seqNumber.

Parameter	Description
amount	Amount of Mandate.
gatewayMandateId	upiRequestId passed in the request.
gatewayReferenceId	Customer reference number (rrn)
gatewayResponseCode	Response code returned by gateway for the mandate.
gatewayResponseMessage	Response message returned by gateway for the mandate.
gatewayResponseStatus	Response status returned by gateway.
merchantChannelId	Unique id for the channel via which request is made.
merchantCustomerId	Merchant generated unique id for customer
merchantId	Unique id for merchant.
merchantRequestId	Request id used for the notification.
nextExecution	Time at which the corresponding execution of mandate for the given seqNumber will take place.
orgMandateId	Refers to upiRequestId used during creation of mandate.
seqNumber	Denotes the recurring cycle of mandate execution. It generally increments by +1 for every recurring cycle. For example - If it is DAILY Mandate everyday it will be +1 from the previous day. For ONETIME mandate, its value is always 1 as ONETIME mandate can be executed only once.
type	Event type of the callback
umn	Vpa used for execution of mandate.

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Mandate Notification Received Successfully.
Else	FAILURE	Any other reason.

Mandate Status Update

# A callback with following POST data will be sent to the configured url :

{
  "amount": "100.00",
  "amountRule": "EXACT",
  "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070"
  "blockFund": "true",
  "gatewayMandateId": "APL71f7d43bdf64d72d9saddfded",
  "gatewayReferenceId": "809323430413"
  "gatewayResponseCode": "00",
  "gatewayResponseMessage": "Mandate Validity End is Over"
  "gatewayResponseStatus": "SUCCESS",
  "initiatedBy" : "PAYER",
  "mandateName": "merchant mandate",
  "mandateTimestamp": "2020-06-01T15:40:42+05:30",
  "merchantChannelId": "APL",
  "merchantCustomerId": "DEMO-CUST-1234",
  "merchantId": "APL",
  "orgMandateId": "APLMsleiuryufhuhsoisdjfadb48003sdaa0",
  "pauseEnd": "2019/09/19",
  "pauseStart": "2019/09/17",
  "payeeMcc": "4121",
  "payeeName": "APLTEST",
  "payeeVpa": "test@apl",
  "payerName": "ABC",
  "payerRevocable": "true",
  "payerVpa": "9962463212@apl",
  "recurrencePattern": "MONTHLY",
  "recurrenceRule": "ON",
  "recurrenceValue": "5",
  "refUrl": "https://www.abcxyz.com/",
  "remarks": "Mandate Validity Over",
  "role": "PAYER",
  "shareToPayee": "true",
  "transactionType": "UPI_MANDATE",
  "type": "MANDATE_STATUS_UPDATE"
  "umn": "uniqueMandateNumber@apl",
  "validityEnd": "2020/06/05",
  "validityStart": "2020/06/04"
}

Server sends a callback to the Merchant to the url configured when mandate status gets updated. This status update is internal and does not depends on NPCI. It will be sent in the following scenarios :

1. When ONETIME mandate gets executed successfully or three attempts to execute ONETIME mandate gets over, then this callback will be sent with the value of status field as COMPLETED.

2. When validityEnd of a mandate passes the specified date, then this callback will be sent with the value of status field as COMPLETED.

3. When a mandate is in PAUSE state and the pauseEnd date passes the specified date, then this callback will be sent with the value of status field as UNPAUSED. So, this callback denotes that mandate was UNPAUSED after pauseEnd got over. The status UNPAUSED denotes that mandate is resumed and can be excecuted.

4. When a future pauseStart date is given during the Pause request, then this callback will be sent with the value of status field as PAUSE when the current date matches with the specified pauseStartDate. The status PAUSE denotes that mandate is currently Paused and cannot be excecuted.

Parameter	Description
amount	Amount of Mandate. Numeric string with two decimals.
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount . If amountRule is EXACT, then mandate should always be executed for the same amount.
bankAccountUniqueId	Unique id for the bank account to be linked
blockFund	Denotes whether customer's fund should be blocked or not. For Onetime mandate, value can be true or false and for recurring mandate it is always false.
gatewayMandateId	UPI request id returned by gateway for the mandate request. It will be same gatewayMandateId returned during create mandate.
gatewayReferenceId	Customer reference number (rrn) for the mandate operation. It will be same gatewayReferenceId returned during create mandate.
gatewayResponseCode	Response code returned by gateway for the mandate. Refer the table below for all possible values.
gatewayResponseMessage	Response message returned by gateway for the mandate.
gatewayResponseStatus	Denotes the current status of the mandate. Refer the table below for all possible values.
initiatedBy	Describes whether PAYER or PAYEE has initiated the mandate request. Its value will be PAYER or PAYEE depending to whom this callback is being send. If it is send to PAYER, value will PAYER and same for PAYEE. It will have same value as role.
mandateName	Name of the mandate.
mandateTimestamp	Timestamp of when the mandate request was attempted.
merchantChannelId	Unique id for the channel via which request is made.
merchantCustomerId optional	Merchant generated unique id for customer. It will not be present if 'PAYEE' is merchant.
merchantId	Unique id for merchant.
orgMandateId	Refers to upiRequestId used during creation of mandate.
pauseEnd conditional	Date until which mandate is paused. It will only be present if status is "SUCCESS" or "PAUSE"
pauseStart conditional	Date from which mandate is paused. It will only be present if status is "SUCCESS" or "PAUSE"
payeeMcc	Merchant Category Code of the payee merchant. If Payee is a customer it will be "0000" else it will be a 4 digit numeric string.
payeeName optioanl	Name of the Payee involved in mandate. It will be present if role is PAYER
payeeVpa	Vpa of the payee.
payerName optional	Name of the Payer involved in mandate. It will be present if role is PAYEE
payerRevocable	Denotes whether mandate can be revoke by payer or not. If while requesting mandate Payee passes this flag is true, mandate can be revoked by Payer else it cannot be revoked by Payer. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
payerVpa	Vpa of the payer.
recurrencePattern	Recurrence Pattern for Mandate. Possible values are ONETIME, DAILY, WEEKLY, FORTNIGHTLY,MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED
recurrenceRule conditional	Recurrence Rule for Mandate. Possible values are ON, BEFORE, AFTER. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
recurrencValue conditional	Recurrence Value for Mandate. Possible values are 1-31 and depends on the recurrencePattern. It is not present if recurrencePattern is ONETIME, DAILY or ASPRESENTED.
refUrl	Invoice as sent by merchant or reference to the mandate in the form of url. This is a field which is majorly for future purpose and is send by the Payee.
remarks	Any mandate summary
role	Role of the customer for this mandate.
shareToPayee	Denotes whether mandate should be shared with payee or not. For Onetime mandate, value can be true or false and for recurring mandate it is always true. Default value is true.
transactionType	Type of Mandate Creation.
type	Event type of the callback.
umn	Vpa used for execution of mandate.
validityEnd	Date until which mandate can be executed.
validityStart	Date after which mandate can be executed.

gatewayResponseCode	gatewayResponseStatus	Description
JPMUP	UNPAUSE	Mandate is Unpaused.
JPMP	PAUSED	Mandate is paused.
JPMC	COMPLETED	Mandate is completed.
Else	FAILURE	Any other reason.

Complaint APIs

Complaint Raise

# Sample request

curl -L -X POST '{{host}}/api/n2/merchants/complaints/raise' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "adjAmount": "0.50",
  "adjFlag": "PBRB",
  "adjCode": "U010",
  "initiationMode": "U1",
  "purpose": "00",
  "merchantCustomerId": "XYZ123456",
  "merchantRequestId": "3764723469",
  "originalUpiRequestId": "AUT75533106f865d1a9wegrhjw9725e6891f",
  "remarks": "Amount not credited",
  "refCategory": "00",
  "refUrl": "https://www.abcxyz.com/",
  "type": "COMPLAINT",
  "upiRequestId": "AUT699393106f865d1a9467c59725e6891f",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "payerVpa": "abcd@apl",
    "payeeVpa": "xyz@apl",
    "customerMobileNumber": "919988776655",
    "merchantRequestId": "3764723469",
    "transactionAmount": "1.00",
    "reqAdjAmount": "0.50",
    "reqAdjFlag": "PBRB",
    "reqAdjCode": "U010",
    "crn": "941451534851394",
    "gatewayReferenceId": "123456",
    "gatewayComplaintId": "AUT699393106f865d1a9467c59725e6891f",
    "gatewayResponseCode": "00",
    "gatewayResponseStatus": "PENDING",
    "gatewayResponseMessage": "Your Complaint is Raised"
    }
,
  "udfParameters": "{}"
}

This Api will be used to raise a complaint on any transactions.

Note

1. Complaints shall be allowed only after '5' mins from the time of transaction and after transaction status check is done by the user.
2. For the below request type = "COMPLAINT" will correspond to one of the categories of "reqComplaint" api. We currently only use "COMPLAINT" because we don't serve other use cases. We have kept it as a field in request body for future api enhancements.
3. Provide request parameters "adjCode" and "adjFlag" based on below scenarios.

Transaction Type	Transaction Status	Adj Flag	Adj Code	Description
U2 (P2M)	Success	PBRB	U021	Credit not processed for cancelled or returned goods & services
U2 (P2M)	Success	PBRB	U008	Goods/services are not provided
U2 (P2M)	Success	PBRB	U022	Account debited but transaction confirmation not received by merchantAccount debited but transaction confirmation not received by merchant
U2 (P2M)	Success	PBRB	U023	Paid by alternate means/Duplicate payment
U2 (P2M)	Deemed	PBRB	U008	Goods/services are not provided
U2 (P2M)	Deemed	PBRB	U021	Credit not processed for cancelled or returned goods & services
U2 (P2M)	Deemed	PBRB	U022	Account debited but transaction confirmation not received by merchant
U2 (P2M)	Deemed	PBRB	U023	Paid by alternate means/Duplicate payment
U2 (P2M)	Failure	PBRB	U009	Customer account not credited back for failed merchant transaction
U3/UC (P2P)	Deemed	PBRB	U010	Beneficiary account is not credited for a pending / timeout transaction
U3/UC (P2P)	Failure	PBRB	U005	Customer account not credited back for failed P2P transaction

Request parameters

Parameter	Description	Constraints
merchantRequestId	Merchant generated id for the transaction	35 characters alphanumeric.
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
originalUpiRequestId	Unique id sent to UPI switch for the request of the transaction on which complaint complaint needs to raise	35 character alphanumeric. Should always start with merchant prefix provided.
remarks optional	Remarks or reason for complaint	String.
adjAmount optional	Amount of the transaction sent to NPCI.	Amount in two decimals. Decimals are mandatory.
adjFlag	Reason flag for complaint sent to NPCI	String.
adjCode	Reason Code for complaint sent to NPCI	String.
initiationMode optional	Defines the initiation mode of the transaction	Refer Request Structure section
type	Define the type of request	String COMPLAINT
purpose optional	Defines the purpose code of the transaction	Refer Request Structure section
refUrl optional	Invoice as sent by merchant in the form of url	String
refCategory optional	Details for refUrl, whether it is 01(advertisement), 02(invoice)	String
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
payerVpa	VPA of the customer to be used for payment	something@handle
payeeVpa	Vpa of the payee to whom money is being sent	something@handle
customerMobileNumber	Customer mobile number as per device binding	12 digits mobile number string
merchantRequestId	Merchant generated id for the transaction	35 characters alphanumeric.
transactionAmount	The total amount for which original transaction was performed	String with mandatory two decimals
reqAdjAmount	Amount of the transaction sent to NPCI	Amount in two decimals.
reqAdjFlag	Reason flag for complaint sent to NPCI	String.
reqAdjCode	Reason Code for complaint sent to NPCI	String.
crn optional	Complaint reference number returned by NPCI	14 to 16 characters alphanumeric.
gatewayReferenceId	Reference id returned by the gateway	String
gatewayComplaintId	Complaint id returned by gateway	String
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	PENDING, FAILURE
gatewayResponseMessage	Response message for code returned by gateway	String
udfParameters optional	Udf parameters as passed in the request	JSON string

Complaint Resolve

# Sample request

curl -L -X POST '{{host}}/api/n2/merchants/complaints/resolve' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantRequestId": "3764723469",
  "originalUpiRequestId": "AUT699393106f865d1a9wegrhjw9725e6891f",
  "originalTransactionUpiRequestId": "AUT699393106f865d1a9467c59725e6891f",
  "remarks": "Goods and services not delivered",
  "adjAmount": "100.00",
  "adjFlag": "P2RC",
  "adjCode": "105",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantRequestId": "3764723469",
    "payerVpa": "123454306@1234",
    "payeeVpa": "83746598743@2312",
    "transactionAmount": "100.00",
    "reqAdjAmount": "100.00",
    "reqAdjFlag": "PBRB",
    "reqAdjCode": "U008",
    "adjAmount": "100.00",
    "adjFlag": "PR2C",
    "adjCode": "105",
    "crn": "302570532",
    "gatewayComplaintId": "AUT699393106f865d1a9wegrhjw9725e6891f",
    "gatewayResponseCode": "00",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseMessage": "Your complaint is resolved succesfully",
    "gatewayReferenceId": "123456"
    }
,
  "udfParameters": "{}"
}

This Api will be used to Resolve the complaint being raised.

Request parameters

Parameter	Description	Constraints
merchantRequestId	Merchant generated id for the request	35 characters alphanumeric unique id.
originalUpiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
originalTransactionUpiRequestId	Original Transaction Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
remarks	Remarks or reason for complaint	String.
adjAmount optional	Amount of the transaction sent to NPCI	Amount in two decimals. Decimals are mandatory.
adjFlag	Reason flag for complaint sent to NPCI	String.
adjCode	Reason Code for complaint sent to NPCI	String.
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantRequestId	Merchant generated id for the request	35 characters alphanumeric unique id.
payerVpa	VPA of the customer to be used for payment	something@handle
payeeVpa	Vpa of the payee to whom money is being sent	something@handle
transactionAmount	The total amount for which original transaction was performed	String with mandatory two decimals
reqAdjAmount	Amount of the transaction sent by NPCI	Amount in two decimals.
reqAdjFlag	Reason flag for complaint sent by NPCI	String.
reqAdjCode	Reason Code for complaint sent by NPCI	String.
adjAmount	Amount of the transaction sent to NPCI	Amount in two decimals.
adjFlag	Reason flag for complaint sent to NPCI	String.
adjCode	Reason Code for complaint sent to NPCI	String.
crn	Complaint reference number returned by NPCI	14 to 16 characters alphanumeric.
gatewayReferenceId	Reference id returned by the gateway	String
gatewayComplaintId	Complaint id returned by gateway	String
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, PENDING, FAILURE
gatewayResponseMessage	Response message for code returned by gateway	String
udfParameters optional	Udf parameters as passed in the request	JSON string

Complaint Status

# Sample request

curl -L -X POST '{{host}}/api/n2/merchants/complaints/status' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "XYZ123456",
  "originalTransactionUpiRequestId": "AUT699393106f865d1a9467c59725e6891f",
  "type": "TXNDISPUTE",
  "originalUpiRequestId": "AUY699393106f865d1a9wegrhjw9725e6891f",
  "udfParameters" : "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantChannelId": "TESTAPP",
    "gatewayResponseStatus": "CLOSED",
    "merchantId": "TEST",
    "gatewayComplaintId": "TXN699393106f865d1a9467c59725e9812h",
    "adjCode": "103",
    "reqAdjAmount": "1.00",
    "gatewayResponseMessage": "Your complaint is raised succesfully",
    "payerVpa": "abcd@handle",
    "adjFlag": "TCC",
    "merchantRequestId": "699393106f865d1a9467c59725e9812h",
    "gatewayResponseCode": "00",
    "gatewayReferenceId": "215105297664",
    "reqAdjCode": "U010",
    "crn": "UPI75f78b9e71042",
    "customerMobileNumber": "919988776655",
    "payeeVpa": "xyz@handle",
    "reqAdjFlag": "PBRB",
    "transactionAmount": "1.00",
    "merchantCustomerId": "test-merchantcustomer-1",
    "adjAmount": "1.00"
    }
,
  "udfParameters": "{}"
}

This api will be used for checking the status of complaints raised on any transactions.

Note

1. Transaction and Complaints Status check shall be allowed only after '3' mins from the time of respective txn.
2. Per day only 3 check status can be done to the NPCI UDIR system, after that PSP will pick the status from the database and that will be shared.
3. For the below request type = "TXNDISPUTE" will correspond to one of the subTypes of "reqComplaint" api where we specify whether we want the status for txn, dispute or both. Currently we don't serve other use cases. We have kept it as a field in request body for future api enhancements.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
originalUpiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
originalTransactionUpiRequestId	Original Transaction Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
type	Type of Complaint Status	String TXNDISPUTE
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
gatewayResponseStatus	Response status returned by gateway	OPEN,CLOSED, PENDING, FAILURE
merchantId	Unique id for the merchant as passed in request headers	String
gatewayComplaintId	Complaint id returned by gateway	String
reqAdjAmount	Amount of the transaction sent to NPCI when complaint was raised	Amount in two decimals.
gatewayResponseMessage	Response message for code returned by gateway	String
payerVpa	VPA of the customer to be used for payment	something@handle
merchantRequestId	Merchant generated id for the transaction	As passed in the request
gatewayResponseCode	Response code returned by gateway	String
gatewayReferenceId	Reference id returned by the gateway	String
reqAdjCode	Reason Code for complaint sent to NPCI when complaint was raised	String.
crn optional	Complaint reference number returned by NPCI	14 to 16 characters alphanumeric.
customerMobileNumber	Customer mobile number as per device binding	12 digits mobile number string
payeeVpa	Vpa for customer who received the payment	String
reqAdjFlag	Reason flag for complaint sent to NPCI when complaint was raised	String.
transactionAmount	The total amount for which original transaction was performed.	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
udfParameters optional	Udf parameters as passed in the request	JSON String

List All Complaint

# Sample request

curl -L -X POST '{{host}}/api/n2/merchants/complaints/list' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "abcdXycxvsdg28483",
  "startDate": "2012-12-03",
  "limit": 4,
  "offSet": 10,
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "complaintsList": [
      "payerVpa": "123454306@1234",
      "payeeVpa": "83746598743@2312",
      "orgTxnStatus": "PENDING",
      "merchantCustomerId": "test-merchantcustomer-1",
      "mobileNumber": "919988776655",
      "transactionUpiRequestId": "AUT69jnknvjf6f865d1a9wegrhjw9725e6891f",
      "upiRequestId": "AUT699393106f865dua9wegrhjw9725e6891h",
      "crn": "298745003940r3y",
      "orgTxnDate": "2021-08-11T22:50:00+05:30",
      "complaintDate": "2021-08-12T22:50:00+05:30",
      "status": "PENDING",
      "remarks": "Under Process",
      "reqAdjAmount": "0.50",
      "reqAdjFlag": "PBRB",
      "reqAdjCode": "U010"
    ]
    }
,
  "udfParameters": "{}"
}

This Api will be used to get the list of all pending complaints on a particular merchant or merchantCustomer.

Request parameters

Parameter	Description	Constraints
merchantCustomerId optional	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
startDate	Time from which complaint status list is required	Date (2012-12-03) (YYYY-MM-DD)
limit	Maximum number of rows to be returned. Used for pagination	Number > 0
offset	Offset for rows to be returned. Used for pagination	Number >= 0
endDate (O)	Time till which complaint status List is required (can only be available for 6 months period as the txn would be archived after that)	End date <= Current date
Status (O) []	List of all possible values of complaint status. In case the list is empty then return all the complaints within the given time slot	OPEN, CLOSED, PENDING, COMPLAINT RECEIVED, FAILURE.
udfParameters optional	Stringified JSON for udf parameters	JSON String

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
pendingComplaints	Array of pending complaints	Array of JSON
payerVpa	VPA of the customer to be used for payment	something@handle
payeeVpa	Vpa of the payee to whom money is being sent	something@handle
orgTxnStatus	Status of Transaction	SUCCESS, FAILURE
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number as per device binding	12 digits mobile number string
originalUpiRequestId	Unique id of the transaction on which complaint is raised	35 character alphanumeric.
upiRequestId	Unique id of the complaint	35 character alphanumeric.
crn	Complaint reference number returned by NPCI	14 to 16 characters alphanumeric.
orgTxnDate	Transaction timestamp	Timestamp (YYYY-MM-DDTHH:MM:SS+05:30)
complaintDate	Complaint timestamp	Timestamp (YYYY-MM-DDTHH:MM:SS+05:30)
status	Status of the complaint	CLOSED, PENDING, FAILURE, OPEN
remarks	remarks of the complaint	String
reqAdjAmount	Amount of the transaction sent by NPCI	Amount in two decimals.
reqAdjFlag	Reason flag for complaint sent by NPCI	String.
reqAdjCode	Reason Code for complaint sent by NPCI	String.
udfParameters optional	Udf parameters as passed in the request	JSON String

Complaint API Callbacks

Incoming Complaint to Merchant

# A callback with following POST data will be sent to the endpoint configured for "MERCHANT_COMPLAINT_RAISED"

{
  "crn": "302570532",
  "currCycle": "Y",
  "customerMobileNumber": "919988776655",
  "gatewayComplaintId": "AIX699393106f865d1a9467c59725789tgh",
  "gatewayReferenceId": "123456",
  "gatewayResponseCode": "00",
  "gatewayResponseMessage": "Complaint is Raised",
  "gatewayResponseStatus": "PENDING",
  "merchantChannelId": "TESTAPP",
  "merchantId": "TEST",
  "originalGatewayTransactionId": "AIX699393106f865d1a9467c59725789tgh",
  "originalTransactionTimestamp" : "2021-08-12T22:50:00+05:30",
  "orgSettRespCode": "RR",
  "payeeVpa": "83746598743@2312",
  "payerVpa": "123454306@1234",
  "remarks": "Goods not received",
  "reqAdjAmount": "1.00",
  "reqAdjCode": "U010",
  "reqAdjFlag": "PBRB",
  "subMerchantChannelId": "SUBMERCHANTAPP",
  "subMerchantId": "SUBMERCHANT",
  "transactionAmount": "1.00",
  "type": "MERCHANT_COMPLAINT_RAISED"
}

This callback is given when a complaint is raised for a merchant.

Parameter	Description
crn optional	Complaint reference number returned by NPCI.
currCycle optional	Describes transaction belongs to current cycle or not.
customerMobileNumber	Customer mobile number as per device binding.
gatewayComplaintId	Complaint id returned by gateway.
gatewayReferenceId	Reference id returned by the gateway.
gatewayResponseCode	Response code returned by gateway.
gatewayResponseMessage	Response message for code returned by gateway.
gatewayResponseStatus	Response status returned by gateway - ["PENDING"].
merchantChannelId	Unique id for the merchant channel as passed in request headers.
merchantId	Unique id for the merchant as passed in request headers.
originalGatewayTransactionId	Original UPI request id returned by gateway of the transaction
originalTransactionTimestamp	Timestamp of the original transaction
orgSettRespCode optional	OriginalRespCode in the transaction
payeeVpa	Vpa of the payee to whom money is being sent.
payerVpa	VPA of the customer to be used for payment.
remarks optional	remarks on Complaint.
reqAdjAmount	Amount of the transaction sent by NPCI.
reqAdjCode	Reason Code for complaint sent by NPCI.
reqAdjFlag	Reason flag for complaint sent by NPCI.
subMerchantId optional	Unique id for subMerchant. Only if present as a subMerchant.
subMerchantChannelId optional	Unique id for the channel via which request is made. Only if present as a subMerchant.
transactionAmount	The total amount for which original transaction was performed.
type	Event type of the callback - MERCHANT_COMPLAINT_RAISED

Outgoing Complaint Callback

# A callback with following POST data will be sent to the endpoint configured for "CUSTOMER_COMPLAINT_RESOLVED"

{
  "adjAmount": "1.00",
  "adjCode": "102",
  "adjFlag": "TCC",
  "reqAdjAmount": "1.00",
  "reqAdjCode": "U010",
  "reqAdjFlag": "PBRB",
  "crn": "302570532",
  "currCycle": "Y",
  "customerMobileNumber": "919988776655",
  "gatewayComplaintId": "AIX699393106f865d1a9467c59725789tgh",
  "gatewayReferenceId": "123456",
  "gatewayResponseCode": "00",
  "gatewayResponseMessage": "Complaint is Raised",
  "gatewayResponseStatus": "CLOSED",
  "merchantChannelId": "TESTAPP",
  "merchantCustomerId": "test-merchantcustomer-1",
  "merchantId": "TEST",
  "originalGatewayTransactionId": "AIX699393106f865d1a9467c59725789tgh",
  "originalTransactionTimestamp": "2021-08-12T22:50:00+05:30",
  "orgSettRespCode": "RR",
  "payeeVpa": "83746598743@2312",
  "payerVpa": "123454306@1234",
  "remarks" : "Goods not received",
  "transactionAmount": "1.00",
  "type": "CUSTOMER_COMPLAINT_RESOLVED"
}

This callback is given when a customer complaint is resolved.

Parameter	Description
adjAmount optional	Amount of the transaction sent by NPCI.
adjCode optional	Reason Code for complaint sent by NPCI.
adjFlag optional	Reason flag for complaint sent by NPCI.
crn optional	Complaint reference number returned by NPCI.
currCycle optional	Describes transaction belongs to current cycle or not.
customerMobileNumber	Customer mobile number as per device binding.
gatewayComplaintId	Complaint id returned by gateway.
gatewayReferenceId	Reference id returned by the gateway.
gatewayResponseCode	Response code returned by gateway.
gatewayResponseMessage	Response message for code returned by gateway.
gatewayResponseStatus	Response status returned by gateway - ["CLOSED","FAILURE"].
merchantChannelId	Unique id for the merchant channel as passed in request headers.
merchantCustomerId optional	Merchant generated unique profile id for customer as passed in the request.
merchantId	Unique id for the merchant as passed in request headers.
originalGatewayTransactionId	Original UPI request id returned by gateway of the transaction
originalTransactionTimestamp	Timestamp of the original transaction
orgSettRespCode optional	OriginalRespCode in the transaction
payeeVpa optional	Vpa of the payee to whom money is being sent.
payerVpa optional	VPA of the customer to be used for payment.
remarks optional	remarks on Complaint.
transactionAmount	The total amount for which original transaction was performed.
type	Event type of the callback - CUSTOMER_COMPLAINT_RESOLVED

Sub Merchant APIs

Headers

{
  "content-type": "application/json",
  "accept": "application/json",
  "x-merchant-id": "TEST",
  "x-merchant-channel-id": "TESTAPP",
  "x-sub-merchant-id": "SUBMERCHANT",
  "x-sub-merchant-channel-id": "SUBMERCHANTAPP",
  "x-timestamp": "1496918882000",
  "x-merchant-signature": "26b339a48db62a..."
}

All the request must have following headers.

Header Name	Header Value
content-type	application/json
accept	application/json
x-merchant-id	Will be shared while onboarding.
x-merchant-channel-id	Will be shared while onboarding.
x-sub-merchant-id	Provided during on-boarding. To be passed in the apis if it needs to be invoked in sub merchant mode.
x-sub-merchant-channel-id	Provided during on-boarding. To be passed in the apis if it needs to be invoked in sub merchant mode.
x-timestamp	This is an epoch unix timestamp string. For example, 1496918882000. It can be used by us to invalidate older requests.
x-merchant-signature	This is a signature over combination of headers, payload. Refer Signature Calculation section for more details.

Signature Calculation

Input = headers["x-merchant-id"] + headers["x-merchant-channel-id"] +
  headers["x-sub-merchant-id"] + headers["x-sub-merchant-channel-id"] +
    headers["x-timestamp"] + RequestBody in String UTF-8 encoding
Signature rsa = Signature.getInstance("SHA256withRSA");
rsa.initSign(getPrivate(keyFile));
rsa.update(Input.getBytes("utf-8"));
byte[] signature = rsa.sign();
headers["x-merchant-signature"] =  byteArrayToHex(signature);

Where,

String byteArrayToHex(byte[] a) {
  StringBuilder sb = new StringBuilder(a.length * 2);
  for(byte b: a) sb.append(String.format("%02x", b));
  return sb.toString();
}

Following snippet shows the way to create a signature over the headers and payload of the request.

Note

1. The order of the parameters while creation of a string for signature should be adhered as above.
2. PSS padding is to be used for signature calculation.

Sub Merchant Refund 360

curl -L -X POST '{{host}}/api/n2/merchants/transactions/refund360'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-sub-merchant-id': 'SUBMERCHANT', \
  'x-sub-merchant-channel-id': 'SUBMERCHANTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "originalUpiRequestId": "AUTcb313014204649ad8818933d8623abd7",
  "originalTransactionTimestamp": "2019-06-07T17:57:49+05:30",
  "refundRequestId": "refund4543843",
  "refundAmount": "19.00",
  "refundType": "ONLINE",
  "merchantRefundVpa": "abcd@xyz",
  "remarks": "OrderCancel",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "refundRequestId": "refund4543843",
    "transactionAmount": "200.00",
    "refundAmount": "19.00",
    "refundType": "ONLINE",
    "refundTimestamp": "2019-06-09T17:57:49+05:30",
    "riskScore": "00979",
    "gatewayTransactionId": "AUTcb313014204649ad8818933d8623abd7",
    "gatewayRefundReferenceId": "809323430413",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Your refund is successful"
  },
  "udfParameters": "{}"
}

This api can be used to trigger a refund against a successful sub-merchant transaction.

Note: This is an idempotent api.

Request parameters

Parameter	Description	Constraints
originalUpiRequestId	UPI request id for the original transaction against which refund is being initiated	35 character alphanumeric
originalTransactionTimestamp optional	Timestamp of the original transaction	As returned in the response of original transaction api, String (YYYY-MM-DDTHH:MM:SS+05:30)
refundRequestId	Merchant generated unique id for the refund	35 characters alphanumeric
refundAmount	The amount to be refunded	String with mandatory two decimals
refundType	Type of refund being initiated	OFFLINE, ONLINE
merchantRefundVpa optional	Merchant refund vpa that is to be used for online refund	mandatory for refundType = ONLINE, vpa@handle,
remarks	Remarks or reason for the refund	String
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant	As passed in request headers
merchantChannelId	Unique id for the merchant channel	As passed in request headers
refundRequestId	Merchant generated unique id for the refund	As passed in the request body
transactionAmount	The total amount for which original transaction was performed	String with mandatory two decimals
refundAmount	The amount to be refunded	As passed in the request body
refundType	Type of refund being initiated	As passed in the request body
refundTimestamp	Timestamp of when refund request was initiated	String (YYYY-MM-DDTHH:MM:SS+05:30)
riskScore optional	RiskScore shared by NPCI or Bank	String
gatewayTransactionId	UPI request id returned by gateway for the transaction	Same as originalUpiRequestId passed in request
gatewayRefundReferenceId	Reference id returned by the gateway for the refund	String
gatewayResponseStatus	Response status returned by gateway for the refund	String (SUCCESS, PENDING, DEEMED, FAILURE)
gatewayResponseCode	Response code returned by gateway for the refund	String
gatewayResponseMessage	Response message for code returned by gateway for the refund	String
udfParameters optional	Udf parameters	As passed in the request body

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Refund accepted successfully
01	PENDING	Refund is in pending state
91	PENDING	Refund is in pending state
09	PENDING	Refund is in pending state
060	PENDING	Refund is in pending state
070	PENDING	Refund is in pending state
080	PENDING	Refund is in pending state
RB	DEEMED	Refund is in deemed state
96	DEEMED	Refund is in deemed state
Else	FAILURE	Refund failed

P2P to P2M migration

curl -L -X POST '{{host}}/api/n2/merchants/sub/p2mMigration' \
-H 'Content-Type: application/json' \
   'x-merchant-id: TEST' \
   'x-merchant-channel-id: TESTAPP' \
   'x-timestamp: 1608126224000' \
   'x-merchant-signature: dummy' \
--data-raw '{
    "subMerchantId":"SUBMERCHANT",
    "subMerchantChannelId":"SUBMERCHANTAPP",
    "vpa":"p2ptop2mtest@axisuat1",
    "mcc":"7113",
    "callbackUrls": "[{\"url\":\"https://beta-upi.juspay.in/callback\",\"type\":\"MERCHANT_CREDITED_VIA_COLLECT\"}]",
    "merchantName":"merchant_name",
    "marketingName":"marketing_name",
    "city":"city",
    "address":"xxxxxxx",
    "state":"state",
    "pinCode":"560034",
    "ownerName":"ownerName",
    "partner1":"partnerOne",
    "partner2":"partnerTwo",
    "mccDescription":"mccDescription",
    "mid":"mid",
    "tid":"tid",
    "sid":"sid",
    "merchantType":"LARGE",
    "merchantGenre":"ONLINE",
    "onBoardingType":"AGGREGATOR",
    "brand":"JUSPAY_brand",
    "legal":"JUSPAY_legal",
    "franchise":"JUSPAY_franchise",
    "type":"PRIVATE",
    "replacementVpa": "p2ptop2mtest2@axisuat1"
}'

# Response: HTTP 200 OK
{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload": {
        "merchantChannelId": "APLTEST",
        "vpa": "p2ptop2mtest@axisuat1",
        "maskedAccountNumber": "XXXXXXX8260",
        "merchantId": "APLTEST",
        "enabled": "true",
        "subMerchantChannelId": "APLSUBMERCHANT01",
        "subMerchantId": "APLSUBMERCHANT01",
        "ifsc": "AXIS0000447",
        "mcc": "7113",
        "callbackUrls": "[{\"url\":\"https://beta-upi.juspay.in/callback\",\"type\":\"MERCHANT_CREDITED_VIA_COLLECT\"}]"
    }
}

This API is used to migrate amazon’s p2p customers to submerchants.

Note: \ You can add --header 'x-api-version: 1' to get idempotent response. Instead of sending DUPLICATE_REQUEST error we share the existing subMerchant details with extra parameter action. It is backward compatible.\ action values :\   FETCHED -> Fetched the existing already created subMerchant\   ADDED -> Created a new subMerchant

Request parameters

Parameter	Description	Constraints
subMerchantId	Merchant generated sub-merchant id value	Alphanumeric string. Maximum length is 256.
subMerchantChannelId	Sub-merchant channel id	Alphanumeric string. Maximum length is 256.
vpa	Vpa which is linked to QR	Special characters allowed(.-@).Maximum length is 25.
accountNumber optional	Account number for the sub-merchant	Numeric string. Maximum length is 30.
ifsc optional	Ifsc code of the sub-merchant bank account	Alphanumeric string. Maximum length is 11.
mcc	Mcc code of the sub-merchant	Numeric String (4).
callbackUrls optional	Callback Urls are configured for each event	Stringified Array of JSON objects.
merchantName	Name of sub-merchant	Alphanumeric string with. Maximum length is 100.
marketingName	Market name of the sub-merchant	Alphanumeric string. Maximum length is 50.
city	City of sub-merchant	Alphanumeric string. Maximum length is 50.
address	Address of sub-merchant	Alphanumeric string. Maximum length is 200.
state	State of sub-merchant	Alphanumeric string . Maximum length is 50.
pincode	Pincode of sub-merchant	Numeric String (6).
owner	Owner of sub-merchant firm	Alphanumeric string. Maximum length is 50.
partner1	Partner name of sub-merchant firm	Alphanumeric string. Maximum length is 50.
partner2	Partner name of sub-merchant firm	Alphanumeric string. Maximum length is 50.
mccDescription	Description of mcc	Alphanumeric string. Maximum length is 256.
gstin optional	GSTIN	Alphanumeric string. Maximum length is 20.
panNumber optional	PAN Number of sub-merchant	Alphanumeric string. Maximum length is 10.
mid	Merchant identifier for sub-merchant	Alphanumeric string. Maximum length is 20.
tid	Terminal identifier for sub-merchant	Alphanumeric string. Maximum length is 20.
sid	Store id for sub-merchant	Alphanumeric string. Maximum length is 20.
merchantType	Merchant type for sub-merchant	SMALL,LARGE.
merchantGenre	Genre of sub-merchant	ONLINE, OFFLINE.
onBoardingType	Onboarding type of sub-merchant	BANK, AGGREGATOR
brand	Brand name of sub-merchant	Alphanumeric string. Maximum length is 99.
legal	Legal name for sub-merchant	Alphanumeric string. Maximum length is 99.
franchise	franchise name for sub-merchant	Alphanumeric string. Maximum length is 99.
type	Ownership type of sub-merchant	PROPRIETARY,PARTNERSHIP,PRIVATE,PUBLIC,OTHERS.
enabled optional	Denotes if the sub-merchant is enabled or not	true, false
isB2BMerchant optional	Denotes if sub-merchant can accept payment as a B2B merchant.	true, false.
replacementVpa optional	Vpa that becomes primary vpa after the primary vpa is migrated.	Special characters allowed(.-@).Maximum length is 25.

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for parent merchant	As passed in request.
merchantChannelId	Unique id for the channel of the parent merchant	As passed in request.
subMerchantId	Merchant generated sub-merchant id value	Merchant generated sub-merchant id value
subMerchantChannelId	Sub-merchant channel id	As passed in request.
vpa	Vpa for sub-merchant	As passed in request.
maskedAccountNumber	Masked account number for the sub-merchant	XXXX123456
ifsc	Ifsc code of the sub-merchant bank account	As passed in request.
mcc	Mcc code of the sub-merchant	As passed in request.
enabled	Tells whether the sub-merchant is enabled or not	As passed in request, true if not passed.
callbackUrls	Callback Urls configured for each event	As passed in request.
action conditional	Tells whether the sub-merchant added newly or fetched if already exists when x-api-version > 0	FETCHED, ADDED

Add Sub Merchant

curl -L -X POST '{{host}}/api/n2/merchants/sub/add' \
-H 'Content-Type: application/json'
  "x-merchant-id: MERCHANT"
  "x-merchant-signature: 26b339a48db62a5b3e779a8e95e6c39d81942fe45.."
  "x-timestamp: 1507792764"
  "x-merchant-channel-id: MERCHANTAPP"
--data-raw '{
  "subMerchantId": "SUBMERCHANT",
  "subMerchantChannelId": "SUBMERCHANTAPP",
  "vpa": "vpa@apl",
  "accountNumber": "987654321345",
  "ifsc": "AXIS08764173",
  "mcc": "0010",
  "callbackUrls": "[{\"type\": \"Event1\",\"url\": \"www.merchant.com/api/callback\"},..]",
  "merchantName": "ABC",
  "marketingName": "abc",
  "city": "Banglore",
  "address" : "#11, 1st cross road, Banglore",
  "state": "Karnataka",
  "pinCode": "1234",
  "mobileNumber": "911234567890",
  "ownerName": "abc",
  "partner1": "abc",
  "partner2": "xyz",
  "mccDescription": "Transaport",
  "gstin": "1234",
  "panNumber": "AB1234",
  "mid": "ABC123",
  "sid": "A123",
  "tid": "AB1234",
  "merchantType": "SMALL",
  "merchantGenre": "ONLINE",
  "onBoardingType": "AGGREGATOR",
  "brand": "abc",
  "legal": "abc",
  "franchise": "abc",
  "type": "PRIVATE",
  "isB2BMerchant": "TRUE",
  "enabled": "TRUE",
  "configurations": [
    {
      "config": "BLOCK_DIRECT_PAY",
      "value": "true"
    },
    {
    "config": "PAYER_ACC_TYPES_ALLOWED",
    "value": [{"accType":"SAVINGS"},{"accType":"CURRENT"},{"accType":"CREDIT","limitType":"SMALL"}]
    }
    ]
  "udfParameters": "{}",
  "iat": "1548782109000"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload":
    {
      "merchantId" : "MERCHANT",
      "merchantChannelId" : "MERCHANTAPP",
      "subMerchantId": "SUBMERCHANT",
      "subMerchantChannelId": "SUBMERCHANTAPP",
      "vpa": " vpa@apl",
      "maskedAccountNumber": "XXXX21345",
      "ifsc": "AXIS08764173",
      "mcc": "0010",
      "enabled": "false",
      "callbackUrls": "[{'type': 'Event1','url': 'www.merchant.com/api/callback'},..]",
      "udfParameters":"{}"
    }
}

# Response: Error
{
  "status": "FAILURE",
  "responseCode": "INTERNAL_SERVER_ERROR",
  "responseMessage": "INTERNAL_SERVER_ERROR",
}

# Idempotent Request
curl --location --request POST 'localhost:8012/api/n2/merchants/sub/add' \
--header 'x-merchant-id: AMAZON' \
--header 'x-merchant-checksum: bypass' \
--header 'x-merchant-channel-id: AMAZONAPP' \
--header 'x-timestamp: 1706088501' \
--header 'Content-Type: application/json' \
--header 'x-merchant-checksum: bypass' \
--header 'x-api-version: 1' \
--data-raw '{
    "subMerchantId": "c340721a3",
    "subMerchantChannelId": "submerchant243",
    "vpa": "submerchant243@axisuat1",
    "accountNumber": "12345243",
    "ifsc": "HDFC0001311",
    "mcc": "1234",
    "merchantName": "submerchant243",
    "marketingName": "marketingname243",
    "city": "city243",
    "address": "address243",
    "state": "state243",
    "pinCode": "147001",
    "mobileNumber": "911600000001",
    "ownerName": "ownername243",
    "partner1": "partner243",
    "partner2": "partner243",
    "mccDescription": "mcdescription243",
    "gstin": "gstin243",
    "panNumber": "BQDPT0000R",
    "mid": "YES123",
    "sid": "YES123",
    "tid": "YES123",
    "merchantType": "SMALL",
    "merchantGenre": "ONLINE",
    "onBoardingType": "BANK",
    "brand": "Yesbank",
    "legal": "Yesbank",
    "franchise": "Yesbank",
    "type": "OTHERS",
    "enabled": "true",
    "callbackUrls": "[{\"type\": \"Event1\",\"url\": \"www.merchant.com/api/callback\"},..]"
}'

# Idempotent Response

{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload":
      {
        "merchantChannelId": "AMAZONAPP",
        "vpa": "submerchant243@axisuat1",
        "maskedAccountNumber": "XXXXXXX1465",
        "merchantId": "AMAZON",
        "enabled": "true",
        "subMerchantChannelId": "submerchant243",
        "subMerchantId": "c340721a3",
        "action": "FETCHED",
        "ifsc": "AXIS0000447",
        "mcc": "9999",
        "callbackUrls": "[{\"type\": \"Event1\",\"url\": \"www.merchant.com/api/callback\"},..]"
      }
}

This api creates a new sub-merchant with the given account number and vpa.

Request parameters

Parameter	Description	Constraints
subMerchantId	Merchant generated sub-merchant id value	Alphanumeric string. Maximum length is 256.
subMerchantChannelId	Sub-merchant channel id	Alphanumeric string. Maximum length is 256.
vpa	VPA for the sub-merchant	Special characters allowed(.-@).Maximum length is 25.
accountNumber optional	Current account number for the sub-merchant	Numeric string. Maximum length is 30. Account number and ifsc both fields should be passed. If not passed, parent aggregator's value will be replicated.
ifsc optional	Ifsc code of the sub-merchant current bank account	Alphanumeric string. Maximum length is 11.If not passed, parent aggregator's value will be replicated.
mcc	Mcc code of the sub-merchant	Numeric String (4).
callbackUrls optional	Callback Urls needs to be configured for each event	Stringified Array of JSON objects. Each Json object has type and url params. Refer Server Callbacks section for allowed value of type. If not passed, parent aggregator's values will be replicated.
merchantName	Name of sub-merchant	Alphanumeric string. Maximum length is 100.
marketingName	Market name of the sub-merchant	Alphanumeric string. Maximum length is 50.
city	City of sub-merchant	Alphanumeric string. Maximum length is 50.
address	Address of sub-merchant	Alphanumeric string. Maximum length is 200.
state	State of sub-merchant	Alphanumeric string. Maximum length is 50.
pinCode	Pincode of sub-merchant	Numeric String (6).
mobileNumber	Mobile number of sub-merchant	Numeric String (12).
ownerName	Owner of sub-merchant firm	Alphanumeric string. Maximum length is 50.
partner1	Partner name of sub-merchant firm	Alphanumeric string. Maximum length is 50.
partner2	Partner name of sub-merchant firm	Alphanumeric string. Maximum length is 50.
mccDescription	Description of mcc	Alphanumeric string. Maximum length is 255.
gstin optional	GSTIN	Alphanumeric string.Maximum length is 20.
panNumber optional	PAN Number of sub-merchant	Alphanumeric string (10).
mid	Merchant identifier for sub-merchant	Alphanumeric string. Maximum length is 20.
sid	Store id for sub-merchant	Alphanumeric string. Maximum length is 20.
tid	Terminal identifier for sub-merchant	Alphanumeric string. Maximum length is 20.
merchantType	Merchant type for sub-merchant	SMALL,LARGE.
merchantGenre	Genre of the sub-merchant	ONLINE, OFFLINE.
onBoardingType	Onboarding type of sub-merchant	BANK, AGGREGATOR
brand	Brand name of sub-merchant	Alphanumeric string. Maximum length is 99.
legal	Legal name for sub-merchant	Alphanumeric string. Maximum length is 99.
franchise	Franchise name of merchant	Alphanumeric string. Maximum length is 99.
type	Ownership type of sub-merchant	PROPRIETARY,PARTNERSHIP,PRIVATE,PUBLIC,OTHERS.
enabled optional	Denotes if the sub-merchant is enabled or not	true, false.
configurations optional	Array of JSON objects to provide custom configurations for every submerchant. Each Json object has name and value params	Only valid flags are allowed. The value associated with the CONFIG_NAME can be text, list or any other value as predefined in the code.
udfParameters optional	Udf parameters	As passed in the request body
iat optional	timestamp to be used in JWS	As passed in the request body

Response parameters

Parameter	Description	Values
status	Status of the API.	SUCCESS, FAILURE.
responseCode	SUCCESS if call succeeded. Otherwise shows the error code.	Refer error code section.
responseMessage	SUCCESS if call succeeded. Otherwise shows verbose error.	Refer error code section.
merchantId	Unique id for merchant.	As passed in request.
merchantChannelId	Unique id for the channel via which request is made.	As passed in request.
subMerchantId	Merchant generated sub-merchant id value	As passed in request.
subMerchantChannelId	Sub-merchant channel id	As passed in request.
vpa	VPA for the sub-merchant	As passed in request.
maskedAccountNumber	Masked account number for the sub-merchant	XXXX123456.
ifsc	Ifsc code of the sub-merchant current bank account	As passed in request.
mcc	Mcc code of the sub-merchant	As passed in request.
enabled	Tells whether the sub-merchant is enabled or not	By default it is false. Initiate Update sub-merchant to enable it.
callbackUrls	Callback Urls needs to be configured for each event	As passed in request.
udfParameters	Stringified json for udf parameters.	String

Response Error

For parameter specific errors, responseCode will be BAD_REQUEST and response message will be Invalid parameter_name.

Error Code	Meaning
INVALID_VPA	The vpa passed in request already exists.
BAD_REQUEST	The request parameters are not proper.
INTERNAL_SERVER_ERROR	Internal Server Error.
DUPLICATE_REQUEST	Duplicate request.
MERCHANT_ALREADY_EXISTS	Merchant already exists.

Configuration Table

Config_Name	Description	Values
BLOCK_DIRECT_PAY	true for Online Submerchants and false for Offline Submerchants	true or false
PAYER_ACC_TYPES_ALLOWED	list of payment methods	possible values for key accType : SAVINGS, CURRENT, DEFAULT, NRE, NRO ,CREDIT ,UOD ,SOD ,CREDITLINE01 ,CREDITLINE02 ,CREDITLINE03, CREDITLINE04, CREDITLINE05, CREDITLINE06 ,CREDITLINE07 ,CREDITLINE08, CREDITLINE09 CREDITLINE10, CL01 ,CL011 ,CL012, CL013, CL014, CL015 ,CL02 ,CL03, CL04 ,CL05 ,CL06 ,CL07 ,CL08, CL09, CL10 possible values for key limitType : SMALL

Update Sub Merchant

curl -L -X POST '{{host}}/api/n2/merchants/sub/update' \
 -H "Content-Type: application/json"
    "x-merchant-id: MERCHANT"
    "x-merchant-signature: 26b339a48db62a5b3e779a8e95e6c39d81942fe45.."
    "x-timestamp: 1507792764"
    "x-merchant-channel-id: MERCHANTAPP"
--data-raw '{
  "subMerchantId": "SUBMERCHANT",
  "subMerchantChannelId": "SUBMERCHANTAPP",
  "mcc": "0010",
  "enabled": "true",
  "callbackUrls": "[{\"type\": \"Event1\",\"url\": \"www.merchant.com/api/callback\"},..]",
  "merchantName": "ABC",
  "marketingName": "abc",
  "city": "Banglore",
  "address" : "#11, 1st cross road, Banglore",
  "state": "Karnataka",
  "pinCode": "1234",
  "mobileNumber": "911234567890",
  "ownerName": "abc",
  "partner1": "abc",
  "partner2": "xyz",
  "mccDescription": "Transport",
  "gstin": "1234",
  "panNumber": "AB1234",
  "mid": "ABC123",
  "sid": "A123",
  "tid": "AB1234",
  "merchantType": "SMALL",
  "merchantGenre": "ONLINE",
  "onBoardingType": "AGGREGATOR",
  "brand": "abc",
  "legal": "abc",
  "franchise": "abc",
  "type": "PRIVATE",
  "configurations": [
    {
      "config": "BLOCK_DIRECT_PAY",
      "value": "true"
    },
    {
    "config": "PAYER_ACC_TYPES_ALLOWED",
    "action": "ADD",
    "value": [{"accType":"SAVINGS"},{"accType":"CURRENT"},{"accType":"CREDIT","limitType":"SMALL"}]
    }
  ]
  "udfParameters": "{}",
  "iat": "1548782109000"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload":
    {
      "merchantId" : "MERCHANT",
      "merchantChannelId" : "MERCHANTAPP",
      "subMerchantId": "SUBMERCHANT",
      "subMerchantChannelId": "SUBMERCHANTAPP",
      "vpa": " vpa@apl",
      "maskedAccountNumber": "XXXX123456",
      "ifsc": "AXIS08764173",
      "mcc": "0010",
      "enabled": "true",
      "callbackUrls": "[{\"type\": \"Event1\",\"url\": \"www.merchant.com/api/callback\"},..]",
      "udfParameters":"{}"
    }
}

# Response: Error
{
  "status": "FAILURE",
  "responseCode": "INTERNAL_SERVER_ERROR",
  "responseMessage": "INTERNAL_SERVER_ERROR",
}

This api updates a sub merchant with the given subMerchantId and subMerchantChannelId. Atleast one optional field has to be passed along with 2 mandatory fields.

Request parameters

Parameter	Description	Constraints
subMerchantId	Merchant generated sub-merchant id value	Alphanumeric string. Maximum length is 256.
subMerchantChannelId	Sub-merchant channel id	Alphanumeric string. Maximum length is 256.
mcc optional	Mcc code of the sub-merchant	Numeric String.(4)
enabled optional	Tells whether the sub-merchant is enabled or not	True/False
callbackUrls optional	Callback Urls needs to be configured for each event	Stringified Array of JSON objects. Each Json object has type and url params. Refer Server Callbacks section for allowed value of type.
merchantName optional	Name of sub-merchant	Alphanumeric string. Maximum length is 100.
marketingName optional	Market name of the sub-merchant	Alphanumeric string. Maximum length is 50.
city optional	City of sub-merchant	Alphanumeric string. Maximum length is 50.
address optional	Address of sub-merchant	Alphanumeric string. Maximum length is 200.
state optional	State of sub-merchant	Alphanumeric string. Maximum length is 50.
pinCode optional	Pincode of sub-merchant	Numeric String.(6)
mobileNumber optional	Mobile number of sub-merchant	Numeric String.(12)
ownerName optional	Owner of sub-merchant firm	Alphanumeric string. Maximum length is 50.
partner1 optional	Partner name of sub-merchant firm	Alphanumeric string. Maximum length is 50.
partner2 optional	Partner name of sub-merchant firm	Alphanumeric string. Maximum length is 50.
mccDescription optional	Description of mcc	Alphanumeric string.
gstin optional	GSTIN	Alphanumeric string.
panNumber optional	PAN Number of sub-merchant	Alphanumeric string.(10)
mid optional	Merchant identifier for sub-merchant	Alphanumeric string. Maximum length is 20.
sid optional	Store id for sub-merchant	Alphanumeric string. Maximum length is 20.
tid optional	Terminal identifier for sub-merchant	Alphanumeric string. Maximum length is 20.
merchantType optional	Merchant type for sub-merchant	SMALL,LARGE.
merchantGenre optional	Genre of sub-merchant	ONLINE, OFFLINE.
onBoardingType optional	Onboarding type of sub-merchant	BANK, AGGREGATOR
brand optional	Brand name of sub-merchant	Alphanumeric string. Maximum length is 99.
legal optional	Legal name for sub-merchant	Alphanumeric string. Maximum length is 99.
franchise optional	Franchise name of merchant	Alphanumeric string. Maximum length is 99.
type optional	Ownership type of sub-merchant	PROPRIETARY,PARTNERSHIP,PRIVATE,PUBLIC,OTHERS.
configurations optional	Array of JSON objects to provide custom configurations for every submerchant. Each Json object has name and value params	Only valid flags are allowed. The value associated with the CONFIG_NAME can be text, list or any other value as predefined in the code.Action can have only two possible values - ADD or REMOVE.Refer below table for possible values for config.
udfParameters optional	Udf parameters	As passed in the request body
iat optional	timestamp to be used in JWS	As passed in the request body

Response parameters

Parameter	Description	Values
status	Status of the API.	SUCCESS, FAILURE.
responseCode	SUCCESS if call succeeded. Otherwise shows the error code.	Refer error code section.
responseMessage	SUCCESS if call succeeded. Otherwise shows verbose error.	Refer error code section.
merchantId	Unique id for merchant.	As passed in request.
merchantChannelId	Unique id for the channel via which request is made.	As passed in request.
subMerchantId	Merchant generated sub-merchant id value	As passed in request.
subMerchantChannelId	Sub-merchant channel id	As passed in request.
vpa	VPA for the sub-merchant	As passed in request.
maskedAccountNumber	Masked account number for the sub-merchant	XXXX123456.
ifsc	Ifsc code of the sub-merchant current bank account	As passed in request.
mcc	Mcc code of the sub-merchant	As passed in request.
enabled	Tells whether the sub-merchant is enabled or not	By default it is false. Initiate update sub-merchant to enable it.
callbackUrls	Callback Urls needs to be configured for each event	As passed in request.
udfParameters	Stringified json for udf parameters.	String

Response Error

For parameter specific errors, responseCode will be BAD_REQUEST and response message will be Invalid parameter_name.

Error Code	Meaning
BAD_REQUEST	The request parameters are not proper.
INTERNAL_SERVER_ERROR	Internal Server Error.

Configuration Table

Config_Name	Description	Values
BLOCK_DIRECT_PAY	true for Online Submerchants and false for Offline Submerchants	true or false
PAYER_ACC_TYPES_ALLOWED	list of payment methods to add or remove	possible values for key accType : SAVINGS, CURRENT, DEFAULT, NRE, NRO ,CREDIT ,UOD ,SOD ,CREDITLINE01 ,CREDITLINE02 ,CREDITLINE03, CREDITLINE04, CREDITLINE05, CREDITLINE06 ,CREDITLINE07 ,CREDITLINE08, CREDITLINE09 CREDITLINE10, CL01 ,CL011 ,CL012, CL013, CL014, CL015 ,CL02 ,CL03, CL04 ,CL05 ,CL06 ,CL07 ,CL08, CL09, CL10 possible values for key limitType : SMALL

List All Sub Merchants

curl -L -X POST '{{host}}/api/n2/merchants/sub/list' \
-H "Content-Type: application/json"
   "x-merchant-id: MERCHANT"
   "x-merchant-signature: 26b339a48db62a5b3e779a8e95e6c39d81942fe45.."
   "x-timestamp: 1507792764"
   "x-merchant-channel-id: MERCHANTAPP"
--data-raw '{
    "offset":0,
    "limit":10,
  "enabled": "true",
  "iat": "1548782109000"
 }'

# The above command returns JSON structured like this:

# Response: HTTP 200 OK
{
    "status": "SUCCESS",
    "responseCode": "SUCCESS",
    "responseMessage": "SUCCESS",
    "payload": {
        "subMerchants": [
            {
                "subMerchantId": "SUBMERCHANT",
                "subMerchantChannelId": "SUBMERCHANTAPP"
            },...
        ],
        "subMerchantsCount": 1
    }
}

# Response: Error
{
  "status": "FAILURE",
  "responseCode": "INTERNAL_SERVER_ERROR",
  "responseMessage": "INTERNAL_SERVER_ERROR",
}

This api lists all sub-merchants for the requested merchant.

Request parameters

Parameter	Description	Constraints
offset	Offset value to be considered while listing	Numeric.
limit	Number of sub-merchants to be returned	Numeric.
enabled optional	Denotes if the sub-merchant is enabled or not	true, false
iat optional	timestamp to be used in JWS	As passed in the request body

Response parameters

Parameter	Description	Values
status	Status of the API.	SUCCESS, FAILURE.
responseCode	SUCCESS if call succeeded. Otherwise shows the error code.	Refer error code section.
responseMessage	SUCCESS if call succeeded. Otherwise shows verbose error.	Refer error code section.
merchantId	Unique id for merchant.	As passed in request.
merchantChannelId	Unique id for the channel via which request is made.	As passed in request.
subMerchants	Array of sub-merchant Information	See sample response.
subMerchantId	merchantId of the sub-merchant	As passed while creation.
subMerchantChannelId	channelId for the sub-merchant	As passed while creation.
subMerchantsCount	Total number of sub-merchants configured for the aggregator	Numeric.

Response Error

Error Code	Meaning
BAD_REQUEST	The request parameters are not proper.
INTERNAL_SERVER_ERROR	Internal Server Error.

List Specific Sub Merchant Info

curl -L -X POST '{{host}}/api/n2/merchants/sub/info' \
-H "Content-Type: application/json"
   "x-merchant-id: MERCHANT"
   "x-merchant-signature: 26b339a48db62a5b3e779a8e95e6c39d81942fe45.."
   "x-timestamp: 1507792764"
   "x-merchant-channel-id: MERCHANTAPP"
--data-raw '{
    "subMerchantId":"SUBMERCHANT",
    "subMerchantChannelId": "SUBMERCHANTAPP",
  "udfParameters": "{}",
  "iat": "1548782109000"
 }'

# Response : HTTP 200 OK
{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload": {
        "merchantChannelId": "CHANNELID",
        "vpa": "vpa@handle",
        "maskedAccountNumber": "XXXXXXX3303",
        "merchantId": "MERCHANTID",
        "enabled": "true",
        "subMerchantChannelId": "SUBMERCHANTAPP",
        "subMerchantId": "SUBMERCHANT",
        "configurations": [
            {
                "config": "BLOCK_DIRECT_PAY",
                "value": "false"
            },
            {
                "config": "PAYER_ACC_TYPES_ALLOWED",
                "value": [
                    {
                        "accType": "CREDIT"
                    },
                    {
                        "accType": "CURRENT"
                    }
                ]
            }
        ],
        "ifsc": "AXIS76413",
        "mcc": "0010",
        "callbackUrls": "[{\"url\":\"www.merchant.com/api/callback\",\"type\":\"MERCHANT_CREDITED_VIA_PAY\"}]"
    },
    "udfParameters": "{}"
}

# Response : Error
{
  "status": "FAILURE",
  "responseCode": "INTERNAL_SERVER_ERROR",
  "responseMessage": "INTERNAL_SERVER_ERROR",
}

This api gives the information of the requested submerchant.

Note:

1. Use --header x-api-version: 2 to get configurations in response.

Request parameters

Parameter	Description	Constraints
subMerchantId	Merchant generated sub-merchant id value	Alphanumeric string. Maximum length is 256.
subMerchantChannelId	Sub-merchant channel id	Alphanumeric string. Maximum length is 256.
udfParameters optional	Udf parameters	As passed in the request body
iat optional	timestamp to be used in JWS	As passed in the request body

Response parameters

Parameter	Description	Values
status	Status of the API.	SUCCESS, FAILURE.
responseCode	SUCCESS if call succeeded. Otherwise shows the error code.	Refer error code section.
responseMessage	SUCCESS if call succeeded. Otherwise shows verbose error.	Refer error code section.
merchantId	Unique id for merchant.	As passed in request.
merchantChannelId	Unique id for the channel via which request is made.	As passed in request.
subMerchantId	merchantId of the sub-merchant	As passed while creation.
subMerchantChannelId	channelId for the sub-merchant	As passed while creation.
vpa	VPA for the sub-merchant	As passed while creation.
maskedAccountNumber	Masked account number for the sub-merchant	As passed while creation.
ifsc	ifsc code of the sub-merchant current bank account	As passed while creation.
mcc	mcc code of the sub-merchant	As passed while creation.
enabled	Tells whether the sub-merchant is enabled or not	By default it is false. Initiate Update Sub-merchant to enable it.
callbackUrls	Callback Urls that are configured for each event	As passed while creation.
udfParameters	Stringified json for udf parameters.	String

Response Error

Error Code	Meaning
BAD_REQUEST	The request parameters are not proper.
INTERNAL_SERVER_ERROR	Internal Server Error.

Upi Mapper Merchant APIs

Check Upi Number Availability

# Sample request

curl -X POST
-H "Content-Type: application/json"
-H 'x-merchant-channel-id: APLTEST'
-H 'x-merchant-signature: 823647862547652376452378456'
-H 'x-merchant-id: APLTEST'
-H 'x-timestamp: 1496918882000'
-d '{
  "merchantCustomerId": "DEMO-CUST-1234",
  "upiRequestId": "APLVGXVGDV21r521r53MAPPERdbhsbcs22",
  "upiNumber": "755027711",
  "vpa": "abcd@xyz",
  "action": "CHECK",
  "deviceFingerPrint": "4e11ca23af4aa457dc1151699762b371e07cb0b685f87eeadba14bc39229ee6c",
  "fallbackDeviceFingerPrint": "",
  "udfParameters": "{}"
}' "{{host}}/api/n2/merchants/upiNumber/availability"

# The above command returns JSON structured like this:

{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload": {
        "merchantChannelId": "APLTEST",
        "status": "NEW",
        "existingVpa": "abcd@xyz",
        "gatewayResponseStatus": "SUCCESS",
        "merchantId": "APLTEST",
        "gatewayResponseMessage": "Your CHECK call was successful",
        "gatewayResponseCode": "00",
        "gatewayTransactionId": "APLVGXVGDV21r521r53MAPPERdbhsbcs22",
        "customerMobileNumber": "917550277516",
        "upiNumber": "755027711",
        "merchantCustomerId": "DEMO-CUST-1234",
        "gatewayTimestamp": "2021-11-08T14:12:09+05:30"
    },
    "udfParameters": "{}"
}

This endpoint will be used to check if a UPI Number is available and also to check the current status of a UPI number. In case of mobile UPI number it will also let us know if we can port the UPI number with the action as PORT.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
upiRequestId	Unique id sent to UPI switch	35 character alphanumeric that starts with a unique merchant prefix
upiNumber	Number mapped to a customer's VPA that is unique to the customer across the UPI ecosystem	8 to 10 digit numeric string. 10 digit number must be the mobile number. Last 3 digits must not be same. Must not start with a 0.
vpa	Vpa linked/to be linked with the provided Upi Number	vpa@handle
action	Action to be performed on UPI Number	CHECK or PORT
deviceFingerPrint	Device fingerprint of the customer	String
fallbackDeviceFingerPrint optional	Fallback Device fingerprint of the customer	String
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	Status of the API.	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantId	Unique id for the merchant as passed in request headers	String
customerMobileNumber	Mobile number of the customer.	12 character string
gatewayTimestamp	Gateway timestamp for the Api call.	String(YYYY-MM-DDTHH:MM:SS+05:30)
gatewayTransactionId	Transaction id returned by gateway. Same as upiRequestId passed in request	String
gatewayResponseStatus	Response status returned by gateway.	String(SUCCESS, FAILURE)
gatewayResponseCode	Response code returned by gateway. Refer the table below for all possible values.	String
gatewayResponseMessage	Response message for code returned by gateway.	String
status	Status of the Upi Number.	String(ACTIVE, DISABLED, DELETED, NEW)
upiNumber	Number mapped to a customer's VPA that is unique to the customer across the UPI ecosystem	As passed in request
existingVpa	Vpa linked(/to be linked) with the upiNumber	vpa@handle
udfParameters	Stringified json for udf parameters.	String

responseCode	responseMessage
JP40	Check request not found for the Upi Number
JP41	User's Vpa doesnot match with the CHECK call
JPMM17	Upi Number mapping already exists

gatewayResponseCode	gatewayResponseStatus	Description
MM18	FAILURE	UPI number mapping already exists / UPI Number is mapped to different VPA
MM17	FAILURE	UPI number mapping already exists / UPI Number is mapped to different VPA

Create New Upi Number

# Sample request

curl -X POST
-H "Content-Type: application/json"
-H 'x-merchant-channel-id: APLTEST'
-H 'x-merchant-signature: 823647862547652376452378456'
-H 'x-merchant-id: APLTEST'
-H 'x-timestamp: 1496918882000'
-d '{
  "merchantCustomerId": "DEMO-CUST-1234",
  "upiRequestId": "APLVGXVGDV21r521r53MAPPERdbhsbcs22",
  "upiNumber": "755027712",
  "vpa": "abcd@xyz",
  "deviceFingerPrint": "4e11ca23af4aa457dc1151699762b371e07cb0b685f87eeadba14bc39229ee6c",
  "fallbackDeviceFingerPrint": "",
  "udfParameters": "{}",
  "packageName": "in.amazon.mShop.android.shopping"
}' "{{host}}/api/n2/merchants/upiNumber/create"

# The above command returns JSON structured like this:

{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload": {
        "merchantChannelId": "APLTEST",
        "status": "ACTIVE",
        "gatewayResponseStatus": "SUCCESS",
        "vpa": "abcd@xyz",
        "merchantId": "APLTEST",
        "gatewayResponseMessage": "SUCCESS",
        "gatewayResponseCode": "00",
        "gatewayTransactionId": "APLVGXVGDV21r521r53MAPPERdbhsbcs22",
        "customerMobileNumber": "917550277516",
        "upiNumber": "755027712",
        "merchantCustomerId": "DEMO-CUST-1234",
        "gatewayTimestamp": "2021-11-08T14:45:37+05:30"
    },
    "udfParameters": "{}"
}

This endpoint is used to create a new UPI number.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
upiRequestId	Unique id sent to UPI switch	35 character alphanumeric that starts with a unique merchant prefix
upiNumber	Number mapped to a customer's VPA that is unique to the customer across the UPI ecosystem	8 to 10 digit numeric string. 10 digit number must be the mobile number. Last 3 digits must not be same. Must not start with a 0.
vpa	Vpa to be linked with the provided Upi Number	vpa@handle
existingVpa optional	Previous Vpa that was linked with the provided Upi Number at other PSP.	Required while porting Upi Number of 10 digits (Mobile Number)
deviceFingerPrint	Device fingerprint of the customer	String
fallbackDeviceFingerPrint optional	Fallback Device fingerprint of the customer	String
udfParameters optional	Stringified JSON for udf parameters	JSON string
packageName optional	Package name of the UPI application	String

Response parameters

Parameter	Description	Values
status	Status of the API.	SUCCESS, FAILURE
responseMessage	PSP response message for the API	Refer error code section
responseCode	PSP response code for the API	Refer error code section
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
status	Status of the Upi Number.	String(ACTIVE, FAILED)
gatewayResponseStatus	Response status returned by gateway.	String(SUCCESS, FAILURE)
vpa	Vpa linked to the upiNumber	vpa@handle
merchantId	Unique id for the merchant as passed in request headers	String
gatewayResponseMessage	Response message for code returned by gateway.	String
gatewayResponseCode	Response code returned by gateway. Refer the table below for all possible values.	String
gatewayTransactionId	Transaction id returned by gateway. Same as upiRequestId passed in request	String
customerMobileNumber	Mobile number of the customer.	12 character string
upiNumber	Number mapped to a customer's VPA that is unique to the customer across the UPI ecosystem	As passed in request
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
gatewayTimestamp	Gateway timestamp for the Api call.	String(YYYY-MM-DDTHH:MM:SS+05:30)
udfParameters	Stringified json for udf parameters.	String

responseCode	responseMessage
JPMM8	Existing Vpa doesnot match with the CHECK call
JP40	Check request not found for the Upi Number
JP41	User's Vpa doesnot match with the CHECK call
JP42	Port request not found for the Upi Number
JP43	Max allowed UPI number registrations reached

gatewayResponseCode	gatewayResponseStatus	Description
MM17	FAILURE	Upi Number already exists.

Update Upi Number

# Sample request

curl -X POST
-H "Content-Type: application/json"
-H 'x-merchant-channel-id: APLTEST'
-H 'x-merchant-signature: 823647862547652376452378456'
-H 'x-merchant-id: APLTEST'
-H 'x-timestamp: 1496918882000'
-d '{
  "upiNumber": "755027712",
  "merchantCustomerId": "DEMO-CUST-1234",
  "upiRequestId": "APLVGXVGDV21r521r53MAPPERdbhsbcs372",
  "vpa": "abcd@xyz",
  "action":"DISABLE",
  "deviceFingerPrint": "4e11ca23af4aa457dc1151699762b371e07cb0b685f87eeadba14bc39229ee6c",
  "fallbackDeviceFingerPrint": "",
  "udfParameters": "{}",
  "packageName": "in.amazon.mShop.android.shopping"
}' "{{host}}/api/n2/merchants/upiNumber/update"

# The above command returns JSON structured like this:

{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload": {
        "merchantChannelId": "APLTEST",
        "status": "DISABLED",
        "gatewayResponseStatus": "SUCCESS",
        "vpa": "abcd@xyz",
        "merchantId": "APLTEST",
        "gatewayResponseMessage": "Upi number was updated successfully",
        "gatewayResponseCode": "00",
        "gatewayTransactionId": "APLVGXVGDV21r521r53MAPPERdbhsbcs372",
        "customerMobileNumber": "917550277516",
        "upiNumber": "755027712",
        "merchantCustomerId": "DEMO-CUST-1234",
        "gatewayTimestamp": "2021-11-08T15:15:08+05:30"
    },
    "udfParameters": "{}"
}

This is a clubbed api endpoint for change vpa, disable, delete and reactivate the Upi Number.

Request parameters

Parameter	Description	Constraints
upiNumber	Number mapped to a customer's VPA that is unique to the customer across the UPI ecosystem	8 to 10 digit numeric string. 10 digit number must be the mobile number. Last 3 digits must not be same. Must not start with a 0.
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
upiRequestId	Unique id sent to UPI switch	35 character alphanumeric that starts with a unique merchant prefix
vpa	Vpa to be linked with the provided Upi Number	vpa@handle
existingVpa optional	Previous VPA that was linked with the provided UPI number	Required when action is CHANGE_VPA. existingVpa and vpa should belong to the same customer and be part of the same PSP
action	Update action to be performed on UPI Number	CHANGE_VPA, DISABLE, DELETE, REACTIVATE
deviceFingerPrint	Device fingerprint of the customer	String
fallbackDeviceFingerPrint optional	Fallback Device fingerprint of the customer	String
udfParameters optional	Stringified JSON for udf parameters	JSON string
packageName optional	Package name of the UPI application	String

Response parameters

Parameter	Description	Values
status	Status of the API.	SUCCESS, FAILURE
responseMessage	PSP response message for the API	Refer error code section
responseCode	PSP response code for the API	Refer error code section
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
status	Status of the Upi Number.	ACTIVE, DISABLED, DELETED
gatewayResponseStatus	Response status returned by gateway.	String(SUCCESS, FAILURE)
vpa	Vpa linked to the upiNumber	vpa@handle
merchantId	Unique id for the merchant as passed in request headers	String
gatewayResponseMessage	Response message for code returned by gateway.	String
gatewayResponseCode	Response code returned by gateway. Refer the table below for all possible values.	String
gatewayTransactionId	Transaction id returned by gateway. Same as upiRequestId passed in request	String
customerMobileNumber	Mobile number of the customer.	12 character string
upiNumber	Number mapped to a customer's VPA that is unique to the customer across the UPI ecosystem	As passed in request
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
gatewayTimestamp	Gateway timestamp for the Api call.	String(YYYY-MM-DDTHH:MM:SS+05:30)
udfParameters	Stringified json for udf parameters.	String

responseCode	responseMessage
JP44	Upi number status is pending to be synced
JP45	Action cannot be performed as upi number status is {{status}}
JP46	Status is already {{status}}

gatewayResponseCode	gatewayResponseStatus	Description
MM2	FAILURE	Mapping does not exist
MM7	FAILURE	Mapping activation not allowed
MM9	FAILURE	Cannot activate deregistered mobile

Upi Number Delink/SyncPending Callback

# A callback with following POST data will be sent to the endpoint configured for "PORTED_OUT"

{
  "action": "PORTED_OUT",
  "customResponse": "{}",
  "customerMobileNumber": "917550277516",
  "gatewayTimestamp": "2021-11-08T15:15:08+05:30",
  "gatewayTransactionId": "APLVGXVGDV21r521r53MAPPERdbhsbcs372",
  "merchantChannelId": "APLTEST",
  "merchantCustomerId": "DEMO-CUST-1234",
  "merchantId": "APLTEST",
  "status": "SUCCESS",
  "type": "UPI_NUMBER_MAPPER",
  "upiNumber": "755027712",
  "vpa": "abcd@xyz"
}

This callback is used for two purposes:

Purpose 1) This callback will be sent when a 10 digit UPI Number (Mobile Number) has been delinked from a particular Vpa and moved to a different PSP. In this case, action is PORTED_OUT and upiNumber will be 10 digit always.

Purpose 2) Juspay will asynchronously resolve UPI numbers that go to pending status, which happens when create or update UPI number call times out because of timeout at NPCI's end. When such a resolution to terminal status happens, this callback will be sent to the merchant using which merchant shall update/sync their database. In this case, action will be one of CREATE, REACTIVATE, CHANGE_VPA, DISABLE, DELETE and upiNumber can be 8, 9 or 10 digit.

Important notes about optional parameters and more:

1. In the first (current) version of UPI number feature, Juspay does not store the action and upiRequestId passed by merchant in create and update UPI number APIs. Hence Juspay will not be able to retrieve these values. So the equivalent action and gatewayTransactionId parameters shall NOT be passed for a bunch of UPI numbers. The status parameter will also be SUCCESS by default for this bunch of UPI numbers. (Applicable in Purpose 2)

2. upiNumberStatus will NOT be sent whenever action is PORTED_OUT. (Applicable in Purpose 1)

3. status will be SUCCESS when the action has succeeded and FAILURE if the action has failed.

Parameter	Description
action optional	Purpose of the callback, values possible are PORTED_OUT, CREATE, REACTIVATE, CHANGE_VPA, DISABLE, DELETE.
customResponse	Stringified JSON parameter for future use.
customerMobileNumber	Mobile number of the customer.
gatewayTimestamp	Timestamp of when the callback was initiated. (YYYY-MM-DDTHH:MM:SS+05:30)
gatewayTransactionId optional	UPI request id returned by gateway for the transaction.
merchantChannelId	Unique id for the channel via which request is made.
merchantCustomerId	Merchant generated unique id for customer.
merchantId	Unique id for merchant.
status	Status/Result of the action, values could be SUCCESS, FAILURE.
type	A unique key to identify the Upi Mapper feature, value is UPI_NUMBER_MAPPER.
upiNumber	Numeric 8-9 digits or 10 digits Mobile Number.
upiNumberStatus optional	Current terminal status of the UPI number after resolution. ACTIVE, DISABLED, DELETED.
vpa	Vpa linked to the upiNumber.

UPI Lite APIs

[Draft] Lite Registration

curl -L -X POST '{{host}}/api/n2/merchants/npci/lite/account'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "2263743036",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
  "credBlock": "{\"identitycred\":{\"data\":{\"encryptedBase64String\":\"2.3.lite-v1.8|eyJhb....GPSK2s4OSA==\",\"ki\":\"202112281\",\"code\":\"NPCI-LITE\"},\"subType\":\"IDENTITY\",\"type\":\"DEVICE\"}}"
}'

# Response for GetLiteParams: HTTP 200 OK
{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload": {
        "rotation": "29",
        "lrn": "01002600010235200167842752521900052",
        "gatewayResponseStatus": "SUCCESS",
        "gatewayResponseMessage": "Get Lite Keys fetched successfully",
        "gatewayResponseCode": "00",
        "respListKeys": "<ns2:RespListKeys xmlns:ns2=\"http://npci.org/upi/schema/\" xmlns:ns3=\"http://npci.org/cm/schema/\"><Head msgId=\"9bSQLnxnN\" orgId=\"NPCI\" ts=\"2023-03-10T14:43:46+05:30\" ver=\"2.0\"></Head><Resp reqMsgId=\"AUTJP292dffa679de4df9bb11ae1edec73e\" result=\"SUCCESS\"></Resp><Txn id=\"AUTc14c050389f5464a8af36741d6c33d2c\" note=\"Lite Creation\" refId=\"AUTJP9b7e907d88c9488a81ec3e9c607558\" refUrl=\"https://www.juspay.com/\" ts=\"2023-03-10T14:43:46+05:30\" type=\"GetLite\"></Txn><Ac addrType=\"ACCOUNT\"><Detail name=\"IFSC\" value=\"AABF0008032\"></Detail><Detail name=\"ACTYPE\" value=\"SAVINGS\"></Detail><Detail name=\"ACNUM\" value=\"83748239234872\"></Detail><Detail name=\"LRN\" value=\"01002600010235200167842752521900052\"></Detail></Ac><keyList></keyList><paramsList><param code=\"DEVICE-CERT\" owner=\"NPCI\"><paramValue xmlns:xs=\"http://www.w3.org/2001/XMLSchema\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:type=\"xs:string\">ajDog94b6Ocdj+YVBeMuVvaDtcfrzdecxMDG88JrZimYddiO8ij+3eEQe6AIokRa8QKFRzw9uUJzodZxd4gH87i/oGjPR60XNO5cqYKgJsZGcAEMooLbI6cIl5LcuHUG5lqaRP4O//m1C5oYiKpmnkm66cq0KiJAgwG3PyjQfXXEHpo/OldWCY6XGBnp2sUq1IjKQgILJNRVBdw28tTOh6cfbc5lOpkPPCXLgGII8K8NEn/T5rjHH3fPmx+S6qlwipvnPvrb3noRk+ctiprNxds2ZYayDZWjNxGlRoe6GKXLM1GCntj4bsg0Sv95wxLuhhoelQtHQCAFKNomZVSOEvAldZqBOOV2nABDJ2lNQyx94fxRd/PjZzpKTQnMocx9djOaylLZ6mCofyvJnPdKsS2vqrJmPYB0inHSywBWw8I7Z+LBZe8Jhk5uOCIRBHeVfmiBmtFUZUKzaOFhk2zgQT5RUttzdP88LX4hk2aw1ztQtQexfxleHRelAuGoQ4IXa6/HNH6yqzDwrSUnbSddYNcx0778RKoj5u+zoyQ8j1u+XZHgfx3MX0bExl1e+TXfL/9FD7aALBQc+kjw1CrkwGE074tzEhfLct/Ga5/YIeVvdsLepD17kJmMUA22X9C5y/ofakqSxDRI5BNgUlCN4EkFIc5raszS+3x9O296SIEw+2XhX0yj7G3rfBnA+YvHM8fKJLRY0i8NgIMQoYGv0c8jvFk46MV+ryx8PQPZyInl+v1otbMRfAwaSU/rR/IF8axIcw3K+z5Tnp8qCXkGYaPLat1w4uUSVvMzMr8XvrrJ1EAABqy/5uFFA5OAfUMRbyTM1yPkj1VCXk6JbCZUs0VQ4VxJIQBOs3f/VbFip4JKOHmWtoZ48oT4aaULVKJ2xyJBFXpLToZm8yWzmqsvP0o5uFFrvvx96VzYgUo8boJ/N1u0rHLJ5bRR8hyileuwitptDaWDph+DvfZBnFqtrTgX/ZXmGU+PC2FPZDcJGZkTqu7WbXLVHPO2KoSkrd9Xdn4P03AIh2L98fLFw8ydP5c88FKPTLUQB5PPXWZjoOw72PBafOcWNqJYblqXeXMeGbSJdp9Z7jk0g8gGyQpdFf07uW8Vlnog6nWjvvvE01kibUemIlmhxSvkaVay9fL3TTFVTp/2eWbcK/3nJH4GybcyKwNskQ83IHilnq2HtXP3IEa5L0KLLIvkkzfYi+VI685n0LfnZSmG3UX6clX9dSUH3Sbf4NrT1bi5CUkuZU40P5Fkgt/2E5LNqqZlpYcMSRqUTOKkzYlXO2IH05JAvGUCByNxa2Mj2rs8WKzW/nLbLU4p4buhcJRigrf+3qpEdwNIqgNuNKVhwJveM7hEkS8obJcI8eRfKL63Ft7Zii++tUgdu9KnYxWHHe0oLZPCJsUD5Lmb2SVVQkTVH4+F6admaJJvyAo+2GkTUMaVhmHhLRcP4EMmD4YMu5xiui+e5a+Inef7bnnzlMj77ps5b6NzpOkDwGn90VYHgghFGlnZGXRe2rB9xuLijc3/AwbWl+E=|jHx/1I7MGTvmqG730Sn/IQ==</paramValue></param><param code=\"STATE\" owner=\"NPCI\"><paramValue xmlns:xs=\"http://www.w3.org/2001/XMLSchema\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:type=\"xs:string\">OKcouKf6HO9MsU6z2q4zZqbCRXUIyYkPH0VGwfZUbk+9BH+IBAMH4RqpSFyNT7vBPTBiEkFWLZrruVMpVakr3GO3s0cfs6QD3+Tpf9kzHqUwiijxxUHE0hI9T1gfgshqdmjVV2h42teQMUlAkF6CXvua7H/ziX/YSnUEKvJ0r2IHvUGLt2KYIfPly8sY9CR73gcxDGnh2CRHOMVHhoCvIMMuuWngSUDjfEcNyS/ixZKWZebdEFKNJQ3n/XMvJBekMzXYUS0EeZ1kOHEkZ11HVFvYTFl1GGhUSsFXr/NR5fvNZ9BgNBH5KSZdrsY2PYGy9+VAonKy93Ggt+6nAiku+h/mgTOA+8UcOpHrgjgybIxdbEwKvptFq1ItQlOkpSSxvgpdWdwtDktCIwn7dp7n/bbSN/p1vuFMq2X5fJTSBgcBmpecHIw0nLCtLLB1R580mfl964iKErTcg8VUimxKCR6FN1Oc7I0cgGdh9nwxMpiGOrfs/dqXd8ZQAiY0/tOKUI3hE7wOfrct7stYhBc+0gZj778JXn2WPIh2uku6sYPPzVmZYJBLVN4GFcWapaTJsrs0B9KK3mOqTG+Wuk+Jj+WeBwN1O6w/IdIcdmyYAzeKpQ3QB/lsWKx677nsvV1BMz5egZHZMDSnTBRDgRtwK4HIGh2TP+WL2t/DC0OOunIs/Z2YwIULvzXUf3wEPKdm7HUfWC6oeb7astHiN4UjH7yjS+Vn70LP5ce57XMuep+hq8LvfKmODC6M7Q==|Wsmrubz4U8AYri46s/9uaw==</paramValue></param></paramsList><Signature xmlns=\"http://www.w3.org/2000/09/xmldsig#\" SignatureValue=\"nZTlHbSTNTzMSLapJdooMGRbSC8IUBVq2j4z455KviSXZ9v7WIDfIKgmYqJZzmJqfBFZk2rIB0KA\r\no0TXzRSf1QB+Lyzdm8td5pURnpTM2CJ8J3TP5wERivEJdvfSmiCjLz7PFRBSn3npqc1c8l/GeHBy\r\nWN9VtpFfXU1rm1RvVV/4hqaOG+rVPmyxoFRSda/oHICuG1+IOC3A71LN5sm1o9v4Y8kf8W/8vnK1\r\nW3KG8rAaBS75+/mRFPianfniFf/Lo6IcfPe8Td52fSdD75YxdIMjtczhm3lyZToYv5sMZLhHYpMM\r\nGsevkZvV2pJHSNoMSxdovkyFR+Oo/VINEP/4lw==\"><SignedInfo><CanonicalizationMethod Algorithm=\"http://www.w3.org/TR/2001/REC-xml-c14n-20010315\"></CanonicalizationMethod><SignatureMethod Algorithm=\"http://www.w3.org/2001/04/xmldsig-more#rsa-sha256\"></SignatureMethod><Reference URI=\"\" DigestValue=\"ASgXCiIkfVAprmI23uVcVl3FSt5YUUtKm/vONg0MiWs=\"><Transforms><Transform Algorithm=\"http://www.w3.org/2000/09/xmldsig#enveloped-signature\"></Transform></Transforms><DigestMethod Algorithm=\"http://www.w3.org/2001/04/xmlenc#sha256\"></DigestMethod></Reference></SignedInfo></Signature></ns2:RespListKeys>",
    }
}

This API will be used to create LRN(Lite Reference Number) for UPI Lite. XML provided should be passed to CL as it is.

Request parameters

Parameter	Description	Values
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
bankAccountUniqueId	Unique id for the bank account to be linked	bankAccountUniqueId in the response of Fetch Accounts api call.
credBlock	Encrypted identity credblock	As return by Common Library

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseMessage	PSP response message for the API	Refer error code section
responseCode	PSP response code for the API	Refer error code section
rotation	merchants needs to call this api every "rotation" days, to rotate DEVICE-CERT and STATE	String
lrn	Lite Reference Number which is reference the number provided for the wallet linked with account number	String
respListKeys	xml which we will get after doing ReqListKeys (GetLite). This will give the lrn of the user	String
gatewayResponseStatus	Response status for Lite Registration	SUCCESS, FAILURE
gatewayResponseCode	Response code for Lite Registration	String
gatewayResponseMessage	Response message for Lite Registration	String

[Draft] Initial Top Up

curl -L -X POST '{{host}}/api/n2/merchants/transactions/sendMoney'
-H 'content-type: application/json' \
  'accept: application/json', \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1668669188' \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "merchantRequestId": "redId1234",
  "payerVpa": "9416ef1d-72e8-4e6b-a38a-8003d765d3eb@axisuat1",
  "payeeVpa": "9416ef1d-72e8-4e6b-a38a-8003d765d3eb@axisuat1",
  "payeeName": "Hitesh",
  "amount": "1.00",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
  "credBlock": "{\"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.3-v1.8|gZBDyM...TEg==\",\"code\":\"NPCI\"}},\"arqccred\":{\"type\":\"ARQC\",\"subType\":\"initial\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20160218\",\"hmac\":\"\",\"encryptedBase64String\":\"2.3.lite-v1.8|eyJhbG...5CTovH7A==\",\"code\":\"NPCI-LITE\"}}}",
  "remarks": "UPI",
  "currency": "INR",
  "transactionType": "P2P_PAY",
  "transactionReference": "P1708071422508815250029",
  "refUrl": "https://www.abcxyz.com/",
  "purpose": "41",
  "udfParameters": "{\"payType\":\"P2P_PAY\"}",
  "ifsc" : "NREB0000001",
  "lrn" : "19216812200107001166427573769209547",
  "timestamp": "2023-04-10T10:46:27.872523+05:30",
  "packageName": "in.amazon.mShop.android.shopping"
}'
# Response: HTTP 200 OK
{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload": {
        "merchantId": "TEST",
        "merchantChannelId": "TESTAPP",
        "merchantCustomerId": "test-merchantcustomer-1",
        "merchantRequestId": "redId1234",
        "customerMobileNumber": "912263743036",
        "payerVpa": "9416ef1d-72e8-4e6b-a38a-8003d765d3eb@axisuat1",
        "payeeMcc": "0000",
        "payeeMerchantCustomerId": "DEMO-CUST-5678",
        "payeeName": "Hitesh",
        "payeeVpa": "9416ef1d-72e8-4e6b-a38a-8003d765d3eb@axisuat1",
        "refUrl": "https://www.juspay.com/",
        "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
        "bankCode": "508534",
        "maskedAccountNumber": "XXXX8862",
        "amount": "1.00",
        "transactionType": "P2P_PAY",
        "transactionTimestamp": "2023-04-10T13:15:48+05:30",
        "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
        "gatewayReferenceId": "346622928434",
        "gatewayResponseStatus": "SUCCESS",
        "gatewayResponseCode": "00",
        "gatewayResponseMessage": "Your transaction is successful",
        "gatewayPayerResponseCode": "00",
        "gatewayPayeeResponseCode": "00",
        "gatewayPayerReversalResponseCode": "00",
        "gatewayPayeeReversalResponseCode": "00",
        "riskScore": "00000",
        "arpc": "2.3.lite-v1.8|eyJhb...KnxME=",
    },
    "udfParameters": "{\"payType\":\"P2P_PAY\"}"
}

This API will be used for initial topup of UPI wallet

Note:

1. Value of Payer and Payee Vpa will be same.
2. timestamp should be passed by merchant which should be same which was given to CL.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
deviceFingerPrint	Device fingerprint of the customer	String
merchantRequestId	Merchant generated id for the transaction	35 characters alphanumeric
payerVpa	Vpa of customer adding money.	something@handle
payeeVpa	Vpa of customer adding money.	something@handle
payeeName optional	Name of the payee	String as returned in the Verify VPA API
amount	Amount for the payment	As passed in the request
upiRequestId	Unique request id passed to UPI switch	35 character alphanumeric. Should always start with merchant prefix provided.
bankAccountUniqueId	Unique id for the payer selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call
payeeBankAccountUniqueId optional	Unique id for the payee selected bank account for self transfer	bankAccountUniqueId in the response of Fetch Accounts api call
credBlock	Encrypted credblock containing user mpin and arqccred	As returned by Common Library
remarks	Any transaction summary	62 characters alphanumeric with hyphen
currency	Currency code	String - INR
transactionType	Type of payment	P2P_PAY
transactionReference optional	Transaction reference id	String
refUrl optional	Reference url for the intent transaction	String
refCategory optional	Details for refUrl, whether it is 01 (Advertisement), 02(Invoice)	String
mcc optional	Merchant category code	String
initiationMode optional	Defines the initiation mode of the transaction	Initiation Modes
purpose optional	Defines the purpose code of the transaction	Purpose Codes
udfParameters optional	Udf parameters as passed in the request	JSON string
ifsc	Ifsc for the bank account as returned by NPCI	String
lrn	Lite Reference Number which is reference the number provided for the wallet linked with account number	String
timestamp	This is the timestamp in ISO format which was sent to CL for generating ARQC credblock. This timestamp should be passed as it is which was passed to CL	String
packageName optional	Package name of the UPI application	String

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantRequestId	Merchant generated id for the transaction	As passed in the request
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
payerVpa	Customer vpa used for the payment	As passed in the request
payeeMcc	MCC for the payee	String
payeeMerchantCustomerId optional	Merchant generated unique id for customer who received the payment. Only if it is an onus P2P transaction.	String
payeeName optional	Name of the upi user who received the payment. Only if payment is done to a non A/C+IFSC vpa.	String
payeeVpa	Vpa of the upi user who received the payment	something@handle
refUrl	Reference url for the intent transaction	String
bankAccountUniqueId	Unique id for the selected bank account	As passed in the request
bankCode	Bank code of the account which was used	Valid bank IIN
maskedAccountNumber	Masked account number of the account which was used	XXXX123456
amount	Amount for the payment	As passed in the request
transactionType	Type of payment	As sent in request
transactionTimestamp	Timestamp of when the transaction was attempted	YYYY-MM-DDTHH:MM:SS+05:30
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayReferenceId	Reference id returned by the gateway	String
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
gatewayPayerResponseCode optional	Response code returned by gateway	String
gatewayPayeeResponseCode optional	Response code returned by gateway	String
gatewayPayerReversalResponseCode optional	Response code returned by gateway	String
gatewayPayeeReversalResponseCode optional	Response code returned by gateway	String
riskScore optional	RiskScore shared by NPCI or Bank	String
udfParameters optional	Udf parameters as passed in the request	JSON string
arpc	This comes from NPCI for all lite txns and it needs to be passed to CL	String

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Payment Success.
JPLTL	FAILURE	Minimum amount for lite top up should be 1
JPHTL	FAILURE	Lite top up limit exceeds 2000

[Draft] Subsequent Top Up

curl -L -X POST '{{host}}/api/n2/merchants/transactions/sendMoney'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "merchantRequestId": "redId1234",
  "payerVpa": "9416ef1d-72e8-4e6b-a38a-8003d765d3eb@axisuat1",
  "payeeVpa": "9416ef1d-72e8-4e6b-a38a-8003d765d3eb@axisuat1",
  "payeeName": "John Doe",
  "amount:" "2.00",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
   "credBlock": "{\"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.3-v1.8|gZBDyM...TEg==\",\"code\":\"NPCI\"}},\"arqccred\":{\"type\":\"ARQC\",\"subType\":\"initial\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20160218\",\"hmac\":\"\",\"encryptedBase64String\":\"2.3.lite-v1.8|eyJhbG...5CTovH7A==\",\"code\":\"NPCI-LITE\"}}}",
  "remarks": "UPI",
  "currency": "INR",
  "transactionType": "P2P_PAY",
  "transactionReference": "P1708071422508815250029",
  "refUrl": "https://www.abcxyz.com/",
  "purpose": "42",
  "ifsc" : "NREB0000001",
  "lrn" : "19216812200107001166427573769209547",
  "timestamp": "2023-03-04T10:46:27.872523+05:30"
  "udfParameters": "{\"payType\":\"P2P_PAY\"}",
  "packageName": "in.amazon.mShop.android.shopping"
}'

# Response: HTTP 200 OK
{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload": {
        "merchantId": "TEST",
        "merchantChannelId": "TESTAPP",
        "merchantCustomerId": "test-merchantcustomer-1",
        "merchantRequestId": "redId1234",
        "customerMobileNumber": "919988776655",
        "payerVpa": "9416ef1d-72e8-4e6b-a38a-8003d765d3eb@axisuat1",
        "payeeMcc": "0000",
        "payeeMerchantCustomerId": "DEMO-CUST-5678",
        "payeeName": "John Doe",
        "payeeVpa": "9416ef1d-72e8-4e6b-a38a-8003d765d3eb@axisuat1",
        "refUrl": "https://www.abcxyz.com/",
        "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
        "bankCode": "123456",
        "maskedAccountNumber": "XXXX123456",
        "amount": "2.00",
        "transactionType": "P2P_PAY",
        "transactionTimestamp": "2023-03-04T10:46:27.872523+05:30",
        "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
        "gatewayReferenceId": "809323430413",
        "gatewayResponseStatus": "SUCCESS",
        "gatewayResponseCode": "00",
        "gatewayResponseMessage": "Your transaction is successful",
        "gatewayPayerResponseCode": "00",
        "gatewayPayeeResponseCode": "00",
        "gatewayPayerReversalResponseCode": "00",
        "gatewayPayeeReversalResponseCode": "00",
        "riskScore": "00000",
        "arpc": "2.3.lite-v1.8|eyJhbX...CUVKnxME="
    },
    "udfParameters": "{\"payType\":\"P2P_PAY\"}"
}

This API will be used to topup UPI wallet again.

Note:

1. Value of Payer and Payee Vpa will be same.
2. timestamp should be passed by merchant which should be same which was given to CL.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
deviceFingerPrint	Device fingerprint of the customer	String
merchantRequestId	Merchant generated id for the transaction	35 characters alphanumeric
payerVpa	Vpa of customer adding money.	something@handle
payeeVpa	Vpa of customer adding money.	something@handle
payeeName optional	Name of the payee	String as returned in the Verify VPA API
amount	Amount for transaction	Numeric string with two decimals
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
bankAccountUniqueId	Unique id for the payer selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call
payeeBankAccountUniqueId optional	Unique id for the payee selected bank account for self transfer	bankAccountUniqueId in the response of Fetch Accounts api call
credBlock	Encrypted credblock containing user mpin	As returned by Common Library
remarks	Any transaction summary	50 characters alphanumeric with space and hyphen
currency	Currency code	String - INR
transactionType	Type of payment	P2P_PAY
transactionReference optional	Transaction reference id	String
refUrl optional	Reference url for the intent transaction	String
refCategory optional	Details for refUrl, whether it is 01 (Advertisement), 02(Invoice)	String
mcc optional	Merchant category code	String
initiationMode optional	Defines the initiation mode of the transaction	Initiation Modes
purpose	Defines the purpose code of the transaction	Purpose Codes
udfParameters optional	Stringified JSON for udf parameters	JSON string
packageName optional	Package name of the UPI application	String
ifsc	Ifsc for the bank account as returned by NPCI	String
lrn	Lite Reference Number which is reference the number provided for the wallet linked with account number	String
timestamp	This is the timestamp in ISO format which was sent to CL for generating ARQC credblock. This timestamp should be passed as it is which was passed to CL	String

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantRequestId	Merchant generated id for the transaction	As passed in the request
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
payerVpa	Customer vpa used for the payment	As passed in the request
payeeMcc	MCC for the payee	String
payeeMerchantCustomerId optional	Merchant generated unique id for customer who received the payment. Only if it is an onus P2P transaction.	String
payeeName optional	Name of the upi user who received the payment. Only if payment is done to a non A/C+IFSC vpa.	String
payeeVpa	Vpa of the upi user who received the payment	something@handle
refUrl	Reference url for the intent transaction	String
bankAccountUniqueId	Unique id for the selected bank account	As passed in the request
bankCode	Bank code of the account which was used	Valid bank IIN
maskedAccountNumber	Masked account number of the account which was used	XXXX123456
amount	Amount for the payment	As passed in the request
transactionType	Type of payment	As sent in request
transactionTimestamp	Timestamp of when the transaction was attempted	YYYY-MM-DDTHH:MM:SS+05:30
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayReferenceId	Reference id returned by the gateway	String
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
gatewayPayerResponseCode optional	Response code returned by gateway	String
gatewayPayeeResponseCode optional	Response code returned by gateway	String
gatewayPayerReversalResponseCode optional	Response code returned by gateway	String
gatewayPayeeReversalResponseCode optional	Response code returned by gateway	String
riskScore optional	RiskScore shared by NPCI or Bank	String
udfParameters optional	Udf parameters as passed in the request	JSON string
arpc	This comes from NPCI for all lite txns and it needs to be passed to CL	Sring

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Payment Success.
JPLTL	FAILURE	Minimum amount for lite top up should be 1
JPHTL	FAILURE	Lite top up limit exceeds 2000

[Draft] Lite Send Money

curl -L -X POST '{{host}}/api/n2/merchants/transactions/sendMoney'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "merchantRequestId": "redId1234",
  "payerVpa": "customer@handle",
  "payeeVpa": "payee@xyz",
  "payeeName": "John Doe",
  "amount:" "2.00",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
  "credBlock": "{\"arqccred\":{\"type\":\"ARQC\",\"subType\":\"initial\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20160218\",\"hmac\":\"\",\"encryptedBase64String\":\"2.3.lite-v1.8|eyJhb...ql4A==\",\"code\":\"NPCI-LITE\"}}}",
  "remarks": "UPI",
  "currency": "INR",
  "transactionType": "P2P_PAY",
  "transactionReference": "P1708071422508815250029",
  "refUrl": "https://www.abcxyz.com/",
  "purpose": "44",
  "ifsc" : "NREB0000001",
  "lrn" : "19216812200107001166427573769209547",
  "timestamp": "2023-03-04T10:46:27.872523+05:30",
  "udfParameters": "{}",
  "packageName": "in.amazon.mShop.android.shopping"

}'

# Response: HTTP 200 OK
{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload": {
        "merchantId": "TEST",
        "merchantChannelId": "TESTAPP",
        "merchantCustomerId": "test-merchantcustomer-1",
        "merchantRequestId": "redId1234",
        "customerMobileNumber": "919988776655",
        "payerVpa": "customervpa@bank",
        "payeeMcc": "0000",
        "payeeMerchantCustomerId": "DEMO-CUST-5678"
        "payeeName": "John Doe",
        "payeeVpa": "payee@xyz",
        "refUrl": "https://www.abcxyz.com/",
        "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
        "bankCode": "123456",
        "maskedAccountNumber": "XXXX123456",
        "amount": "2.00",
        "transactionType": "P2P_PAY",
        "transactionTimestamp": "2023-03-04T10:46:27.872523+05:30",
        "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
        "gatewayReferenceId": "809323430413",
        "gatewayResponseStatus": "SUCCESS",
        "gatewayResponseCode": "00",
        "gatewayResponseMessage": "Your transaction is successful",
        "gatewayPayerResponseCode": "00",
        "gatewayPayeeResponseCode": "00",
        "gatewayPayerReversalResponseCode": "00",
        "gatewayPayeeReversalResponseCode": "00",
        "riskScore": "00000",
        "arpc": "2.3.lite-v1.8|eyJhbX...CUVKnxME="

    },
    "udfParameters": "{\"payType\":\"P2P_PAY\"}"
}

This api will be used for completing all P2P and P2M Payment scenarios. This includes

• Incoming Intent Payment
• Scan and Pay (UPI QR & Bharat QR)
• P2P Pay (Vpa & Account+IFSC)
• Payment to PSP merchant

The api can be invoked to process different types of payments. The transactionType key of request is used to identify the type of payment. Possible values are P2M_PAY, P2P_PAY, SELF_PAY, INTENT_PAY and SCAN_PAY. Depending on the payment type, some additional parameters need to be passed.

P2M_PAY is to be used for payment to a PSP merchant only. The payeeVpa should be a valid PSP generated vpa for the merchant.

INTENT_PAY and SCAN_PAY are used for the intent and qr scan transactions. Both UPI QR and Bharat QR codes are supported.

P2P_PAY is to be used for completing all other P2P payment scenarios. For direct to account transfers, payeeVpa should be of format <account-no>@<ifsc-code>.ifsc.npci like 12345@BankIFSC.ifsc.npci.

SELF_PAY is to be used for doing a self transfer between customer accounts having same vpa domain.

Below are some request parameters required to be handled specifically according to the payment scenario.

Parameter	P2M Pay	P2P Pay	Scan & Pay	Incoming Intent	Self Pay
transactionType	P2M_PAY	P2P_PAY	SCAN_PAY	INTENT_PAY	SELF_PAY
payeeVpa	Mandatory	Mandatory	pa in deeplink url	pa in deeplink url	Mandatory
payeeName	Not Required	Not required for account transfers only	pn in deeplink url	pn in deeplink url	Mandatory
amount	Mandatory	Mandatory	am in deeplink url	am in deeplink url	Mandatory
upiRequestId	Mandatory	Mandatory	tid in deeplink url	tid in deeplink url	Mandatory
remarks	Mandatory	Mandatory	tn in deeplink url	tn in deeplink url	Mandatory
refUrl	Not Required	Not Required	url in deeplink url	url in deeplink url	Not Required
refCategory	Not Required	Not Required	category in deeplink url	category in deeplink url	Not Required
currency	INR	INR	cu in deeplink url	cu in deeplink url	INR
mcc	Mandatory	Not Required	mc in deeplink url	mc pin deeplink url	Not Required
transactionReference	Not Required	Not Required	tr in deeplink url	tr in deeplink url	Not Required
payeeBankAccountUniqueId	Not Required	Not Required	Not Required	Not Required	Mandatory

Note

1. Validity of a payeeVpa can be verified using the Verify VPA API.
2. SERVICE_UNAVAILABLE_{entity}_{error} will be returned in case of NPCI timeout or deemed transactions.
3. In case of UPI LITE transactions lrn and timestamp is Mandatory
4. Timestamp should be passed by merchant which should be same which was given to CL.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
deviceFingerPrint	Device fingerprint of the customer	String
merchantRequestId	Merchant generated id for the transaction	35 characters alphanumeric
payerVpa	VPA of the customer to be used for payment	something@handle
payeeVpa	Vpa of the payee to whom money is being sent	something@handle
payeeName optional	Name of the payee	String as returned in the Verify VPA API
amount	Amount for transaction	Numeric string with two decimals
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
bankAccountUniqueId	Unique id for the payer selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call
payeeBankAccountUniqueId optional	Unique id for the payee selected bank account for self transfer	bankAccountUniqueId in the response of Fetch Accounts api call
credBlock	Encrypted credblock containing user mpin	As returned by Common Library
remarks	Any transaction summary	50 characters alphanumeric with space and hyphen
currency	Currency code	String - INR
transactionType	Type of payment	P2M_PAY, P2P_PAY, INTENT_PAY or SCAN_PAY
transactionReference optional	Transaction reference id	String
refUrl optional	Reference url for the intent transaction	String
refCategory optional	Details for refUrl, whether it is 01 (Advertisement), 02(Invoice)	String
mcc optional	Merchant category code	String
initiationMode optional	Defines the initiation mode of the transaction	Initiation Modes
purpose	Defines the purpose code of the transaction	Purpose Codes
ifsc	Ifsc for the bank account as returned by NPCI	String
lrn	Lite Reference Number which is reference the number provided for the wallet linked with account number	String
timestamp	This is the timestamp in ISO format which was sent to CL for generating ARQC credblock. This timestamp should be passed as it is which was passed to CL	String
udfParameters optional	Stringified JSON for udf parameters	JSON string
packageName optional	Package name of the UPI application	String

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantRequestId	Merchant generated id for the transaction	As passed in the request
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
payerVpa	Customer vpa used for the payment	As passed in the request
payeeMcc	MCC for the payee	String
payeeMerchantCustomerId optional	Merchant generated unique id for customer who received the payment. Only if it is an onus P2P transaction.	String
payeeName optional	Name of the upi user who received the payment. Only if payment is done to a non A/C+IFSC vpa.	String
payeeVpa	Vpa of the upi user who received the payment	something@handle
refUrl	Reference url for the intent transaction	String
bankAccountUniqueId	Unique id for the selected bank account	As passed in the request
bankCode	Bank code of the account which was used	Valid bank IIN
maskedAccountNumber	Masked account number of the account which was used	XXXX123456
amount	Amount for the payment	As passed in the request
transactionType	Type of payment	As sent in request
transactionTimestamp	Timestamp of when the transaction was attempted	YYYY-MM-DDTHH:MM:SS+05:30
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayReferenceId	Reference id returned by the gateway	String
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
gatewayPayerResponseCode optional	Response code returned by gateway	String
gatewayPayeeResponseCode optional	Response code returned by gateway	String
gatewayPayerReversalResponseCode optional	Response code returned by gateway	String
gatewayPayeeReversalResponseCode optional	Response code returned by gateway	String
riskScore optional	RiskScore shared by NPCI or Bank	String
udfParameters optional	Udf parameters as passed in the request	JSON string
arpc	This comes from NPCI for all lite txns and it needs to be passed to CL	String

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Payment Success.
Z8	FAILURE	Per transaction limit exceeded as set by remitting member.
Z7	FAILURE	Transaction frequency limit exceeded as set by remitting member.
Else	FAILURE	Any other reason.

Additional Error Codes

responseCode	Meaning
DUPLICATE_REQUEST	Duplicate merchantRequestId or upiRequestId used for the transaction

[Draft] Lite Deregistration with Amount in Wallet

curl -L -X POST '{{host}}/api/n2/merchants/transactions/sendMoney'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "merchantRequestId": "redId1234",
  "payerVpa": "9416ef1d-72e8-4e6b-a38a-8003d765d3eb@axisuat1",
  "payeeVpa": "9416ef1d-72e8-4e6b-a38a-8003d765d3eb@axisuat1",
  "payeeName": "John Doe",
  "amount:" "2.00",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
  "credBlock": "{\"arqccred\":{\"type\":\"ARQC\",\"subType\":\"initial\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20160218\",\"hmac\":\"\",\"encryptedBase64String\":\"2.3.lite-v1.8|eyJhz...ovH7A==\",\"code\":\"NPCI-LITE\"}}}",
  "remarks": "UPI",
  "currency": "INR",
  "transactionType": "P2P_PAY",
  "transactionReference": "P1708071422508815250029",
  "refUrl": "https://www.abcxyz.com/",
  "purpose": "43",
  "ifsc" : "NREB0000001",
  "lrn" : "19216812200107001166427573769209547",
  "timestamp": "2023-03-04T10:46:27.872523+05:30",
  "udfParameters": "{}",
  "packageName": "in.amazon.mShop.android.shopping"

}'

# Response: HTTP 200 OK
{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload": {
        "merchantId": "TEST",
        "merchantChannelId": "TESTAPP",
        "merchantCustomerId": "test-merchantcustomer-1",
        "merchantRequestId": "redId1234",
        "customerMobileNumber": "919988776655",
        "payerVpa": "9416ef1d-72e8-4e6b-a38a-8003d765d3eb@axisuat1",
        "payeeMcc": "0000",
        "payeeMerchantCustomerId": "DEMO-CUST-5678",
        "payeeName": "John Doe",
        "payeeVpa": "9416ef1d-72e8-4e6b-a38a-8003d765d3eb@axisuat1",
        "refUrl": "https://www.abcxyz.com/",
        "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
        "bankCode": "123456",
        "maskedAccountNumber": "XXXX123456",
        "amount": "2.00",
        "transactionType": "P2P_PAY",
        "transactionTimestamp": "2023-03-04T10:46:27.872523+05:30",
        "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
        "gatewayReferenceId": "809323430413",
        "gatewayResponseStatus": "SUCCESS",
        "gatewayResponseCode": "00",
        "gatewayResponseMessage": "Your transaction is successful",
        "gatewayPayerResponseCode": "00",
        "gatewayPayeeResponseCode": "00",
        "gatewayPayerReversalResponseCode": "00",
        "gatewayPayeeReversalResponseCode": "00",
        "riskScore": "00000",
        "arpc": "2.3.lite-v1.8|eyJhbX...CUVKnxME=",

    },
    "udfParameters": "{\"payType\":\"P2P_PAY\"}"
}

This API will be used for Deregistration Wallet. In case of wallet has some amount of Money.

Note:

1. Value of Payer and Payee Vpa will be same.
2. timestamp should be passed by merchant which should be same which was given to CL.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
deviceFingerPrint	Device fingerprint of the customer	String
merchantRequestId	Merchant generated id for the transaction	35 characters alphanumeric
payerVpa	Vpa of customer adding money.	something@handle
payeeVpa	Vpa of customer adding money.	something@handle
payeeName optional	Name of the payee	String as returned in the Verify VPA API
amount	Amount for transaction	Numeric string with two decimals
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
bankAccountUniqueId	Unique id for the payer selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call
payeeBankAccountUniqueId optional	Unique id for the payee selected bank account for self transfer	bankAccountUniqueId in the response of Fetch Accounts api call
credBlock	Encrypted credblock containing arqccred	As returned by Common Library
remarks	Any transaction summary	50 characters alphanumeric with space and hyphen
currency	Currency code	String - INR
transactionType	Type of payment	P2P_PAY
transactionReference optional	Transaction reference id	String
refUrl optional	Reference url for the intent transaction	String
refCategory optional	Details for refUrl, whether it is 01 (Advertisement), 02(Invoice)	String
mcc optional	Merchant category code	String
initiationMode optional	Defines the initiation mode of the transaction	Initiation Modes
purpose	Defines the purpose code of the transaction	Purpose Codes
udfParameters optional	Stringified JSON for udf parameters	JSON string
packageName optional	Package name of the UPI application	String
ifsc	Ifsc for the bank account as returned by NPCI	String
lrn	Lite Reference Number which is reference the number provided for the wallet linked with account number	String
timestamp	This is the timestamp in ISO format which was sent to CL for generating ARQC credblock. This timestamp should be passed as it is which was passed to CL	String

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantRequestId	Merchant generated id for the transaction	As passed in the request
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
payerVpa	Customer vpa used for the payment	As passed in the request
payeeMcc	MCC for the payee	String
payeeMerchantCustomerId optional	Merchant generated unique id for customer who received the payment. Only if it is an onus P2P transaction.	String
payeeName optional	Name of the upi user who received the payment. Only if payment is done to a non A/C+IFSC vpa.	String
payeeVpa	Vpa of the upi user who received the payment	something@handle
refUrl	Reference url for the intent transaction	String
bankAccountUniqueId	Unique id for the selected bank account	As passed in the request
bankCode	Bank code of the account which was used	Valid bank IIN
maskedAccountNumber	Masked account number of the account which was used	XXXX123456
amount	Amount for the payment	As passed in the request
transactionType	Type of payment	As sent in request
transactionTimestamp	Timestamp of when the transaction was attempted	YYYY-MM-DDTHH:MM:SS+05:30
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayReferenceId	Reference id returned by the gateway	String
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
gatewayPayerResponseCode optional	Response code returned by gateway	String
gatewayPayeeResponseCode optional	Response code returned by gateway	String
gatewayPayerReversalResponseCode optional	Response code returned by gateway	String
gatewayPayeeReversalResponseCode optional	Response code returned by gateway	String
riskScore optional	RiskScore shared by NPCI or Bank	String
udfParameters optional	Udf parameters as passed in the request	JSON string
arpc	This comes from NPCI for all lite txns and it needs to be passed to CL	Sring

[Draft] LiteSync Request

curl -L -X POST '{{host}}/api/n2/merchants/transactions/litesync'
-H 'content-type: application/json' \
  'Accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "upiRequestId": "ICGfcbfed27c4be47ce892ac50",
  "lrn" : "19216812200107001166427573769209547",
  "merchantCustomerId" : "6376699547"
}'

# Response: HTTP 200 OK

{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload": {
        "gatewayResponseStatus": "SUCCESS",
        "gatewayResponseCode": "00"
        "gatewayResponseMessage": "Sync data fetched successfully",
        "lrn" : "19216812200107001166427573769209547"
        "arpc" : "2.3.lite-v1.8|eyJ...H7A=="
    }
}

This API will be used for making sync between CL and NPCI.

Request parameters

Parameter	Description	Values
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
lrn	Lite Reference Number which is reference the number provided for the wallet linked with account number	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseMessage	PSP response message for the API	Refer error code section
responseCode	PSP response code for the API	Refer error code section
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message returned by gateway	String
lrn	Lite Reference Number which is reference the number provided for the wallet linked with account number	String
arpc	encrypted state of the wallet which will be returned by npci auth engine	String

[Draft] Zero Balance Disablement

curl -L -X POST '{{host}}/api/n2/merchants/transactions/litesync'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "upiRequestId": "TXN64b11472f3254ddab25fb4e",
  "lrn" : "19216812200107001166427573769209547",
  "merchantCustomerId" : "2263743036",
  "purpose": "50"
}'

# Response: HTTP 200 OK
{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload": {
        "gatewayResponseStatus": "SUCCESS",
        "gatewayResponseCode": "00"
        "gatewayResponseMessage": "Account disabled successfully",
        "lrn": "19216812200107001166427573769209547",
        "arpc" : "2.3.lite-v1.8|eyJ...H7A=="
    }
}

This API will be used for Deregistration Wallet. In case of wallet balance is zero.

Request parameters

Parameter	Description	Constraints
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
lrn	Lite Reference Number which is reference the number provided for the wallet linked with account number	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
purpose	Defines the purpose code of the transaction	Purpose Codes

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseMessage	PSP response message for the API	Refer error code section
responseCode	PSP response code for the API	Refer error code section
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message returned by gateway	String
lrn	Lite Reference Number which is reference the number provided for the wallet linked with account number	String
arpc	encrypted state of the wallet which will be returned by npci auth engine	String

Aadhaar OTP APIs

Fetch Accounts

curl -L -X POST '{{host}}/api/{{uri}}/merchants/accounts/fetch' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "upiRequestId": "TXNef1a2908395239df56663244f8c7deaa",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "bankCode": "607153",
  "udfParameters": "",
  "aadhaarConsent": "True"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "919988776655",
    "gatewayTransactionId": "TXNef1a2908395239df56663244f8c7deaa",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Accounts fetched successfully",
    "accounts": [{
      "bankCode": "607153",
      "bankName": "BankName",
      "maskedAccountNumber": "XXXX8796",
      "mpinLength": "6",
      "mpinSet": "true",
      "otpLength": "6",
      "atmPinLength": "4",
      "type": "SAVINGS",
      "ifsc": "BankIFSC",
      "name": "Ram Singh",
      "aadhaarEnabled": "True",
      "isAadhaarNumberAvailable": "True",
      "bankAccountUniqueId":
      "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf"
    }],
    "vpaSuggestions": ["vpa@handle", "vpa2@handle"]
  },
  "udfParameters": ""
}

This api fetches customer accounts from NPCI. accounts will be present in the response only if gatewayResponseCode = "00". In case there are one or more accounts fetched, vpaSuggestions will be sent in response.

Note: In case merchant retires this api, the accounts will be fetched from NPCI again.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
deviceFingerPrint	Device fingerprint of the customer	String
bankCode	Bank code (IIN) of selected bank	String
udfParameters optional	Stringified JSON for udf parameters	JSON string
aadhaarConsent	Aadhaar Consent to fetch Customer Aadhaar Details	Boolean string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Mobile number of the customer	12 digits mobile number string
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
accounts optional	Bank accounts as returned by NPCI for the customer mobile number	Array of accounts
vpaSuggestions optional	Vpa suggestions for the bank accounts fetched	Array of strings
udfParameters optional	Udf parameters as passed in the request	JSON string
isAadhaarNumberAvailable optional	Customer Aadhaar number is received or not	Boolean string
aadhaarEnabled	Aadhaar Enabled or not	Boolean string

Generate OTP

curl -L -X POST '{{host}}/api/{{uri}}/merchants/accounts/otp' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "upiRequestId": "TXNef1a2908395239df56663244f8c7deaa",
  "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf",
  "customerVpa": "vpa@handle",
  "udfParameters": "{}",
  "otpRequestType": "BANK",
  "aadhaarNo": "123456"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "919988776655",
    "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
    "bankCode": "123456",
    "customerVpa": "vpa@handle",
    "maskedAccountNumber": "XXXX123456",
    "mobRegFormat": "FORMAT1",
    "mpinLength": "6",
    "otpLength": "6",
    "atmPinLength": "4",
    "gatewayTransactionId": "TXNef1a2908395239df56663244f8c7deaa",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "OTP generation successful"
  },
  "udfParameters": "{}"
}

This api can be used to generate an otp to be used for set/reset mpin process. Customer has to entre this otp in the Common Library page.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
deviceFingerPrint	Device fingerprint of the customer	String
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
bankAccountUniqueId	Unique id for the selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call.
customerVpa	VPA of the customer linked to the account	something@handle
udfParameters optional	Stringified JSON for udf parameters	JSON string
otpRequestType	Type of OTP request BANK, UIDAI, BANK-UIDAI	String
aadhaarNo optional	First 6 digits for customer aadhaar number	To be populated if otpRequestType = UIDAI

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
bankAccountUniqueId	Unique id for the selected bank account	As passed in the request
bankCode	Bank code of the account which was used	Valid bank IIN
customerVpa	Vpa of the customer linked to this account	As passed in the request
maskedAccountNumber	Masked account number of the account which was used	XXXX123456
mobRegFormat	Mobile registraion format type	FORMAT1, FORMAT2, FORMAT3
mpinLength	MPIN length for the account	String
otpLength	OTP length for the account	String
uidaiError optional	Error code populated by UIDAI incase of failure	400, 952
atmPinLength	ATM PIN length for the account used for FORMAT2 usecases	String
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
udfParameters optional	Udf parameters as passed in the request	JSON string

gatewayResponseCode	Description
00	Success.
ZT	Failure. OTP retry limit exceeded.
JPAW	Incorrect Aadhaar Number
JPAUB	User is blocked from using Aadhaar to SET/RESET MPIN.
JPAM	Validation timeout for Aadhaar Number. Please try again.
UD2	UIDAI FAILURE
Else	Failure. Any other reason.

Set/Reset MPIN

curl -L -X POST '{{host}}/api/{{uri}}/merchants/accounts/setMpin' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "upiRequestId": "TXNef1a2908395239df56663244f8c7deaa",
  "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf",
  "customerVpa": "vpa@handle",
  "credBlock": "{\"otpcred\":{\"type\":\"OTP\",\"subType\":\"SMS\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|IMQQwH6pcsw/cXNOWy...9gnNkA/o8CWGOQ==\",\"code\":\"NPCI\"}},
  \"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|qhRJ...d9Be7AQg2IFg==\",\"code\":\"NPCI\"}}",
  \"aadhaarcred\":{\"type\":\"OTP\",\"subType\":\"SMS\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|IMQQwH6pcsw/cXNOWy...9gnNkA/o8CWGOQ==\",\"code\":\"NPCI\"}}}",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "919988776655",
    "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
    "bankCode": "123456",
    "customerVpa": "vpa@handle",
    "maskedAccountNumber": "XXXX123456",
    "gatewayTransactionId": "TXNef1a2908395239df56663244f8c7deaa",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Set/Reset MPIN successful"
  },
  "udfParameters": "{}"
}

This api can be used to set/reset mpin for a customer bank account. Set/reset mpin is successful only when gatewayResponseCode = "00".

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
deviceFingerPrint	Device fingerprint of the customer	String
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
bankAccountUniqueId	Unique id for the selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call.
customerVpa	VPA of the customer linked to the account	something@handle
credBlock	Encrypted credblock for containing user otp and mpin	As returned by Common Library
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
bankAccountUniqueId	Unique id for the selected bank account	As passed in the request
bankCode	Bank code of the account which was used	Valid bank IIN
customerVpa	Vpa of the customer linked to this account	As passed in the request
maskedAccountNumber	Masked account number of the account which was used	XXXX123456
gatewayTransactionId	Transaction id returned by gateway	String
uidaiError optional	Error code populated by UIDAI incase of failure	400, 952
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
udfParameters optional	Udf parameters as passed in the request	JSON string

gatewayResponseCode	Description
00	Success.
XN	Failure. No Card Record found.
XL	Failure. Expired Card Details.
ZR	Failure. Invalid / Incorrect OTP.
UD2	UIDAI FAILURE
ZS	Failure. OTP Time expired.
G74	Incorrect mobile registration format used.
Else	Failure. Any other reason.

UPI CC APIs

Fetch Accounts

# Sample Request Response for fetching Credit Card account

curl -L -X POST '{{host}}/api/n2/merchants/accounts/fetch' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "bankCode": "175001",
  "udfParameters": "{}",
  "accountType": "CREDIT",
  "packageName" : "in.amazon.mShop.android.shopping"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "919988776655",
    "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Accounts fetched successfully",
    "accounts": [{
      "maskedAccountNumber": "652925XXXXXXXX03",
      "otpLength": "6",
      "mpinSet": "true",
      "atmPinLength": "4",
      "name": "Venkat",
      "ifsc": "TESTCC0000001",
      "type": "CREDIT",
      "bankCode": "175001",
      "mpinLength": "4",
      "bankAccountUniqueId": "4a47411cad6f6acb4c31cad3fe3c32b935288314b4916f4da5c6ed53a781c534",
      "bankName": "TEST Bank Credit Card"
    }],
    "vpaSuggestions": ["vpa@handle", "vpa2@handle"]
  },
  "udfParameters": "{}"
}

This api fetches customer accounts from NPCI. accounts will be present in the response only if gatewayResponseCode = "00". In case there are one or more accounts fetched, vpaSuggestions will be sent in response.

IN CASE OF CREDIT CARD pass one extra parameter accountType with value CREDIT in Input.

ATM PIN length for the credit card account used for FORMAT2 usecases.

For credit card account maskedAccountNumber represents Masked Credit Card number with first 6 digits and last 2 digits unmasked.

IN CASE OF CREDIT CARD only the bankCodes of banks which have version no = '2.99' in listBanks api response, supports credit cards in UPI ecosystem.

Note: In case merchant retries this api, the accounts will be fetched from NPCI again.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
deviceFingerPrint	Device fingerprint of the customer	String
bankCode	Bank code (IIN) of selected bank	String
udfParameters optional	Stringified JSON for udf parameters	JSON string
accountType optional	Account Type(In CC TPAP should send accountType as CREDIT, in other cases they can skip sending this field)	String
packageName optional	Package name of the UPI application	String

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Mobile number of the customer	12 digits mobile number string
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
accounts optional	Bank accounts as returned by NPCI for the customer mobile number	Array of accounts
vpaSuggestions optional	Vpa suggestions for the bank accounts fetched	Array of strings
udfParameters optional	Udf parameters as passed in the request	JSON string

Check Balance

curl -L -X POST '{{host}}/api/{{uri}}/merchants/accounts/balance' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "upiRequestId": "TXNef1a2908395239df56663244f8c7deaa",
  "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf",
  "customerVpa": "vpa@handle",
  "credBlock": "{\"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|j+dtxs...1ca1o0CrjnUw==\",\"code\":\"NPCI\"}}}",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "919988776655",
    "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
    "bankCode": "123456",
    "customerVpa": "vpa@handle",
    "maskedAccountNumber": "XXXX123456",
    "balance": "123.00",
    "gatewayTransactionId": "TXNef1a2908395239df56663244f8c7deaa",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Check balance successful",
    "outstandingAmount": "200.00"
  },
  "udfParameters": "{}"
}

This api can be used to get the balance for a customer bank account. balance is sent in response only when gatewayResponseCode = "00".

Note: IN CASE OF CREDIT CARD one extra pair will come in response outstandingAmount

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
deviceFingerPrint	Device fingerprint of the customer	String
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
bankAccountUniqueId	Unique id for the selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call.
customerVpa	VPA of the customer linked to the account	something@handle
credBlock	Encrypted credblock containing user mpin	As returned by Common Library
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
bankAccountUniqueId	Unique id for the selected bank account	As passed in the request
bankCode	Bank code of the account which was used	Valid bank IIN
customerVpa	Vpa of the customer linked to this account	As passed in the request
maskedAccountNumber	Masked account number of the account which was used	XXXX123456
balance optional	Balance of the bank account used	1234.00
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
udfParameters optional	Udf parameters as passed in the request	JSON string
outstandingAmount optional	Used amount out of the available credit limit in case of a CREDIT or OD account	String

Check EMI [DRAFT]

# 1.Check EMI to get eligible EMI list

curl -L -X POST '{{host}}/api/{{uri}}/merchants/creditCard/checkEmi' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "upiRequestId": "TXNef1a2908395239df56663244f8c7deaa",
  "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf",
  "payerVpa": "vpa@handle",
  "payeeVpa": "vpa1@handle",
  "emiTxnType": "POST",
  "originalTxnUpiRequestId": "TXNef1a2908395239df56663244f8c7deed",
  "originalTxnAmt": "10000.00",
  "originalTxnTs": "2023-10-07T17:57:49+05:30",
  "mcc": "6540",
  "remarks": "This is remarks",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "gatewayTransactionId": "TXNef1a2908395239df56663244f8c7deaa",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Your Check EMI call is successful.",
    "termsConditions": "www.termsConditions/emi/2",
    "emiOfferList":[{
      "seqNum": "1",
      "offerId": "Abcef1a2908395239df56663244f8c7deed",
      "tenure": "6",
      "amount": "1866.66",
      "intRatePct": "12",
      "intRateAmt": "1200.00",
      "totalAmt": "11100",
      "discountAmt": "200",
      "procFee": "100",
    },
    {
      "seqNum": "2",
      "offerId": "Abcef1a2908395239df56663244f8c7deef",
      "tenure": "10",
      "amount": "1100.00",
      "intRatePct": "10",
      "intRateAmt": "1000.00",
      "totalAmt": "10850",
      "discountAmt": "200",
      "procFee": "50",
    }],

  },
  "udfParameters": "{}"
}

# 2.Check EMI to Foreclose an EMI.

curl -L -X POST '{{host}}/api/{{uri}}/merchants/creditCard/checkEmi' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "upiRequestId": "TXNef1a2908395239df56663244f8c7deaa",
  "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf",
  "payerVpa": "vpa@handle",
  "payeeVpa": "vpa1@handle",
  "emiTxnType": "FORECLOSE",
  "originalTxnUpiRequestId": "TXNef1a2908395239df56663244f8c7deed", // This TxnId should be of Select EMI call
  "originalTxnAmt": "10000.00",
  "originalTxnTs": "2023-10-07T17:57:49+05:30",
  "mcc": "6540",
  "foreCloseEmiId": "Ahask1a2908395239df56663244f8c7deef",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "gatewayTransactionId": "TXNef1a2908395239df56663244f8c7deaa",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Your Check EMI call is successful.",
    "termsConditions": "www.termsConditions/emi/2",
    "forecloseDetails": {
        "forecloseAmt": "100.00",
        "penaltyAmt": "1000.00",
        "principalAmt": "10000.00",
        "intRatePct": "10.00"
    }
  },
  "udfParameters": "{}"
}

This api can be used to

1.Get the EMI offers as shared by Issuer bank

2.Get foreclose details for a converted EMI

Note: Only the bankCodes of Issuing banks which have version no = '2.14' in listBanks api response, supports credit card EMI in UPI ecosystem.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
deviceFingerPrint	Device fingerprint of the customer	String
fallbackDeviceFingerPrint optional	Fallback Device fingerprint of the customer	String
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
bankAccountUniqueId	Unique id for the selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call.
payerVpa	Vpa of the customer/payer to be used for emi conversion payment	something@handle
payeeVpa	Vpa of the payee to whom money is being sent for emi conversion payment	something@handle
emiTxnType	EMI transaction Conversion types	ENUM String [DURING,POST,FORECLOSE]
originalTxnUpiRequestId	In case of POST: upiRequestId of the fin txn which is to be converted to EMI, FORECLOSE: upiRequestId of the SELECT call through which fin txn was converted to EMI	35 character alphanumeric. Required when emiTxnTypein [POST,FORECLOSE]
originalTxnAmt	Amount of the original transaction which is to be converted to EMI	String
originalTxnTs conditional	Timestamp of the original transaction	String (YYYY-MM-DDTHH:MM:SS+05:30). Required when emiTxnType= POST
mcc	Merchant Category Code for the merchant whose VPA is passed in payeeVpa	String
remarks optional	Any transaction summary	Max 50 characters alphanumeric with space and hyphen
forecloseEmiId conditional	emiId of the converted EMI that is to be foreclosed	String . Required when emiTxnType= FORECLOSE
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
termsConditions	The terms and conditions passed by the Issuer for EMI conversion and foreclosure	String
emiLimitAmount optional	The amount above which credit card issuer is allowing the financial transactions to be converted into EMI	String
emiOfferList conditional	List of eligible EMIs for a txn	Array of JSON . emiTxnType in [DURING,POST]
seqNum	Indexing for each EMI offer in the list	Integer String
offerId	The unique identifier for an EMI offer. It is dynamically computed and changes for every txn for every user	35 character alphanumeric.
tenure	Tenure is the validity of an EMI and will contain the number of months	Numeric String
amount	Emi amount for the Month = [(principal-amt + int-rate-amt) / tenure]	Numeric String
intRatePct	Interest rate for the complete EMI	Numeric String
intRateAmt	Total Interest amount to be paid for the complete EMI = [int-rate-pct% of principal-amt]	Numeric String
totalAmt	Total Amount to be paid for the complete EMI = [(amount * tenure) - discount-amt + proc-fee]	Numeric String
discountAmt	Discount amount for the complete EMI	Numeric String
procFee	Processing fee for the complete EMI	Numeric String
forecloseDetails conditional	List of eligible EMIs for a txn	Array of JSON . emiTxnType = FORECLOSE
forecloseAmt	Foreclose amount	Numeric String
penalityAmt	Penalty amount	Numeric String
principalAmt	Principal amount	Numeric String
intRatePct	Interest rate (in flat value)	Numeric String
udfParameters optional	Udf parameters as passed in the request	JSON string

Select EMI [DRAFT]

# 1.Select EMI to apply an EMI.

curl -L -X POST '{{host}}/api/{{uri}}/merchants/creditCard/selectEmi' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "upiRequestId": "TXNef1a2908395239df56663244f8c7deab",
  "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf",
  "payerVpa": "vpa@handle",
  "payeeVpa": "vpa1@handle",
  "emiTxnType": "POST",
  "originalTxnUpiRequestId": "TXNef1a2908395239df56663244f8c7deed",
  "originalTxnAmount": "10000.00",
  "originalTxnTs": "2023-10-07T17:57:49+05:30",
  "credBlock": "{\"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|j+dtxs...1ca1o0CrjnUw==\",\"code\":\"NPCI\"}}}",
  "userConsent":"Y",
  "mcc": "6540",
  "emiData":{
      "seqNum": "2",
      "offerId": "Abcef1a2908395239df56663244f8c7deef",
      "tenure": "10",
      "amount": "1100.00",
      "intRatePct": "10",
      "intRateAmt": "1000.00",
      "totalAmt": "10850",
      "discountAmt": "200",
      "procFee": "50",
    }
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload":{
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "gatewayTransactionId": "TXNef1a2908395239df56663244f8c7deab",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Your EMI operation is successfully applied.",
    "emiId": "Ahask1a2908395239df56663244f8c7deef"
  },
  "udfParameters": "{}"
}



# 2.SELECT EMI to Foreclose an EMI.

curl -L -X POST '{{host}}/api/{{uri}}/merchants/creditCard/selectEmi' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "upiRequestId": "TXNef1a2908395239df56663244f8c7deaa",
  "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf",
  "payerVpa": "vpa@handle",
  "payeeVpa": "vpa1@handle",
  "emiTxnType": "FORECLOSE",
  "originalTxnUpiRequestId": "TXNef1a2908395239df56663244f8c7deed",
  "originalTxnAmount": "10000.00",
  "mcc": "6540",
  "credBlock": "{\"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|j+dtxs...1ca1o0CrjnUw==\",\"code\":\"NPCI\"}}}",
  "userConsent":"Y",
  "forecloseDetails": {
        "emiId": "Ahask1a2908395239df56663244f8c7deef",
        "forecloseAmt": "100.00",
        "penaltyAmt": "1000.00",
        "principalAmt": "10000.00",
        "intRatePct": "10.00"
    }
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "gatewayTransactionId": "TXNef1a2908395239df56663244f8c7deaa",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Your EMI operation is successfully applied.",
    "emiId": "Ahask1a2908395239df56663244f8c7deef",
  },
  "udfParameters": "{}"
}

This api can be used to

1.Apply an EMI offer to a financial transaction

2.Foreclose a converted EMI

Note: Only the bankCodes of Issuing banks which have version no = '2.14' in listBanks api response, supports credit card EMI in UPI ecosystem.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
deviceFingerPrint	Device fingerprint of the customer	String
fallbackDeviceFingerPrint optional	Fallback Device fingerprint of the customer	String
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
bankAccountUniqueId	Unique id for the selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call.
payerVpa	Vpa of the customer/payer to be used for emi conversion payment	something@handle
payeeVpa	Vpa of the payee to whom money is being sent for emi conversion payment	something@handle
credBlock conditional	Encrypted credblock containing user mpin	As returned by Common Library . Required when emiTxnTypein [POST,FORECLOSE]
emiTxnType	EMI transaction Conversion types	ENUM String [DURING,POST,FORECLOSE]
originalTxnUpiRequestId	In case of DURING/POST: upiRequestId of the fin txn which is to be converted to EMI, FORECLOSE: upiRequestId of the SELECT call through which fin txn was converted to EMI	35 character alphanumeric.
originalTxnAmt	Amount of the original transaction which is to be converted to EMI	String
originalTxnTs conditional	Timestamp of the original transaction	String (YYYY-MM-DDTHH:MM:SS+05:30). Required when emiTxnType= POST
checkEmiUpiRequestId conditional	upiRequestId of EMI CHECK api call	35 character alphanumeric. Required when emiTxnType!= DURING(Brand Funded scenario)
mcc	Merchant Category Code for the merchant whose VPA is passed in payeeVpa	String
userConsent	User consent to convert a fin txn to EMI or foreclose a converted EMI	ENUM String [Y,N]
emiData conditional	Stringified JSON of EMI Details	JSON String. Required when emiTxnType in [DURING,POST]
seqNum	seqNum of the desired EMI offer(as received in the response of corresponding CHECK request)	Integer String
offerId	offerId of the desired EMI offer (as received in the response of corresponding CHECK request)	35 character alphanumeric.
tenure	tenure of the desired EMI offer (as received in the response of corresponding CHECK request)	Integer String
amount	amount of the desired EMI offer (as received in the response of corresponding CHECK request)	Numeric String
intRatePct	intRatePct of the desired EMI offer (as received in the response of corresponding CHECK request)	Numeric String
intRateAmt	intRateAmt of the desired EMI offer (as received in the response of corresponding CHECK request)	Numeric String
totalAmt	totalAmt of the desired EMI offer (as received in the response of corresponding CHECK request)	Numeric String
discountAmt	discountAmt of the desired EMI offer (as received in the response of corresponding CHECK request)	SNumeric tring
procFee	procFee of the desired EMI offer (as received in the response of corresponding CHECK request)	Numeric String
imei conditional	imei of the desired EMI offer	String. Required when emiTxnType= DURING(Brand Funded scenario)
forecloseDetails conditional	Stringified JSON of Foreclose Details	JSON String. Required when emiTxnType= FORECLOSE
emiId	emiId of the converted EMI that is to be foreclosed	String
forecloseAmt	forecloseAmt as received in the response of corresponding CHECK request	Numeric String
penaltyAmt	penaltyAmt as received in the response of corresponding CHECK request	Numeric String
principalAmt	principalAmt as received in the response of corresponding CHECK request	Numeric String
remarks optional	Any transaction summary	Max 50 characters alphanumeric with space and hyphen
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
emiId	Unique identifier of the converted EMI	String
udfParameters optional	Udf parameters as passed in the request	JSON string

EMI Status [DRAFT]

curl -L -X POST '{{host}}/api/{{uri}}/merchants/creditCard/emiStatus' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "upiRequestId": "TXNef1a2908395239df56663244f8c7dech",
  "selectEmiUpiRequestId": "TXNef1a2908395239df56663244f8c7deab",
  "originalTxnTs": "2023-10-07T17:57:49+05:30"
  "remarks": "EMI status check",
  "purpose": "00",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload":{
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "gatewayTransactionId": "TXNef1a2908395239df56663244f8c7dech",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Your EMI operation is successfully applied.",
    "emiId": "Ahask1a2908395239df56663244f8c7deef"
  },
  "udfParameters": "{}"
}

This api can be used to check the status of EMI.

Note: Only the bankCodes of Issuing banks which have version no = '2.14' in listBanks api response, supports credit card EMI in UPI ecosystem.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
originalTxnTs	Timestamp of the original transaction	String (YYYY-MM-DDTHH:MM:SS+05:30).
selectEmiUpiRequestId	upiRequestId of SELECT EMI api call	35 character alphanumeric.
remarks optional	Any transaction summary	Max 50 characters alphanumeric with space and hyphen
purpose optional	Defines the purpose code of the transaction	Refer Request Structure section
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
emiId	Unique identifier of the converted EMI	String
udfParameters optional	Udf parameters as passed in the request	JSON string

Send Money [EMI Financial Transaction]

# SendMoney call for During EMI TXN
curl -L -X POST '{{host}}/api/n2/merchants/transactions/sendMoney'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-sub-merchant-id': 'SUBMERCHANT', \
  'x-sub-merchant-channel-id': 'SUBMERCHANTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "merchantRequestId": "redId1234",
  "payerVpa": "customer@handle",
  "payeeVpa": "payee@xyz",
  "payeeName": "John Doe",
  "amount:" "2.00",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
  "credBlock": "{\"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|j+dtxs...1ca1o0CrjnUw==\",\"code\":\"NPCI\"}}}",
  "remarks": "Payment for order",
  "currency": "INR",
  "transactionType": "INTENT_PAY",
  "transactionReference": "P1708071422508815250029",
  "refUrl": "https://www.abcxyz.com/",
  "refCategory": "02",
  "mcc": "6549",
  "initiationMode": "00",
  "purpose": "72",
  "udfParameters": "{}",
  "packageName": "in.amazon.mShop.android.shopping"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "merchantRequestId": "redId1234",
    "customerMobileNumber": "919988776655",
    "payerVpa": "customervpa@bank",
    "payeeMcc": "0000",
    "payeeMerchantCustomerId": "DEMO-CUST-5678",
    "payeeName": "John Doe",
    "payeeVpa": "payee@xyz",
    "refUrl": "https://www.abcxyz.com/",
    "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
    "bankCode": "123456",
    "maskedAccountNumber": "XXXX123456",
    "amount": "2.00",
    "transactionType": "INTENT_PAY",
    "transactionTimestamp": "2017-06-09T17:57:49+05:30",
    "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
    "gatewayReferenceId": "809323430413",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Your transaction is successful",
    "gatewayPayerResponseCode": "00",
    "gatewayPayeeResponseCode": "00",
    "gatewayPayerReversalResponseCode": "00",
    "gatewayPayeeReversalResponseCode": "00",
    "riskScore": "00000"
  },
  "udfParameters": "{}"
}

This api will be used for completing all P2P and P2M Payment scenarios. This includes

• Incoming Intent Payment
• Scan and Pay (UPI QR & Bharat QR)
• P2P Pay (Vpa & Account+IFSC)
• Payment to PSP merchant
• Self Pay

The api can be invoked to process different types of payments. The transactionType key of request is used to identify the type of payment. Possible values are P2M_PAY, P2P_PAY, SELF_PAY, INTENT_PAY and SCAN_PAY. Depending on the payment type, some additional parameters need to be passed.

P2M_PAY is to be used for payment to a PSP merchant only. The payeeVpa should be a valid PSP generated vpa for the merchant.

INTENT_PAY and SCAN_PAY are used for the intent and qr scan transactions. Both UPI QR and Bharat QR codes are supported.

Note

1. For DURING type EMI transaction, purposeCode must be 72. Everything else is same as normal send money call.
2. For Request and Response Body Parameters, refer Send Money

Fetch Bill [DRAFT]

# 1.Fetching CC Bill for self.

curl -L -X POST '{{host}}/api/{{uri}}/merchants/creditCard/fetchBill' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "upiRequestId": "TXNef1a2908395239df56663244f8c7deaa",
  "isCCAccLinked":"True",
  "creditAccDetails":{
     "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf"
     },
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Your Fetch bill call is successful.",
    "billDetails":{
     "_regName" : "CustomerName",
     "_dueDate" : "29112023",
     "_billDate" : "15112023",
     "_minAmt" : "300.00",
     "_totalAmt" : "3000.00",
     "_latePaymentFee" : "200.00",
     "_interestRate" : "10",
     "_billingPeriod" : "15102023/15112023",
    },
    "udfParameters": "{}"
    }
}

# 2.Fetching CC Bill for others.

curl -L -X POST '{{host}}/api/{{uri}}/merchants/creditCard/fetchBill' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "upiRequestId": "TXNef1a2908395239df56663244f8c7deaa",
  "isCCAccLinked":"False",
  "creditAccDetails":{
     "bankCode": "500003",
     "linkedMobileNumber":"9123456780",
     "cardDigits":"1234",
     },
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Your Fetch bill call is successful.",
    "billDetails":{
     "_regName" : "CustomerName",
     "_dueDate" : "29112023",
     "_billDate" : "15112023",
     "_minAmt" : "300.00",
     "_totalAmt" : "3000.00",
     "_latePaymentFee" : "200.00",
     "_interestRate" : "10",
     "_billingPeriod" : "15102023/15112023",
    },
    "udfParameters": "{}"
    }
}

This API can be used to fetch the credit card bill for self and others

Note: Only the bankCodes of Issuing banks which have version no = '2.13' in listBanks api response, supports credit card bill generation and payment in UPI ecosystem.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
deviceFingerPrint	Device fingerprint of the customer	String
fallbackDeviceFingerPrint optional	Fallback Device fingerprint of the customer	String
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
isCCAccLinked	Flag to denote if the credit account for which the bill is being fetched has an active VPA created with the PSP	Boolean string
crediAccDetails	Credit Card Account details	JSON string .
bankAccountUniqueId conditional	Unique id for the selected bank account with type = CREDIT	bankAccountUniqueId in the response of Fetch Accounts api call. Required when isCCAccLinked = True
bankCode conditional	Bank code (IIN) of selected bank	String. Required when isCCAccLinked = False
cardDigits conditional	Last 4 digits of the credit card	Numeric String . Required when isCCAccLinked = False
linkedMobileNumber	Mobile number linked to the credit card	12 digits mobile number string. Required when isCCAccLinked = False
udfParameters optional	Stringified JSON for udf parameters	JSON string
iat optional	timestamp to be used in JWS	As passed in the request body

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
billDeatils	Credit card bill details	JSON string
regName	Cardholder’s name	String
dueDate	Due date for payment of CC bill	ISO Date format - DDMMYYYY
billDate	Billing date of CC bill as per cycle	ISO Date format - DDMMYYYY
minAmt	Minimum payable amount for CC bill	Numeric string
totalAmt	Total payable amount for CC bill	Numeric string
latePaymentFee	Late payment fee	Numeric string
interestRate	Interest rate	Numeric string
billingPeriod	Billing period	2 Dates in string format separated by / Format - DDMMYYYY/DDMMYYYY
udfParameters optional	Udf parameters as passed in the request	JSON string

Send Money [CC Bill Payment Transaction]

# SendMoney call for credit card bill payment
curl -L -X POST '{{host}}/api/n2/merchants/transactions/sendMoney'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-sub-merchant-id': 'SUBMERCHANT', \
  'x-sub-merchant-channel-id': 'SUBMERCHANTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "merchantRequestId": "redId1234",
  "payerVpa": "customer@handle",
  "payeeVpa": "CC.<mobilenumber>@bankhandle",
  "payeeName": "John Doe",
  "amount:" "2.00",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
  "credBlock": "{\"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|j+dtxs...1ca1o0CrjnUw==\",\"code\":\"NPCI\"}}}",
  "remarks": "CC Bill payment",
  "currency": "INR",
  "transactionType": "P2P_PAY",
  "transactionReference": "1234",
  "refUrl": "https://www.abcxyz.com/",
  "refCategory": "02",
  "initiationMode": "26",
  "udfParameters": "{}",
  "packageName": "in.amazon.mShop.android.shopping"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "merchantRequestId": "redId1234",
    "customerMobileNumber": "919988776655",
    "payerVpa": "customervpa@bank",
    "payeeMcc": "0000",
    "payeeMerchantCustomerId": "DEMO-CUST-5678",
    "payeeName": "John Doe",
    "payeeVpa": "payee@xyz",
    "refUrl": "https://www.abcxyz.com/",
    "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
    "bankCode": "123456",
    "maskedAccountNumber": "XXXX123456",
    "amount": "2.00",
    "transactionType": "INTENT_PAY",
    "transactionTimestamp": "2017-06-09T17:57:49+05:30",
    "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
    "gatewayReferenceId": "809323430413",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Your transaction is successful",
    "gatewayPayerResponseCode": "00",
    "gatewayPayeeResponseCode": "00",
    "gatewayPayerReversalResponseCode": "00",
    "gatewayPayeeReversalResponseCode": "00",
    "riskScore": "00000"
  },
  "udfParameters": "{}"
}

This api will be used for completing all P2P and P2M Payment scenarios. This includes

• Incoming Intent Payment
• Scan and Pay (UPI QR & Bharat QR)
• P2P Pay (Vpa & Account+IFSC)
• Payment to PSP merchant
• Self Pay

The api can be invoked to process different types of payments. The transactionType key of request is used to identify the type of payment. Possible values are P2M_PAY, P2P_PAY, SELF_PAY, INTENT_PAY and SCAN_PAY. Depending on the payment type, some additional parameters need to be passed.

P2M_PAY is to be used for payment to a PSP merchant only. The payeeVpa should be a valid PSP generated vpa for the merchant.

INTENT_PAY and SCAN_PAY are used for the intent and qr scan transactions. Both UPI QR and Bharat QR codes are supported.

Note

1. For CC bill payment transaction, initiationMode must be 25(SELF case) or 26(OTHERS case).
2. If initiationMode is 25, then transactionReference should contain linked credit card bankAccountUniqueId .If initiationMode is 26, then transactionReference should contain last 4 digits of the credit card.
3. payeeVpa should be in the format of CC.<mobilenumber>@bankhandle.
4. Everything else is same as normal send money call. For Request and Response Body Parameters, refer Send Money

Create Mandate for CC Bill AutoPay

# Sample request

curl -X POST
-H "Content-Type: application/json"
-H 'x-merchant-channel-id: TESTAPP'
-H 'x-merchant-signature: 823647862547652376452378456'
-H 'x-merchant-id: TEST'
-H 'x-timestamp: 1496918882000'
-d '{
  "amount": "100.0",
  "amountRule": "MAX",
  "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
  "blockFund": "true",
  "credBlock": "{\"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|j+dtxs...1ca1o0CrjnUw==\",\"code\":\"NPCI\"}}}",
  "currency": "INR",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "expiry": "10",
  "initiatedBy": "PAYER",
  "makeAsync": "true",
  "mandateName": "Sample Name",
  "mcc": "0000",
  "merchantCustomerId": "JUS14081",
  "merchantRequestId": "b1a4418b4ac",
  "payeeVpa": "CC.<mobilenumber>@bankhandle",
  "payerRevocable": "true",
  "payerVpa": "xyz@test",
  "recipientName": "abcdefg",
  "recurrencePattern": "WEEKLY",
  "recurrenceRule": "BEFORE",
  "recurrenceValue": "2",
  "refUrl": "https://www.refUrl.com",
  "remarks": "MAD",
  "shareToPayee": "true",
  "transactionType": "UPI_MANDATE",
  "udfParameters": "{}",
  "upiRequestId": "APLMe5c9711f1ede1f5524e2fadb48003aa0",
  "validityEnd": "2019/09/20",
  "validityStart": "2019/09/08",
  "refCategory": "02",
  "transactionReference": "1234",
  "purpose": "00",
  "initiationMode": "26",
  "packageName" : "in.amazon.mShop.android.shopping"
}' "{{host}}/api/n2/merchants/mandates/create"

# The above command returns JSON structured like this:

{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "amount": "100.00",
    "amountRule": "MAX",
    "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
    "blockFund": "true",
    "currency": "INR"
    "expiry": "2020-12-24T14:17:06+05:30",
    "gatewayMandateId": "APLMe5c9711f1ede1f5524e2fadb48003aa0",
    "gatewayReferenceId": "806115044725",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Your transaction is successful",
    "gatewayResponseStatus": "SUCCESS",
    "initiatedBy": "PAYER",
    "makeAsync": "true",
    "mandateApprovalTimestamp" : "2017-06-09T17:58:49+05:30",
    "mandateName": "Sample Name",
    "mcc": "0000",
    "mandateTimestamp": "2018-12-24T14:17:06+05:30",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "DEMO-CUST-1234",
    "merchantId": "TEST",
    "merchantRequestId": "b1a4418b4ac",
    "orgMandateId": "APLMe5c9711f1ede1f5524e2f92648y03aa0"
    "payeeMcc": "4121",
    "payeeName": "APLTEST",
    "payeeVpa": "CC.<mobilenumber>@bankhandle",
    "payerName": "ABC",
    "payerRevocable": "true",
    "payerVpa": "xyz@test",
    "recurrencePattern": "WEEKLY",
    "recurrenceRule": "BEFORE",
    "recurrenceValue": "2",
    "refUrl": "https://www.refUrl.com",
    "remarks": "MAD",
    "role": "PAYER",
    "shareToPayee": "true",
    "transactionType": "UPI_MANDATE",
    "umn": "uniqueMandateNumber@test",
    "validityEnd": "2019/09/20",
    "validityStart": "2019/09/08",
    "refCategory": "02",
    "transactionReference": "1234",
    "purpose": "00",
    "initiationMode": "26",
  },
  "udfParameters":"{}"
}

This API hits TSP Server with a timeout of 60 seconds.

This api will be used for creation of a mandate for cc bill payment . For this scenario payer creates the madate.

Note

1. For CC bill autopay mandate creation, initiationMode must be 25(SELF case) or 26(OTHERS case).
2. If initiationMode is 25, then transactionReference should contain linked credit card bankAccountUniqueId .If initiationMode is 26, then transactionReference should contain last 4 digits of the credit card.
3. payeeVpa should be in the format of CC.<mobilenumber>@bankhandle.
4. remarks must be MAD or TotalAmount. MAD used to create auto-pay for Minimum Amount Due.TotalAmount used to create auto-pay for full bill amount.
5. amountRule must be MAX.
6. Everything else is same as normal create mandate call .For Request and Response Body Parameters, refer Create Mandate

UPI Credit Line APIs

Fetch Accounts

curl -L -X POST '{{host}}/api/{{uri}}/merchants/accounts/fetch' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "upiRequestId": "TXNef1a2908395239df56663244f8c7deaa",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "bankCode": "607153",
  "udfParameters": "",
  "accountType": "UPICREDIT"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "919988776655",
    "gatewayTransactionId": "TXNef1a2908395239df56663244f8c7deaa",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Accounts fetched successfully",
    "accounts": [{
      "bankCode": "607153",
      "bankName": "BankName",
      "maskedAccountNumber": "XXXX8796",
      "mpinLength": "6",
      "mpinSet": "true",
      "otpLength": "6",
      "atmPinLength": "4",
      "type": "CREDITLINE",
      "accSubType": "CD",
      "allowedMCC": ["5541", "5411", "5311", "5944"],
      "notallowedMCC": ["0000", "5413"],
      "ifsc": "BankIFSC",
      "name": "Ram Singh",
      "bankAccountUniqueId":
      "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf"
    }],
    "vpaSuggestions": ["vpa@handle", "vpa2@handle"]
  },
  "udfParameters": ""
}

This api fetches customer accounts from NPCI. accounts will be present in the response only if gatewayResponseCode = "00". In case there are one or more accounts fetched, vpaSuggestions will be sent in response.

IN CASE OF CREDIT LINE only the bankCodes of banks which have version no = '2.15' in listBanks api response, supports credit cards in UPI ecosystem.

Note: In case merchant retires this api, the accounts will be fetched from NPCI again.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
deviceFingerPrint	Device fingerprint of the customer	String
bankCode	Bank code (IIN) of selected bank	String
udfParameters optional	Stringified JSON for udf parameters	JSON string
accountType	For Credit line, account-type will be UPICREDIT	String

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Mobile number of the customer	12 digits mobile number string
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
type	For the Credit line, accType can be "CREDITLINE"/"CREDITLINE01"/"CL01" etc	String
accSubType optional	Account subtype indicates the sub type/purpose of credit account i.e. Name of the Credit line product defined by Issuing bank Ex: "CD" or "PL"	String
allowedMCC optional	Allowed MCC is the list of MCC against which the UPICREDIT account can be used to make txns. Ex:["5541", "5411", "5311", "5944"]	Array of strings
notallowedMCC optional	Not allowed MCC is the list of MCC against which the UPICREDIT account cant be used to make txns. Ex: ["0000", "5413"]	Array of strings
accounts optional	Bank accounts as returned by NPCI for the customer mobile number	Array of accounts
vpaSuggestions optional	Vpa suggestions for the bank accounts fetched	Array of strings
udfParameters optional	Udf parameters as passed in the request	JSON string

Check Balance

curl -L -X POST '{{host}}/api/{{uri}}/merchants/accounts/balance' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "upiRequestId": "TXNef1a2908395239df56663244f8c7deaa",
  "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf",
  "customerVpa": "vpa@handle",
  "credBlock": "{\"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|j+dtxs...1ca1o0CrjnUw==\",\"code\":\"NPCI\"}}}",
  "udfParameters": "{}"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "919988776655",
    "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
    "bankCode": "123456",
    "customerVpa": "vpa@handle",
    "maskedAccountNumber": "XXXX123456",
    "balance": "123.00",
    "gatewayTransactionId": "TXNef1a2908395239df56663244f8c7deaa",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Check balance successful",
    "outstandingAmount": "200.00"
  },
  "udfParameters": "{}"
}

This api can be used to get the balance for a customer bank account. balance is sent in response only when gatewayResponseCode = "00".

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
deviceFingerPrint	Device fingerprint of the customer	String
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
bankAccountUniqueId	Unique id for the selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call.
customerVpa	VPA of the customer linked to the account	something@handle
credBlock	Encrypted credblock containing user mpin	As returned by Common Library
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
bankAccountUniqueId	Unique id for the selected bank account	As passed in the request
bankCode	Bank code of the account which was used	Valid bank IIN
customerVpa	Vpa of the customer linked to this account	As passed in the request
maskedAccountNumber	Masked account number of the account which was used	XXXX123456
balance optional	Balance of the bank account used	1234.00
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
udfParameters optional	Udf parameters as passed in the request	JSON string
outstandingAmount optional	Used amount out of the available credit limit in case of a CREDIT or OD account	String

UPI International APIs

Manage Activation

curl -L -X POST '{{host}}/api/{{uri}}/merchants/international/manageActivation'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'

--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "upiRequestId": "TXNef1a2908395239df56663244f8c7deaa",
  "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf",
  "credBlock": "{\"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|j+dtxs...1ca1o0CrjnUw==\",\"code\":\"NPCI\"}}}",
  "startDate": "yyyy-mm-ddThh:mm:ss+05:30",
  "endDate": "yyyy-mm-ddThh:mm:ss+05:30",
  "featureName": "UPI_INTERNATIONAL"
  "action": "ACTIVATE" | "QUERY" | "DEACTIVATE",
  "udfParameters": ""
}'

# Response: for action = ACTIVATE

{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "udfParameters": ""
  "payload":{
    "status": "ACTIVE",
    "startDate": "yyyy-mm-ddThh:mm:ss+05:30",
    "endDate": "yyyy-mm-ddThh:mm:ss+05:30",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "SUCCESS"
   }
}

# Response: for action = QUERY

{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "udfParameters": ""
  "payload":{
    "status": "ACTIVE" | "INACTIVE",
    "startDate": "yyyy-mm-ddThh:mm:ss+05:30",
    "endDate": "yyyy-mm-ddThh:mm:ss+05:30",
    "gatewayResponseStatus": "SUCCESS", # populated if check is disabled
    "gatewayResponseCode": "00", # populated if check is disabled
    "gatewayResponseMessage": "SUCCESS" # populated if check is disabled
   }
}

# Response: for action = DEACTIVATE

{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "udfParameters": ""
  "payload":{
    "status": "INACTIVE",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "SUCCESS"
   }
}

This API is used to activate the international account for international payments for the selected time period. International activation is a pre-requisite for UPI International transaction. The UPI enabled customer apps shall provide for customer activation flow in their apps. Activation can be done for specific time period e.g. for travel duration or enabled till disabled again. The maximum activation period can be of 90 days.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
deviceFingerPrint	Device fingerprint of the customer	String
bankAccountUniqueId	Unique id for the payer selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call
credBlock	Encrypted credblock containing user mpin	As returned by Common Library
startDate optional	Start date of the International Activation yyyy-MM- ddTHH:mm:ss+05:30	String, Should only be populated in case of action = ACTIVATE
endDate optional	End date of the International Activation yyyy-MM- ddTHH:mm:ss+05:30	String, Should only be populated in case of action = ACTIVATE (if not passed in action = ACTIVATE, by default activation request will be executed with 90 days endDate)
action	Action to be performed like ACTIVATE, QUERY, DEACTIVATE	String
featureName	UPI_INTERNATIONAL has to be passed for UPI_INTERNATIONAL and UPI_INTERNATIONAL_FIR has to be passed for consent for FIR	String
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
status	International Status	ACTIVE, INACTIVE
startDate optional	Start date of the International Activation received from bank	String, Should only be populated in case of status = ACTIVE
endDate optional	End date of the International Activation received from bank	String, Should only be populated in case of status = ACTIVE
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
udfParameters optional	Udf parameters as passed in the request	JSON string

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Payment Success.
ZM	Invalid Mpin	Invalid Mpin entered by customer
B3	Txn not permited to the account ex: Minor account or proprietor account	Banks are not allowing this type of accounts
UG1	Response activation time out	Remitter bank failed to respond in the stipulated time
UB9	Remitter bank doesn’t support International Transactions	Failure.

QR Validation

curl -L -X POST '{{host}}/api/{{uri}}/merchants/international/validateQr'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'

--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "upiRequestId": "TXNef1a2908395239df56663244f8c7deaa",
  "qrPayLoad": "upiGlobal://pay?ver=01&mode=02&purpose=11&orgId=1800420001&pa=vxxxat@mypsp&pn=KARMA TAILORING&mc=5697&mid=MER00000006&cc=BTN&bCurr=BTN&qrMedium=04&sign=ARoKGMLxS-8R_9Q9GtptkrKWQHnfIE7sLHofWNFi_0eukvXAjj5Rmf895rPc-gW_8tZNBWqPZAoRGkapY25wTONoASkfjNRlggQg0Jyd--X8dcwAh37d1qb8Lh95sq9O3_jd9UxW6-KjdlL5ZQdARVsfItDutGNNqFv_oxNNC8TU6WYq",
  "initiationMode": "02",
  "networkInstitutionId": "1812345678",
  "udfParameters": ""
}'

# Response for Merchants with checks enabled: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "udfParameters": "",
  "payload":{
    "txnId": "txnId",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "SUCCESS",
    "paymentDetails":{
      "payeeName": "payeename",
      "payeeCode": "payeecode",
      "payeeType": "payeetype",
      "payeeAddr": "addr@mypsp",
      "fxList": [
        {
          "fx": "1.00",
          "mkup": "2.90",
          "baseAmount": "35.00",
          "baseCurr": "AUS",
          "convertedAmount": "35.00",
          "lastModifiedTs": "yyyy-mm-ddThh:mm:ss+05:30",
          "active": "Y" | "N"
        },
        {
          "fx": "2.00",
          "mkup": "2.95"
          "baseAmount": "36.00",
          "baseCurr": "SGR",
          "convertedAmount": "74.12",
          "lastModifiedTs": "yyyy-mm-ddThh:mm:ss+05:30",
          "active": "Y" | "N",
        }
      ]
    }
  }
}

# Response for Merchants with checks disabled: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseMessage": "SUCCESS",
  "responseCode": "SUCCESS",
  "udfParameters": "{}",
  "payload":{
    "gatewayResponseStatus": "SUCCESS",
    "txnId": "txnId",
    "gatewayResponseMessage": "Your transaction is successful",
    "gatewayResponseCode": "00",
    "paymentDetails":{
      "payeeName": "Merchant",
      "payeeCode": "5697",
      "payeeType": "ENTITY",
      "payeeAddr": "venkat@mypsp",
      "qr":{
          "expireTs": "2022-12-02T13:15:00+05:30",
          "networkInstitutionId": "1800420001",
          "verificationToken": "71234",
          "qrPayload": "upiGlobal://pay?ver=01&mode=02&purpose=11&orgId=1800421201&pa=payee@xyz&pn=KARMA TAILORING&mc=1234&mid=MER00000006&cc=BTN&bCurr=BTN&qrMedium=04&sign=ARoKGMLxS-8R_9Q9GtptkrKWQHnfIE7sLHofWNFi_0eukvXAjj5Rmf895rPc-gW_8tZNBWqPZAoRGkapY25wTONoASkfjNRlggQg0Jyd--X8dcwAh37d1qb8Lh95sq9O3_jd9UxW6-KjdlL5ZQdARVsfItDutGNNqFv_oxNNC8TU6WYq",
          "medium": "16",
          "version": "01",
          "query": "",
          "countryCode": "",
          "stan": "132011",
          "timestamp": "2021-02-12T19:56:57+05:30"
      },
      "account":{
        "accType": "CURRENT",
        "ifsc": "AABC0001234",
        "encAccNum": "7645fd812621e3640ca62fdcf13f7887ec16b77123a6c26e7cad757a4b814a59"
      },
      "fxList": [
        {
          "fx": "1.00",
          "mkup": "2.90",
          "baseAmount": "35.00",
          "baseCurr": "AUS",
          "convertedAmount": "35.00",
          "lastModifiedTs": "yyyy-mm-ddThh:mm:ss+05:30",
          "active": "Y" | "N"
        },
        {
          "fx": "2.00",
          "mkup": "2.95"
          "baseAmount": "36.00",
          "baseCurr": "SGR",
          "convertedAmount": "74.12",
          "lastModifiedTs": "yyyy-mm-ddThh:mm:ss+05:30",
          "active": "Y" | "N",
        }
      ],
      "merchant":{
        "registrationId": "23946934",
        "franchise": "GAGOI",
        "invoiceNum": "324632584238",
        "merchantType": "SMALL",
        "pincode": "7000105",
        "location": "BHUTAN",
        "ownershipType": "OTHERS",
        "brand": "GAGOI",
        "invoiceName": "FOR",
        "tid": "66322746283",
        "tier": "",
        "invoiceDate": "121219",
        "instCode": "88888",
        "mid": "454646",
        "genre": "ONLINE",
        "onBoardingType": "BANK",
        "legal": "GAGOI",
        "sid": "46578765432676541212",
        "subCode": "1221"
      }
    }
  }
}

This API is used to validate the UPI international QR, and before doing any payment this api should be called.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
deviceFingerPrint	Device fingerprint of the customer	String
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
qrPayLoad	Deep Link URL	String
initiationMode	Defines the initiation mode of the transaction	Initiation Modes
networkInstitutionId optional	Unique ID for each international institution provided by UPI	String
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters with check enabled

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
txnId	This id will be created for every txn by Merchant	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayReferenceId	Reference id returned by the gateway	String
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
fx	Foreign exchange rate	Decimal String, with 2 decimal places
mkup	Markup rate	String
baseAmount optional	Amount in base currency	Decimal String, with 2 decimal places. Only populated in case of dynamic QR
baseCurr	Base currency	String
convertedAmount optional	converted amount based on the country	Decimal String, with 2 decimal places. Only populated in case of dynamic QR
lastModifiedTs optional	Last modified time of the QR as received from NPCI	String
active optional	Active status for forex as received from NPCI	String
udfParameters optional	Udf parameters as passed in the request	JSON string
payeeName	Payee name is to be used for International Pay txns	String
payeeAddr	Vpa of the payee to whom money is being sent	something@handle
payeeCode	MCC code of payee	String
payeeType	Merchant's type ex:SMALL, LARGE	String

Response parameters with check disabled

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
txnId	This id will be created for every txn by Merchant	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayReferenceId	Reference id returned by the gateway	String
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
payeeName	Payee name is to be used for International Pay txns	String
payeeAddr	Vpa of the payee to whom money is being sent	something@handle
payeeCode	MCC code of payee	String
payeeType	Merchant's type ex:SMALL, LARGE	String
fx	Foreign exchange rate	Decimal String, with 2 decimal places
mkup	Markup rate	String
baseAmount optional	Amount in base currency	Decimal String, with 2 decimal places. Only populated in case of dynamic QR
baseCurr	Base currency	String
convertedAmount optional	converted amount based on the country	Decimal String, with 2 decimal places. Only populated in case of dynamic QR
lastModifiedTs optional	Last modified time of the QR as received from NPCI	String
active optional	Active status for forex as received from NPCI	String
expireTs	Expired time stamp of international activation	String
networkInstitutionId	Unique ID for each international institution provided by UPI	String
verificationToken	This is a unique token generated by the International partner for every QR validation request response, based on which payment is later approved or decline	String
qrPayload	Deep Link URL	String
medium	This field indicates the Source channel i.e. creation point of the string (like Gallery, App, ATM, etc).	String
version	The QR Version	String
query	This is for future use in JSON format. We can add multiple fields basis requirements	String
countryCode	Represents the country code of the Merchant	String
stan	STAN - System Trace Audit Number. Unique identifier for the transaction used by the merchant	String
timestamp	Timestamp representing the creation time of QR	String
encAccNum	Account Reference Number	String
accType	Account Type	String
ifsc	Account IFSC	String
registrationId	Identifier for this QR scan instance, generated by the merchant/network	String
franchise	Franchise agent name	String
invoiceNum optional	This field is used to capture the bill invoice date. Only mandatory for GST use case	String
merchantType	Merchant's type, Ex: SMALL, LARGE	String
pincode	Zip code or pin code or postal code of the merchant	String
location	Location of the Country	String
ownershipType	Type of Ownership, Ex: PROPRIETARY, PARTNERSHIP, PRIVATE, PUBLIC, OTHERS	String
brand	Brand name of the Merchant	String
invoiceName optional	This field is used to track the unique customer name present in the bill. If this tag is present, app should display the value to the customer	String
tid	Terminal id for merchant	String
tier	Denotes the tier of the city on the basis of the population Ex: TIER1, TIER2, TIER3	String
invoiceDate optional	This field is used to capture the bill/ invoice no. If this tag is present, app should display the value to the customer. Only mandatory for GST use case	String
instCode	This is w.r.t to end Aggregator identification by the International Network	String
mid	The Merchant’s Id	String
genre	Merchant Genre, Ex: ONLINE, OFFLINE	String
onBoardingType	Onboarding Type of merchant, Ex:BANK, AGGREGATOR	String
legal	Legal name of the merchant	String
sid	Merchant's Store Id	String
subCode	This is the MCC code of the Merchant	String
udfParameters optional	Udf parameters as passed in the request	JSON string

Send Money

curl -L -X POST '{{host}}/api/{{uri}}/merchants/transactions/sendMoney'
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "merchantRequestId": "redId1234",
  "payerVpa": "customer@handle",
  "payeeVpa": "payee@xyz",
  "payeeName": "John Doe",
  "amount": "2.00",
  "upiRequestId": "TXNef1a2908395239df56663244f8c7deaa",
  "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
  "credBlock": "{\"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|j+dtxs...1ca1o0CrjnUw==\",\"code\":\"NPCI\"}}}",
  "remarks": "Payment for order",
  "currency": "INR",
  "transactionType": "SCAN_PAY",
  "transactionReference": "P1708071422508815250029",
  "refUrl": "https://www.abcxyz.com/",
  "refCategory": "",
  "mcc": "",
  "initiationMode": "",
  "purpose": "11"
}'

# Request for Merchants with checks enabled: HTTP 200 OK
{
  "baseAmount": "35.00",
  "baseCurr": "AUS",
  "intlTxnConsent": "",
  "originalTransactionUpiRequestId": "",
  "udfParameters": ""
}

# Request for Merchants with checks disabled: HTTP 200 OK
{
  "baseAmount": "35.00",
  "baseCurr": "AUS",
  "intlTxnConsent": "",
  "originalTransactionUpiRequestId": "",
  "fx": "1.00",
  "mkup": "2.90",
  "qrVerToken": "123456",
  "qrStan": "123456",
  "mSubCode": "1234",
  "mType": "SMALL",
  "mGenre": "ONLINE",
  "mOnBoardingType": "BANK",
  "mRegId": "12345678",
  "mPinCode": "1234567",
  "mTier": "TIER 1",
  "mLoc": "Bhutan",
  "mInstCode": "99999",
  "mBrand": "GAGA",
  "mLegal": "GAGA",
  "mFranchise": "GAGA",
  "mOwnershipType": "Others",
  "iQrPayLoad": "upiGlobal://pay?ver=01&mode=02&purpose=11&orgId=1800421201&pa=payee@xyz&pn=KARMA TAILORING&mc=1234&mid=MER00000006&cc=BTN&bCurr=BTN&qrMedium=04&sign=ARoKGMLxS-8R_9Q9GtptkrKWQHnfIE7sLHofWNFi_0eukvXAjj5Rmf895rPc-gW_8tZNBWqPZAoRGkapY25wTONoASkfjNRlggQg0Jyd--X8dcwAh37d1qb8Lh95sq9O3_jd9UxW6-KjdlL5ZQdARVsfItDutGNNqFv_oxNNC8TU6WYq",
  "iConCode": "AUSdummy",
  "iNetInstId": "18000234567",
  "payeeAccRef": "4567fd812621e3640ca62fdcf13f7887ec11234e87a6c26e7cad757a4b814a59",
  "payeeAccType": "Savings",
  "payeeAccIfsc": "AA1234556",
  "invoiceName": "FOR",
  "invoiceNum": "1234567890123",
  "invoiceDate": "01/02/2023",
  "udfParameters": ""
}


# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "merchantRequestId": "redId1234",
    "customerMobileNumber": "919988776655",
    "payerVpa": "customervpa@bank",
    "payeeMcc": "0000",
    "payeeMerchantCustomerId": "DEMO-CUST-5678",
    "payeeName": "John Doe",
    "payeeVpa": "payee@xyz",
    "payeeActype": "",
    "payerActype": "",
    "payeeIfsc": "",
    "payerIfsc": "",
    "refUrl": "https://www.abcxyz.com/",
    "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
    "bankCode": "123456",
    "maskedAccountNumber": "XXXX123456",
    "amount": "2.00",
    "transactionType": "SCAN_PAY",
    "transactionTimestamp": "2017-06-09T17:57:49+05:30",
    "gatewayTransactionId": "TXNef1a2908395239df56663244f8c7deaa",
    "gatewayReferenceId": "809323430413",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Your transaction is successful",
    "gatewayPayerResponseCode": "00",
    "gatewayPayeeResponseCode": "00",
    "gatewayPayerReversalResponseCode": "00",
    "gatewayPayeeReversalResponseCode": "00"
  },
  "udfParameters": ""
}

This api will be used for completing all P2P and P2M Payment scenarios. This includes

• Incoming Intent Payment
• Scan and Pay (UPI QR & Bharat QR)
• P2P Pay (Vpa & Account+IFSC)
• Payment to PSP merchant
• Self Pay

The api can be invoked to process different types of payments. The transactionType key of request is used to identify the type of payment. Possible values are P2M_PAY, P2P_PAY, SELF_PAY, INTENT_PAY and SCAN_PAY. Depending on the payment type, some additional parameters need to be passed.

P2M_PAY is to be used for payment to a PSP merchant only. The payeeVpa should be a valid PSP generated vpa for the merchant.

INTENT_PAY and SCAN_PAY are used for the intent and qr scan transactions. Both UPI QR and Bharat QR codes are supported.

P2P_PAY is to be used for completing all other P2P payment scenarios. For direct to account transfers, payeeVpa should be of format <account-no>@<ifsc-code>.ifsc.npci like 12345@BankIFSC.ifsc.npci.

SELF_PAY is to be used for doing a self transfer between customer accounts having same vpa domain.

SELF_PAY is to be used for doing a self transfer between customer accounts having same vpa domain.

UPI International transactionType will only be SCAN_PAY.

Below are some request parameters required to be handled specifically according to the payment scenario.

Parameter	P2M Pay	P2P Pay	Scan & Pay	Incoming Intent	Self Pay
transactionType	P2M_PAY	P2P_PAY	SCAN_PAY	INTENT_PAY	SELF_PAY
payeeVpa	Mandatory	Mandatory	pa in deeplink url	pa in deeplink url	Mandatory
payeeName	Not Required	Not required for account transfers only	pn in deeplink url	pn in deeplink url	Mandatory
amount	Mandatory	Mandatory	am in deeplink url	am in deeplink url	Mandatory
upiRequestId	Mandatory	Mandatory	tid in deeplink url	tid in deeplink url	Mandatory
remarks	Mandatory	Mandatory	tn in deeplink url	tn in deeplink url	Mandatory
refUrl	Not Required	Not Required	url in deeplink url	url in deeplink url	Not Required
refCategory	Not Required	Not Required	category in deeplink url	category in deeplink url	Not Required
currency	INR	INR	cu in deeplink url	cu in deeplink url	INR
mcc	Mandatory	Not Required	mc in deeplink url	mc pin deeplink url	Not Required
transactionReference	Not Required	Not Required	tr in deeplink url	tr in deeplink url	Not Required
payeeBankAccountUniqueId	Not Required	Not Required	Not Required	Not Required	Mandatory

Note

1. Validity of a payeeVpa can be verified using the Verify VPA API.
2. SERVICE_UNAVAILABLE_{entity}_{error} will be returned in case of NPCI timeout or deemed transactions.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
deviceFingerPrint	Device fingerprint of the customer	String
merchantRequestId	Merchant generated id for the transaction	35 characters alphanumeric
payerVpa	VPA of the customer to be used for payment	something@handle
payeeVpa	Vpa of the payee to whom money is being sent	something@handle
payeeName optional	Name of the payee	String as returned in the Verify VPA API
amount	Amount for transaction	Numeric string with two decimals
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
bankAccountUniqueId	Unique id for the payer selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call
payeeBankAccountUniqueId optional	Unique id for the payee selected bank account for self transfer	bankAccountUniqueId in the response of Fetch Accounts api call
credBlock	Encrypted credblock containing user mpin	As returned by Common Library
remarks	Any transaction summary	50 characters, alphanumeric, space and hyphen
currency	Currency code	String - INR
transactionType	Type of payment	SCAN_PAY
transactionReference optional	Transaction reference id	String
refUrl optional	Reference url for the intent transaction	String
refCategory optional	Details for refUrl, whether it is 01 (Advertisement), 02(Invoice)	String
mcc optional	Merchant category code	String
initiationMode optional	Defines the initiation mode of the transaction	Initiation Modes
purpose	Defines the purpose code of the transaction	Purpose Codes
upiNumber optional	upiNumber of payee if transaction is done using UPI Number	String (8-10 digit Number)
udfParameters optional	Stringified JSON for udf parameters	JSON string

Request parameters for checks enabled

Parameter	Description	Constraints
purpose	Defines the purpose code of the transaction	Purpose Codes
baseAmount	Amount in base currency	String
baseCurr	Base currency	String
intlTxnConsent	The consent type denotes the purpose for which the customer’s consent is being taken.This is for specific use cases as may be defined in future. This tag is not applicable for GST	String
originalTransactionUpiRequestId	The txnId of QR Validation request	35 character alphanumeric. Should always start with merchant prefix provided.

Request parameters for checks disabled

Parameter	Description	Constraints
purpose	Defines the purpose code of the transaction	Purpose Codes
baseAmount	Amount in base currency	String
baseCurr	Base currency	String
intlTxnConsent	The consent type denotes the purpose for which the customer’s consent is being taken.This is for specific use cases as may be defined in future. This tag is not applicable for GST	String
originalTransactionUpiRequestId	The txnId of QR Validation request	35 character alphanumeric. Should always start with merchant prefix provided.
fx optional	Foreign exchange rate	String
mkup optional	Markup rate	String
qrVerToken optional	This is a unique token generated by the International partner for every QR validation request/response, based on which payment is later approved or declined	String
qrStan optional	STAN - System Trace Audit Number. Unique identifier for the transaction used by the merchant	String
mSubCode optional	This is the MCC code of the Merchant	String
mType optional	Merchant's type, Ex:SMALL, LARGE	String
mGenre optional	Genre of sub-merchant	ONLINE, OFFLINE.
mOnBoardingType optional	Onboarding type of sub-merchant	BANK, AGGREGATOR
mRegId optional	Identifier for this QR scan instance, generated by the merchant/network	String
mPinCode optional	Zip code or pin code or postal code of the merchant	String
mTier optional	Denotes the tier of the city on the basis of the population Ex: TIER1, TIER2, TIER3	String
mLoc optional	Location of the Country	Stirng
mInstCode optional	This is w.r.t to end Aggregator identification by the International Network	String
mBrand optional	Brand name of the Merchant	String
mLegal optional	Legal name of the merchant	String
mFranchise optional	Franchise agent name	String
mOwnershipType optional	Type of Ownership, Ex: PROPRIETARY, PARTNERSHIP, PRIVATE, PUBLIC, OTHERS	String
iQrPayLoad optional	Deep Link URL	String
iConCode optional	Represents the country code of the Merchant	String
iNetInstId optional	Unique ID for each international institution provided by UPI	String
payeeAccRef optional	Payee Account reference	String
payeeAccType optional	Type of payee account	String
payeeAccIfsc optional	Payee Account IFSC	String
invoiceName optional	This field is used to track the unique customer name present in the bill. If this tag is present, app should display the value to the customer	String
invoiceNum optional	This field is used to capture the bill invoice date. Only mandatory for GST use case	String
invoiceDate optional	This field is used to capture the bill/ invoice no. If this tag is present, app should display the value to the customer. Only mandatory for GST use case	String

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantRequestId	Merchant generated id for the transaction	As passed in the request
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
payerVpa	Customer vpa used for the payment	As passed in the request
payeeMcc	MCC for the payee	String
payeeMerchantCustomerId optional	Merchant generated unique id for customer who received the payment. Only if it is an onus P2P transaction.	String
payeeName optional	Name of the upi user who received the payment. Only if payment is done to a non A/C+IFSC vpa.	String
payeeActype	Account type of the customer who received the payment	String
payerActype	Account type of the customer who sends the payment	String
payeeIfsc	Account ifsc of the customer who received the payment	String
payerIfsc	Account ifsc of the customer who sends the payment	String
payeeVpa	Vpa of the upi user who received the payment	something@handle
refUrl	Reference url for the intent transaction	String
bankAccountUniqueId	Unique id for the selected bank account	As passed in the request
bankCode	Bank code of the account which was used	Valid bank IIN
maskedAccountNumber	Masked account number of the account which was used	XXXX123456
amount	Amount for the payment	As passed in the request
transactionType	Type of payment	As sent in request
transactionTimestamp	Timestamp of when the transaction was attempted	YYYY-MM-DDTHH:MM:SS+05:30
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayReferenceId	Reference id returned by the gateway	String
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
gatewayPayerResponseCode optional	Response code returned by gateway	String
gatewayPayeeResponseCode optional	Response code returned by gateway	String
gatewayPayerReversalResponseCode optional	Response code returned by gateway	String
gatewayPayeeReversalResponseCode optional	Response code returned by gateway	String
udfParameters optional	Udf parameters as passed in the request	JSON string

gatewayResponseCode	gatewayResponseStatus	Description
00	SUCCESS	Payment Success.
Z9	FAILURE	Insufficient funds in customer (remitter) account.
Z8	FAILURE	Per transaction limit exceeded as set by remitting member.
Z7	FAILURE	Transaction frequency limit exceeded as set by remitting member.
Z6	FAILURE	Number of pin tries exceeded.
ZM	FAILURE	Invalid mpin.
Else	FAILURE	Any other reason.
UA2	Version/Tags not supported by PSP/Bank	Payer PSP not supported for "FOR" transactions
U16	Risk Threshold exceeded	NPCI FRM sends response with the risk score which has breached the NPCI configured FRM limit
U30	Debit has been failed	Remitter bank validates customer international activation and decline the request
U12	Amount or currency mismatch	FX value incorrect error code
U31	Credit has been Failed	International entity validates the verification token provided in the Validate QR response and decline the transaction with response code "IV" / Merchant fails to send confirmation to international network
U29	Address resolution is failed	International entity validates the QR Expiry provided in the Validate QR response and declines the transaction with response code "PE"

Additional Error Codes

responseCode	Meaning
DUPLICATE_REQUEST	Duplicate merchantRequestId or upiRequestId used for the transaction

Delegate Payments

The below APIs should be called post the Device Binding is completed.

Manage VPA

Incase a user is creating a VPA without a Bank Account, merchant should call the below API to create VPA without a Banking Instrument

Endpoint - {{host}}/api/{{uri}}/merchants/vpaAccounts

curl --location '{host}/api/{uri}/merchants/vpaAccounts' \
--header 'Content-Type: application/json' \
--header 'x-merchant-id: TEST' \
--header 'x-merchant-channel-id: TESTAPP' \
--header 'Accept: application/json' \
--header 'x-timestamp: 1549040555000' \
--header 'x-api-version: 4' \
--data-raw '{
  "merchantCustomerId": "S7875792622627",
  "action": "ADD_VPA",
  "customerVpa": "p8639@ypay",
  "flags": ["DelegateVpa"],
  "udfParameters": "{}"
}'

# Response

{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload": {
        "vpas": [],
        "merchantChannelId": "TESTAPP",
        "merchantId": "TEST",
        "accounts": [],
        "delegateInfo": {
            "delegateLinks": [],
            "delegateVpas": [
                "p8639@ypay"
            ]
        },
        "customerMobileNumber": "915792622627",
        "merchantCustomerId": "S7875792622627"
    },
    "udfParameters": "{}"
}

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
action	Action to be performed on vpaAccounts	ADD_VPA, DELETE_VPA
customerVpa	Vpa on which Action is to be perfomed	something@handle
flags optional	flags to make decisions for various vpa	array of flags specified in table below
udfParameters optional	Stringified JSON for udf parameters	JSON string

Flag	Description
DelegateVpa	Specify that vpa being added doesn't have a bank account over it.

If nothing is passed in flags everything will be deleted

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
vpas	List of vpas added	Array
Accounts	List of Accounts assosiated with that vpa	Array
DelegateInfo	List of DelegateLinks and DelegateVpas assosiated with that vpa	Object
DelegateLinks	List of Links Assosiated for that MCID	Array of Objects
DelegateVpas	List of Active DelegateVpas for that MCID	Array of Strings
udfParameters optional	Udf parameters as passed in the request	JSON string

VerifyVPA360

This API will be used to verify mobile number and vpa of delegatee by the delegator before initiating a link Request. It will also validate the mapping between vpa and mobileNumber of the delegatee as passed in request.

Note:

1. You will need to send x-api-version: 1 in headers.

2. ifsc ,iin ,isMerchant ,isMerchantVerified ,mcc , featureTags and merchantType will not be applicable in delegate validation

EndPoint - {host}/api/{uri}/merchants/vpas/validity360

curl --location '{host}/api/{uri}/merchants/vpas/validity360' \
--header 'Content-Type: application/json' \
--header 'x-merchant-id: TEST' \
--header 'x-merchant-channel-id: TESTAPP' \
--header 'x-timestamp: 1549040555000' \
--header 'x-api-version: 1' \
--data-raw '{
    "upiRequestId": "YPC173bc3c",
    "vpa": "p8639@ypay",
    "mobileNumber" : "915792622627",
    "purposeCode" : "87",
    "merchantCustomerId": "test-merchantcustomer-1",
    "udfParameters": "{}"
}'


# Response

{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload": {
        "merchantChannelId": "AMAZONAPP",
        "gatewayResponseStatus": "SUCCESS",
        "vpa": "Name",
        "merchantId": "AMAZON",
        "isMerchant": "false",
        "gatewayResponseMessage": "Your transaction is successful",
        "mobileNumber": "915792622627",
        "gatewayResponseCode": "00",
        "gatewayTransactionId": "YPC173bc3c",
        "name": "p8639@ypay",
        "featureTags": []
    },
    "udfParameters": "{}"
}

Request parameters

Parameter	Description	Constraints
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
vpa	VPA to be verified	something@handle
mobileNumber	mobile number of the delegatee	String
purposeCode	purposeCode of api call	87 for PARTIAL Delegation and 59 for FULL Delegation
merchantCustomerId optional	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
vpa	Vpa as passed in the request	String
mobileNumber	mobile number of the delegatee	String
name optional	Name of the customer	String
ifsc optional	IFSC code of the account linked to this VPA	String
iin optional	IIN code of the account linked to this VPA	String
isMerchant	Flag indicating whether the VPA is of merchant or not	Boolean string
isMerchantVerified optional	Flag indicating whether merchant is verified or not	Boolean string
mcc optional	Merchant Category Code for the merchant whose VPA is passed	String
merchantType optional	Merchant Type for the merchant whose VPA is passed	JSON
udfParameters optional	Udf parameters as passed in the request	JSON string
featureTags optional	This will be an array of feature values, each having it's own significance as decided by NPCI	Array of strings

Manage Delegate Links

This API will be there to manage delegate links by both primary and secondary. Linking can only be done by a Delegator but Delinking can be done by both Delegator and Delegatee. Same API will also be used by Delegatee to approve the linking request. In case of action = LINK, the API will be async. In all other cases, it will be sync.

curl --location '{host}/api/{uri}/merchants/customer/delegates/manageLink' \
--header 'Content-Type: application/json' \
--header 'x-merchant-id: TEST' \
--header 'x-merchant-channel-id: TESTAPP' \
--header 'x-timestamp: 1549040555000' \
--header 'x-api-version: 4' \
--data-raw '{
    "action": "LINK",
    "delegatorVpa": "p8991@yapl",
    "delegateeVpa": "p3116@yapl",
    "delegateeMobileNumber": "915344449869",
    "deviceFingerPrint": "fbaaed9de89c687e91cd65a3bf25591556b77012589a73677c50d95749013684",
    "expiry": "30",
    "initiatedBy": "DELEGATOR",
    "upiRequestId": "YAP79922e6",
    "linkType": "PARTIAL",
    "currency": "INR",
    "merchantRequestId": "YAP79922e6MRID",
    "delegateeName": "KARAN",
    "documentType": "AADHAAR",
    "documentId": "847906830000",
    "relation": "CHILD",
    "merchantCustomerId" : "P7870468342262"
}'


{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload": {
        "initiatedBy": "DELEGATOR",
        "linkStatus": "LINK_PENDING",
        "merchantChannelId": "TESTAPP",
        "gatewayResponseStatus": "SUCCESS",
        "merchantId": "TEST",
        "expiry": "30",
        "refUrl": "https://www.juspay.com/",
        "delegateeVpa": "p3116@yapl",
        "deviceFingerPrint": "fbaaed9de89c687e91cd65a3bf25591556b77012589a73677c50d95749013684",
        "gatewayResponseMessage": "Your LINK action has been raised successfully",
        "action": "LINK",
        "merchantRequestId": "YAP79922e6MRID",
        "gatewayResponseCode": "00",
        "gatewayTransactionId": "YAP79922e6",
        "currency": "INR",
        "delegateeName": "KARAN",
        "delegatorVpa": "p8991@yapl",
        "merchantCustomerId": "P7870468342262",
        "linkedUpiRequestId": "YAP79922e6"
    }
}

Action	Description
LINK	Its is used to initiate the linking by Delegator to a Delegatee
DELINK	It is used to perform Delinking operation either by Delegator or Delegatee.
APPROVE	It is used to approve the delegate link request by Delegatee.
DECLINE	It is used to decline the delegate link request by Delegatee.
CHECK	It is used to check the status of the link either by Delegator or Delegatee.
UPDATE	It used to perform updates on the link between Delegator and Delegatee. Will be application only in case of FULL Delegates. Can only be performed by Delegator.
CHECK_BALANCE	It is used to check the remaining balance (in case of a FULL delegation relation).
CONVERT_TO_FULL	It is used to convert a PARTIAL linking to FULL linking. Can be done by Delegator only
CONVERT_TO_PARTIAL	It is used to convert a FULL linking to PARTIAL linking. Can be done by Delegator only
MARK_LINK_EXPIRED	The Delegator can mark the link as expired if the Delegatee does not respond after the DelegateLink expiry time has passed.Can be done by Delegator only

Endpoint S2S - merchant/customer/delegates/manageLink

Request Body

Parameter	Description	Values
action	Link action to be performed	LINK, DELINK, APPROVE, DECLINE, CHECK, UPDATE, CHECK_BALANCE, CONVERT_TO_FULL, CONVERT_TO_PARTIAL and MARK_LINK_EXPIRED
delegatorVpa	Delegatee Vpa	something@handle
delegateeVpa	Delegatee Vpa	something@handle
deviceFingerPrint	Device fingerprint of the customer	String
expiry optional	Expiry of Linking Request (in minutes)	String (Max value can be 30)
initiatedBy	User type initiating the request	DELEGATOR or DELEGATEE
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
linkType	type of linking	FULL or PARTIAL
amount optional	Amount in case of FULL Delegates	String
bankAccountUniqueId optional	Unique id for the selected bank account for FULL Delegates	As passed in the request
credBlock optional	Encrypted credblock containing user mpin. (in case of Full Delegates )	As returned by Common Library
currency	Currency code	String - INR
mandateName optional	Name of the Mandate only in case of Full Delegate	String
mcc optional	Merchant category code	String
merchantRequestId	Merchant generated id for the mandate request	35 character alphanumeric unique id.
delegateeName	Name of the delegatee	String
delegateeMobileNumber optional	Only required in link call	Numeric
refUrl optional	It is mainly kept for future purpose for invoice in inbox feature, if nothing is passed then a default value is set for this tag and same will be send back in response.	String
remarks optional	Any linking summary	String
udfParameters optional	Stringified JSON for udf parameters	JSON string
validityEnd optional	Date before which mandate can be execute	String with proper date format YYYY/MM/DD
refCategory optional	Details for refUrl, whether it is 01 (advertisement), 02(Invoice). If nothing is passed, a default value of "00" is set up and same
purpose optional	purposeCode of api call	87 for PARTIAL Delegation and 59 for FULL Delegation
documentType optional	The document type used for linking. Mandatory for FULL Delegation	AADHAAR, PASSPORT, VOTER_ID, NREGA, DRIVING_LICENSE
documentId optional	The corresponding document number for selected documentType. Mandatory for FULL Delegation	String
relation	The relation between Delegator and Delegatee.	Child, Parent, Spouse, Sibling, Domestic Employee, Small Business Employee

Note:

1. CredBlock is required in FULL Delegate LINK request, DELINK performed by DELEGATOR for FULL Delegates and UPDATE operation perform by Delegator for FULL Delegates
2. Update for FULL delegation can be done by DELEGATOR only.
3. Conversion can be done by DELEGATOR only.

Request Parameter table

Parameter	LINK	DELINK	APPROVE	DECLINE	CHECK	UPDATE	CHECK_BALANCE	CONVERT_TO_FULL	CONVERT_TO_PARTIAL	MARK_LINK_EXPIRED
delegatorVpa	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory
delegateeVpa	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory
deviceFingerPrint	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory
expiry	Mandatory	Not Required	Not Required	Not Required	Not Required	Not Required	Not Required	Mandatory	Mandatory	Not Required
initiatedBy	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory
merchantCustomerId	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory
upiRequestId	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory
linkType	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory
amount	Mandatory if FULL	Not Required	Not Required	Not Required	Not Required	Mandatory	Not Required	Mandatory	Not Required	Not Required
bankAccountUniqueId	Mandatory if FULL	Not Required	Not Required	Not Required	Not Required	Not Required	Not Required	Mandatory	Not Required	Not Required
credBlock	Mandatory if FULL	Mandatory if FULL	Not Required	Not Required	Not Required	Mandatory if FULL	Not Required	Mandatory	Mandatory	Mandatory
currency	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory
mandateName	Mandatory if FULL	Not Required	Not Required	Not Required	Not Required	Optional	Not Required	Mandatory	Not Required	Not Required
merchantRequestId	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory
delegateeName	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory
delegateeMobileNumber	Mandatory	Not Required	Not Required	Not Required	Not Required	Not Required	Not Required	Mandatory	Mandatory	Mandatory
refUrl	Optional	Optional	Optional	Optional	Optional	Optional	Optional	Optional	Optional	Optional
validityEnd	Mandatory if FULL	Not Required	Not Required	Not Required	Not Required	Mandatory	Not Required	Mandatory	Not Required	Not Required
refCategory	Optional	Optional	Optional	Optional	Optional	Optional	Optional	Optional	Optional	Optional
mcc	Optional	Optional	Optional	Optional	Optional	Optional	Optional	Optional	Optional	Optional
remarks	Optional	Optional	Optional	Optional	Optional	Optional	Optional	Optional	Optional	Optional

Response Body

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
action	Link action to be performed	LINK, DELINK, APPROVE, DECLINE, CHECK, UPDATE and CHECK_BALANCE
amountUsed optional	Amount exhausted in the current cycle of 30 days (applicable in case of Full Delegation)	String
currentCycleEnd optional	End date of the current Full Delegation cycle. Renews every 30 days	String with proper date format YYYY/MM/DD
delegatorVpa	Delegator Vpa	As passed in the request
delegateeVpa	Delegatee Vpa	something@handle
bankAccountUniqueId optional	Unique id for the selected bank account for FULL Delegates	As passed in the request
deviceFingerPrint	Device fingerprint of the customer	String
merchantId	Unique id for merchant.	String
merchantChannelId	Unique id for the channel via which request is made.	String
expiry optional	Timestamp until which link request is valid.
gatewayReferenceId	Reference id returned by the gateway	String
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayTransactionId	Transaction id returned by gateway	String
initiatedBy	user type initiating the request	DELEGATOR or DELEGATEE
linkStatus	status of the Delegate Link	Linked, Delinked, DECLINED, LINK_PENDING, EXPIRED, FAILURE
linkType	type of linking	FULL or PARTIAL
linkedUpiRequestId	upiRequestId for linking call	String
limit optional	limit of the mandate in case of Full Delegate	String
merchantCustomerId	Merchant generated unique id for customer. It will not be present if 'PAYEE' is merchant.
umn optional	Umn of Mandate in case of Full Delegation	String
currency	Currency code	String - INR
mandateName optional	Name of the Mandate in case of Full Delegate	String
mcc optional	Merchant category code	String
merchantRequestId	Merchant generated id for the link request	35 character alphanumeric unique id.
delegateeName	Name of the Delegatee	String
refUrl	Reference url for the link. It is mainly kept for future purpose for invoice in inbox feature, if nothing is passed then a default value is set for this tag and same will be send back in response.	String
remarks optional	Any link summary	String
udfParameters optional	Stringified JSON for udf parameters	JSON string
validityEnd optional	Date till which link can be executed	String with proper date format YYYY/MM/DD
refCategory optional	Details for refUrl, whether it is 01 (advertisement), 02(Invoice). If nothing is passed, a default value of "00" is set up and same

LINKING REQUEST CALLBACK

Callback to inform Delegatee in case of any incoming linking request received.

DELEGATE_LINK_REQUEST

{
    "bankCode": "500004",
    "action" : "LINK",
    "delegateeName": "KARAN",
    "delegateeVpa": "something@handle",
    "delegatorMobileNumber": "914612963979",
    "delegatorName": "ABC",
    "delegatorVpa": "something@handle",
    "expiryTimestamp": "2025-03-19T13:05:53+05:30",
    "gatewayTransactionId": "APYf583fb6c06904319920de317bd8b075f",
    "ifsc": "AABF0008032",
    "limit": "1610.00",
    "linkType": "FULL",
    "maskedAccountNumber": "XXXXXXXXXXX4769",
    "merchantChannelId": "APLTEST",
    "merchantCustomerId": "amzn1.account.637188",
    "merchantId": "APLTEST",
    "orgMandateId": "JUS9d2ac2c8e37b4f11930dd03",
    "recurrencePattern": "ASPRESENTED",
    "type": "DELEGATE_LINK_REQUEST",
    "umn": "bfe261ed85c14825ae44b31a090ad7d2@yapl",
    "validityEnd": "2025/08/01",
    "relation": "CHILD",
    "documentType": "AADHAR",
    "documentId": "XXXXXXXXXXXX"
}

Parameter	Description	Values
bankCode optional	Bank code of delegator bank account for FULL Delegates	Alphanumeric string. Maximum length is 11.
action optional	Last action perfomed on the delegateLink	LINK or CONVERT_TO_FULL or CONVERT_TO_PARTIAL
delegateeName	delegateeName as passsed by delegator in link request	String
delegateeVpa	Delegatee Vpa	something@handle
delegatorMobileNumber	Mobile Number of DELEGATOR	String
delegatorName	Name of the delegator	String
delegatorVpa	Delegator Vpa	something@handle
expiryTimestamp	Timestamp of when the link request will expire	YYYY-MM-DDTHH:MM:SS+05:30
gatewayTransactionId	UPI request id of linking request	String
ifsc optional	Ifsc code of delegator bank account for FULL Delegates	Alphanumeric string. Maximum length is 11.
limit optional	Maximum amount set for the mandate	String
linkType	type of linking	FULL or PARTIAL
maskedAccountNumber optional	Delegator Masked Account Number in case of Full Delegate	String
merchantChannelId	Unique id for the channel via which request is made.	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
merchantId	Unique id for merchant.	String
orgMandateId optional	Mandate id upiRequestId in case of Full Delegate	String
recurrencePattern optional	Recurrence Pattern for link. Denotes at what frequency link can be executed in case of Full Delegate	ASPRESENTED
type	DELEGATE_LINK_REQUEST	DELEGATE_LINK_REQUEST
umn optional	umn for FULL Delegate Authorisation.	String
validityEnd optional	Date until which link will be active.	String with proper date format YYYY/MM/DD
documentType optional	The document type used for linking only in case of FULL Delegation	AADHAAR, PASSPORT, VOTER_ID, NREGA, DRIVING_LICENSE
documentId optional	The corresponding document number for selected documentType only in case of FULL Delegation	String
relation optional	The relation between Delegator and Delegatee.	Child, Parent, Spouse, Sibling, Domestic Employee, Small Business Employee

LINK STATUS CALLBACK

Callback to inform both the parties about the LINK status DELEGATE_LINK_STATUS Will sent to Delegator to convey the status of LINK request initiated. Will be triggered to both the party of any change is happened on the link like update or delink operation.

{
    "accountReferenceId": "A53b941d69fc4f73ae9052d455dae7",
    "action": "LINK",
    "actionStatus": "SUCCESS",
    "delegateeMobileNumber": "914720370267",
    "delegateeName": "KARAN",
    "delegateeVpa": "svpa0370267@yapl",
    "delegatorMobileNumber": "914612963979",
    "delegatorVpa": "4612963979@yapl",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Your transaction is successful",
    "gatewayResponseStatus": "LINKED",
    "gatewayTransactionId": "APYf583fb6c06904319920de317bd8b075f",
    "ifsc": "AABF0008032",
    "linkStatus": "LINKED",
    "linkType": "FULL",
    "linkedUpiRequestId": "APYf583fb6c06904319920de317bd8b075f",
    "merchantChannelId": "APLTEST",
    "merchantCustomerId": "amzn1.account.054812",
    "merchantId": "APLTEST",
    "type": "DELEGATE_LINK_STATUS",
    "umn": "bfe261ed85c14825ae44b31a090ad7d2@yapl",
    "userType": "DELEGATOR",
    "validityEnd": "2025/08/01"
}

Parameter	Description	Values
accountReferenceId optional	Unique reference ID for the selected Account in case of FULL linking.	String
bankAccountUniqueId optional	Unique id for the selected bank account for FULL Delegates	As passed in the request
action	Last action perfomed on the delegateLink	String
actionStatus	Status of the last action Performed	String
delegateeMobileNumber	Mobile number of Delegatee	String
delegateeName optional	Name of DELEGATEE	String
delegatorName optional	Name of DELEGATOR	String
delegateeVpa	secondary vpa which added as delegatee vpa	something@handle
delegatorMobileNumber optioanl	Mobile Number of DELEGATOR	String
delegatorVpa	Vpa of the customer linked to this account	something@handle
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayTransactionId	Transaction id returned by gateway	String
ifsc optional	Ifsc code of delegator bank account	Alphanumeric string. Maximum length is 11.
linkStatus	status of link	LINKED, DELINKED, EXPIRED, DECLINED, FAILURE, LINK_PENDING
linkType	type of linking	FULL or PARTIAL
linkedUpiRequestId	upiRequestId for linking call	String
merchantChannelId	Unique id for the channel via which request is made	String
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
merchantId	Unique id for merchant	String
type	DELEGATE_LINK_STATUS	DELEGATE_LINK_STATUS
umn optional	umn used for execution of mandate in case of Full Delegate	String
userType	type of user	DELEGATOR or DELEGATEE
validityEnd optional	Date before which mandate can be execute in case of Full Delegate	String with proper date format YYYY/MM/DD

TRANSACTION REQUEST CALLBACK

Partial Payment Callback [DELEGATE_PAY_REQUEST_RECEIVED]

Whenever a Payment Request is recieved by Delegator in case of PARTIAL Delegates this callback will be triggered.

{
    "amount": "2.00",
    "collectType": "DELEGATE",
    "delegateeVpa": "9606541955@yapl",
    "expiry": "2025-03-18T18:15:32+05:30",
    "gatewayTransactionId": "APYAP87322e244abfd9a8f43d4bec26bc66",
    "initiationMode": "00",
    "isVerifiedPayee": "false",
    "linkType": "PARTIAL",
    "linkedUpiRequestId": "APYa04928e859103d60f79146805842f221",
    "merchantChannelId": "AMAZONAPP",
    "merchantCustomerId": "amzn1.account.AGWIZYGJNU7WT25JL2EZKZIVT33A.617d",
    "merchantId": "AMAZON",
    "payeeMcc": "0000",
    "payeeName": "NIHARIKA NAVIN ACHARYA",
    "payeeVpa": "8618718035@yapl",
    "payerName": "ABC",
    "payerVpa": "7259933863@yapl",
    "purpose": "87",
    "refCategory": "00",
    "refUrl": "https://www.juspay.com/",
    "remarks": "UPI",
    "transactionTimestamp": "2025-03-18T18:05:32+05:30",
    "type": "DELEGATE_PAY_REQUEST_RECEIVED"
}

Parameter	Description	Values
amount	Amount for the payment	As passed in the request
collectType	Differentiates between a transaction collect request (TRANSACTION) or a mandate execution collect request (MANDATE).
delegateeVpa	secondary vpa which added as delegatee vpa	something@handle
expiry	Timestamp until which delegator can initiate pay	YYYY-MM-DDTHH:MM:SS+05:30
gatewayTransactionId	Transaction id returned by gateway	String
initiationMode	Inititation mode of Payment	String
isVerifiedPayee	Whether payee address is verified or not	True or False
linkType	type of linking	FULL or PARTIAL
linkedUpiRequestId	LinkRequestUpiRequestId of DelegateLink	String
merchantChannelId	Unique id for the channel via which request is made	String
merchantCustomerId	Merchant generated unique id for customer	String
merchantId	Unique id for merchant	String
payeeMcc	Merchant Category Code of the payee merchant. If Payee is a customer it will be "0000" else it will be a 4 digit numeric string.	String
payeeName	Name of the payee	String
payeeVpa	Vpa of the payee	something@handle
payerName	Name of the Payer (Delegator)	String
payerVpa	Delegator vpa used during linking	something@handle
purpose	purposeCode of api call	87 for PARTIAL Delegation and 59 for FULL Delegation
refCategory	Details for refUrl, whether it is 01 (advertisement), 02(Invoice). If nothing is passed, a default value of "00" is set up and same	String
refUrl	Invoice as sent by merchant or reference to the transaction in the form of url.	String
remarks	Remarks sent by customer for the collect request.	String
transactionTimestamp	Timestamp of when the transaction was attempted	YYYY-MM-DDTHH:MM:SS+05:30
type	DELEGATE_PAY_REQUEST_RECEIVED	DELEGATE_PAY_REQUEST_RECEIVED

TRANSACTION REQUEST EXPIRED CALLBACK

Partial Payment Request Expired Callback [DELEGATE_PAY_REQUEST_EXPIRED]

Whenever a Payment Request is recieved by Delegator expires in case of PARTIAL Delegates this callback will be triggered.

{
    "amount": "2.00",
    "collectType": "DELEGATE",
    "delegateeVpa": "9606541955@yapl",
    "expiry": "2025-03-18T18:15:32+05:30",
    "gatewayTransactionId": "APYAP87322e244abfd9a8f43d4bec26bc66",
    "initiationMode": "00",
    "isVerifiedPayee": "false",
    "linkType": "PARTIAL",
    "linkedUpiRequestId": "APYa04928e859103d60f79146805842f221",
    "merchantChannelId": "AMAZONAPP",
    "merchantCustomerId": "amzn1.account.AGWIZYGJNU7WT25JL2EZKZIVT33A.617d",
    "merchantId": "AMAZON",
    "payeeMcc": "0000",
    "payeeName": "NIHARIKA NAVIN ACHARYA",
    "payeeVpa": "8618718035@yapl",
    "payerName": "ABC",
    "payerVpa": "7259933863@yapl",
    "purpose": "87",
    "refCategory": "00",
    "refUrl": "https://www.juspay.com/",
    "remarks": "UPI",
    "transactionTimestamp": "2025-03-18T18:05:32+05:30",
    "type": "DELEGATE_PAY_REQUEST_EXPIRED"
}

Parameter	Description	Values
amount	Amount for the payment	As passed in the request
collectType	Differentiates between a transaction collect request (TRANSACTION) or a mandate execution collect request (MANDATE).
delegateeVpa	secondary vpa which added as delegatee vpa	something@handle
expiry	Timestamp until which delegator can initiate pay	YYYY-MM-DDTHH:MM:SS+05:30
gatewayTransactionId	Transaction id returned by gateway	String
initiationMode	Inititation mode of Payment	String
isVerifiedPayee	Whether payee address is verified or not	True or False
linkType	type of linking	FULL or PARTIAL
linkedUpiRequestId	LinkRequestUpiRequestId of DelegateLink	String
merchantChannelId	Unique id for the channel via which request is made	String
merchantCustomerId	Merchant generated unique id for customer	String
merchantId	Unique id for merchant	String
payeeMcc	Merchant Category Code of the payee merchant. If Payee is a customer it will be "0000" else it will be a 4 digit numeric string.	String
payeeName	Name of the payee	String
payeeVpa	Vpa of the payee	something@handle
payerName	Name of the Payer (Delegator)	String
payerVpa	Delegator vpa used during linking	something@handle
purpose	purposeCode of api call	87 for PARTIAL Delegation and 59 for FULL Delegation
refCategory	Details for refUrl, whether it is 01 (advertisement), 02(Invoice). If nothing is passed, a default value of "00" is set up and same	String
refUrl	Invoice as sent by merchant or reference to the transaction in the form of url.	String
remarks	Remarks sent by customer for the collect request.	String
transactionTimestamp	Timestamp of when the transaction was attempted	YYYY-MM-DDTHH:MM:SS+05:30
type	DELEGATE_PAY_REQUEST_EXPIRED	DELEGATE_PAY_REQUEST_EXPIRED

Delegate Pay

Endpoint - merchants/transactions/delegatePay

It will be async in case of Request.

#Request

curl --location {host}/api/{uri}/merchants/transactions/delegatePay' \
--header 'x-merchant-id: TEST' \
--header 'x-merchant-channel-id: TESTAPP' \
--header 'x-timestamp: 1549040555000' \
--header 'Content-Type: application/json' \
--data-raw '{
    "merchantCustomerId": "S7874196263335",
    "deviceFingerPrint": "6b5cdb2ac2b72cc3f5e4989a23a0503c61d7c312ca679f4f62e05fe6292d4c77",
    "merchantRequestId": "YAP16dd34dMR",
    "delegateeVpa": "p3887@yapl",
    "delegatorVpa": "p8991@yapl",
    "payeeVpa": "amazon@yapl",
    "amount": "10.00",
    "expiry": "10",
    "upiRequestId": "YAP16dd34d",
    "mcc": "0000",
    "payerName": "Himanshi",
    "payeeName": "ABC",
    "action": "REQUEST_PAY",
    "initiationMode": "00",
    "purpose": "87",
    "linkType": "PARTIAL",
    "remarks": "Send Money ppi pre approved test1",
    "currency": "INR",
    "transactionType": "PAY",
    "udfParameters": "{}"
}'

# Response: HTTP 200 OK

{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload": {
        "merchantChannelId": "AMAZONAPP",
        "amount": "1.00",
        "gatewayResponseStatus": "PENDING",
        "merchantId": "AMAZON",
        "refUrl": "https://www.juspay.com/",
        "delegateeVpa": "p4163@ypay",
        "gatewayResponseMessage": "Transaction is in pending state",
        "payerName": "Himanshi",
        "merchantRequestId": "YPCdaf9d87MR",
        "gatewayResponseCode": "01",
        "purpose": "87",
        "gatewayReferenceId": "422986499611",
        "gatewayTransactionId": "YPCdaf9d87",
        "payeeVpa": "amazon@yapl",
        "transactionTimestamp": "2024-08-16T14:32:29+05:30",
        "mcc": "5420",
        "delegatorVpa": "p0906@ypay",
        "merchantCustomerId": "AKHUT-S05",
        "expiryTimestamp": "2024-08-17T07:12:29+05:30",
        "remarks": "Send Money ppi pre approved test1"
        "gatewayPayerResponseCode": "00",
        "gatewayPayeeResponseCode": "00",
        "gatewayPayerReversalResponseCode": "00",
        "gatewayPayeeReversalResponseCode": "00",
    },
    "udfParameters": "{}"
}

action	Description
REQUEST_PAY	It will be done by delegatee to initiate a payment request to delegator.
APPROVE_PAY	It will be used by delegator to approve a delegate payment request.
DECLINE_PAY	It will be used by delegator to decline a delegate payment request.
ACK	It will be used to send a success acknowledgement of delegate payment request.
PAY	It will used to PAY a delegate payment via other PSP.
CHECK	It will be used to check the status of a transaction with a maximum of 3 CHECK calls allowed till expiry of payment request (can only be used in case of PARTIAL Delegation)

Request

Parameter	Description	Values
merchantCustomerId	Merchant generated unique profile id for customer. It will not be present if role passed in request is PAYEE and payeeVpa is of merchant.	Alphanumeric string with dot(.). Maximum length is 256.
deviceFingerPrint	Device fingerprint of the customer. It is required if mandate is initiatedBy Payer.	String
merchantRequestId optional	Merchant generated id for the mandate request	35 character alphanumeric unique id.
delegatorVpa	Vpa of the customer linked to this account	As passed in the request
delegateeVpa	secondary vpa which added as delegatee vpa	something@handle
payeeVpa	Vpa of the UPI user who receives the payment	something@handle
payerVpa optional	Delegator VPA which is to be used to make the payment	As passed in request.
payerName optional	Name of the payer.	String
payeeName optional	Name of the upi user who received the payment. Only if payment is done to a non A/C+IFSC vpa.	String
amount	Amount for the payment	As passed in the request
action	type of request	REQUEST, ACK, APPROVE, DECLINE,
bankAccountUniqueId optional	Unique id for the selected bank account	As passed in the request
accountReferenceId optional	Unique reference ID for the selected Account.	String
ifsc optional	Ifsc for the bank account as returned by NPCI	String
credBlock optional	Encrypted credblock containing user mpin	As returned by Common Library
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
remarksoptional	Any transaction summary	50 characters, alphanumeric, space and hyphen
expiry optional	Expiry of Linking Request (in minutes)	String (Max value can be 10)
currency optional	Currency code	String - INR
transactionType optional	Type of payment	String
linkType optional	type of linking	FULL or PARTIAL
transactionReference optional	Transaction reference id	String
refUrl optional	Invoice as sent by merchant or reference to the transaction in the form of url.
refCategory optional	Details for refUrl, whether it is 01 (advertisement), 02(Invoice). If nothing is passed, a default value of "00" is set up and same
mcc optional	Merchant category code	String
initiationMode optional	Defines the initiation mode of the transaction	Initiation Modes
purpose	Defines the purpose code of the transaction	87 for PARTIAL Delegation and 59 for FULL Delegation
udfParameters optional	Stringified JSON for udf parameters	JSON string
featureTags optional	This will be an array of feature values, each having it's own significance as decided by NPCI	Array of strings

Request Parameter table

Parameter	REQUEST_PAY	APPROVE_PAY	DECLINE_PAY	ACK	PAY
merchantCustomerId	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory
deviceFingerPrint	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory
merchantRequestId	Optional	Optional	Optional	Optional	Optional
payeeVpa	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory
delegatorVpa	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory
delegateeVpa	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory
payeeName	Optional	Optional	Optional	Optional	Optional
expiry	Mandatory	Not Required	Not Required	Not Required	Not Required
amount	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory
bankAccountUniqueId	Not Required	Mandatory	Not Required	Not Required	Mandatory
credBlock	Not Required	Mandatory	Not Required	Not Required	Mandatory
linkType	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory
upiRequestId	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory
remarks	Optional	Optional	Optional	Optional	Optional
initiationMode	Optional	Optional	Optional	Optional	Optional
purposeCode	Mandatory	Mandatory	Mandatory	Mandatory	Mandatory
refUrl	Optional	Optional	Optional	Optional	Optional
refCategory	Optional	Optional	Optional	Optional	Optional
transactionReference	Optional	Optional	Optional	Optional	Optional

Response

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer. It will not be present if role passed in request is PAYEE and payeeVpa is of merchant.	Alphanumeric string with dot(.). Maximum length is 256.
customerMobileNumber optional	Customer mobile number	12 digits mobile number string
amount	Amount for the payment	As passed in the request
expiryTimestamp	Timestamp of when the collect request will expire	YYYY-MM-DDTHH:MM:SS+05:30
payerVpa	Vpa on which collect request was triggered	As passed in request.
umn optional	Vpa used for execution of mandate.	String
mcc optional	Merchant category code	String
delegatorVpa optional	Delegator's Vpa	As passed in the request
delegateeVpa optional	Delegatee VPA	something@handle
payerName optional	Name of the upi user who initiates the payment.	String
refUrl optional	Invoice as sent by merchant or reference to the transaction in the form of url.
remarks optional	Any transaction summary	50 characters, alphanumeric, space and hyphen
purpose optional	Defines the purpose code of the transaction	Refer Request Structure section
transactionTimestamp	Timestamp of when the transaction was attempted	YYYY-MM-DDTHH:MM:SS+05:30
gatewayTransactionId	Transaction id returned by gateway	String
gatewayReferenceId optional	Reference id returned by the gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
udfParameters optional	Udf parameters as passed in the request	JSON string
gatewayPayerResponseCode optional	Response code returned by gateway	String
gatewayPayeeResponseCode optional	Response code returned by gateway	String
gatewayPayerReversalResponseCode optional	Response code returned by gateway	String
gatewayPayeeReversalResponseCode optional	Response code returned by gateway	String

TRANSACTION CONFIRMATION CALLBACK - Delegatee

CallBack For transaction Confirmation to Delegatee DELEGATEE_DEBITED_VIA_PAY (P2P) , DELEGATEE_DEBITED_FOR_MERCHANT_VIA_PAY (P2M)

{
    "amount": "1.00",
    "collectType": "DELEGATE",
    "customResponse": "{}",
    "delegateeVpa": "svpa0370267@yapl",
    "delegatorVpa": "4612963979@yapl",
    "expiryTimestamp": "2025-03-19T13:05:30+05:30",
    "gatewayReferenceId": "507800078063",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Your transaction is successful",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayTransactionId": "JUS8f7839f",
    "initiationMode": "00",
    "linkType": "FULL",
    "merchantChannelId": "APLTEST",
    "merchantCustomerId": "amzn1.account.637188",
    "merchantId": "APLTEST",
    "merchantRequestId": "JUS8f7839fMRID1",
    "orgMandateId": "JUSf19bf39e2db34bc6a0dd7ef",
    "payeeMcc": "0000",
    "payeeName": "ABC",
    "payeeVpa": "amazon@yapl",
    "payerMerchantCustomerId": "amzn1.account.637188",
    "payerMobileNumber": "914720370267",
    "payerVpa": "svpa0370267@yapl",
    "purpose": "59",
    "refId": "JUS8f7839fMRID1",
    "refUrl": "https://www.juspay.com/",
    "transactionTimestamp": "2025-03-19T12:55:30+05:30",
    "type": "DELEGATEE_DEBITED_FOR_MERCHANT_VIA_PAY",
    "udfParameters": "{}",
    "umn": "ed365773c3384a0ab95f1b898ec69576@yapl"
}

Parameter	Description	Values
amount	Amount for the payment	As passed in the request
collectType optional	Differentiates between a transaction collect request (TRANSACTION) or a mandate execution collect request (MANDATE). DELEGATE in this case	String
customResponse	Stringified JSON parameter for future use.	Stringified Json
delegateeVpa	secondary vpa which added as delegatee vpa	something@handle
delegatorVpa	primary vpa which added as delegatee vpa	something@handle
expiryTimestamp	Link payment request expiry	YYYY-MM-DDTHH:MM:SS+05:30
gatewayReferenceId	Reference id returned by the gateway	String
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayTransactionId	Transaction id returned by gateway	String
initiationMode optional	Defines the initiation mode of the transaction	Initiation Modes
linkType optional	type of linking	FULL or PARTIAL
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId optional	Merchant generated unique profile id for customer. It will not be present if role passed in request is PAYEE and payeeVpa is of merchant.	Alphanumeric string with dot(.). Maximum length is 256. JSON string
merchantId	Unique id for the merchant as passed in request headers	String
merchantRequestId optional	Merchant generated id for the mandate request	35 character alphanumeric unique id.
orgMandateId optional	Mandate id upiRequestId in case of Full Delegate	String
payeeMcc	Merchant Category Code of the payee merchant. If Payee is a customer it will be "0000" else it will be a 4 digit numeric string.
payeeName optional	Name of the upi user who received the payment. Only if payment is done to a non A/C+IFSC vpa.	String
payeeVpa	Vpa of the customer who sent the collect request.
payerMerchantCustomerId optional	Merchant generated unique id for payer who received the request.	String
payerMobileNumber	Payer mobile number	12 digits mobile number string
payerVpa	Vpa on which collect request was triggered	As passed in request.
purpose	Defines the purpose code of the transaction	Refer Request Structure section
refId optional	referenceId as shared by merchant	String
refUrl optional	Invoice as sent by merchant or reference to the transaction in the form of url.
transactionTimestamp	Timestamp of when the transaction was attempted	YYYY-MM-DDTHH:MM:SS+05:30
type	DELEGATEE_DEBITED_FOR_MERCHANT_VIA_PAY, DELEGATEE_DEBITED_VIA_PAY	DELEGATEE_DEBITED_FOR_MERCHANT_VIA_PAY, DELEGATEE_DEBITED_VIA_PAY
udfParameters optional	Udf parameters as passed in the request	JSON string
umn optional	Vpa used for execution of mandate.	something@handle

TRANSACTION CONFIRMATION CALLBACK - Delegator

Will sent to Delegator for any payment done CUSTOMER_DEBITED_VIA_DELEGATE (P2P), CUSTOMER_DEBITED_FOR_MERCHANT_VIA_DELEGATE (P2M)

{
    "amount": "1.00",
    "bankAccountUniqueId": "58dec06b75ade81beed1656cbed64ea8440ce24a28cb240814589d1299e0dbed",
    "bankCode": "500004",
    "collectType": "DELEGATE",
    "customResponse": "{}",
    "delegateeVpa": "svpa0370267@yapl",
    "delegatorVpa": "4612963979@yapl",
    "expiryTimestamp": "2025-03-19T13:05:30+05:30",
    "gatewayReferenceId": "507800078064",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Your transaction is successful",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayTransactionId": "JUS8f7839f",
    "initiationMode": "00",
    "linkType": "FULL",
    "maskedAccountNumber": "XXXXXXXXXX254769",
    "merchantChannelId": "APLTEST",
    "merchantCustomerId": "amzn1.account.054812",
    "merchantId": "APLTEST",
    "orgMandateId": "JUSf19bf39e2db34bc6a0dd7ef",
    "payeeAcType": "SAVINGS",
    "payeeIfsc": "YESB0APLUPI",
    "payeeMcc": "5413",
    "payeeName": "ABC",
    "payeeVpa": "amazon@yapl",
    "payerAcType": "SAVINGS",
    "payerMerchantCustomerId": "amzn1.account.054812",
    "payerMobileNumber": "914612963979",
    "payerVpa": "ed365773c3384a0ab95f1b898ec69576@yapl",
    "purpose": "59",
    "refId": "JUS8f7839fMRID1",
    "refUrl": "https://www.juspay.com/",
    "transactionTimestamp": "2025-03-19T12:55:30+05:30",
    "type": "CUSTOMER_DEBITED_FOR_MERCHANT_VIA_DELEGATE",
    "umn": "ed365773c3384a0ab95f1b898ec69576@yapl"
}

Parameter	Description	Values
amount	Amount for the payment	As passed in the request
bankAccountUniqueId	Unique id for the selected bank account	As passed in the request
bankCode	Bank code of the account which was used	Valid bank IIN
collectType optional	Differentiates between a transaction collect request (TRANSACTION) or a mandate execution collect request (MANDATE). DELEGATE in this case	String
customResponse	Stringified JSON parameter for future use.	Stringified Json
delegateeVpa	secondary vpa which added as delegatee vpa	something@handle
delegatorVpa	primary vpa which added as delegatee vpa	something@handle
expiryTimestamp	Link payment request expiry	YYYY-MM-DDTHH:MM:SS+05:30
gatewayReferenceId	Reference id returned by the gateway	String
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayTransactionId	Transaction id returned by gateway	String
initiationMode optional	Defines the initiation mode of the transaction	Initiation Modes
linkType	type of linking	FULL or PARTIAL
maskedAccountNumber	Masked account number of the account which was used	XXXX123456
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId optional	Merchant generated unique profile id for customer. It will not be present if role passed in request is PAYEE and payeeVpa is of merchant.	Alphanumeric string with dot(.). Maximum length is 256. JSON string
merchantId	Unique id for the merchant as passed in request headers	String
merchantRequestId optional	Merchant generated id for the mandate request	35 character alphanumeric unique id.
orgMandateId optional	Mandate id upiRequestId in case of Full Delegate	String
payeeActype optional	Account type of the customer who received the payment	String
payeeMcc	Merchant Category Code of the payee merchant. If Payee is a customer it will be "0000" else it will be a 4 digit numeric string.
payeeName optional	Name of the upi user who received the payment. Only if payment is done to a non A/C+IFSC vpa.	String
payeeVpa	Vpa of the customer who sent the collect request.
payerMerchantCustomerId optional	Merchant generated unique id for customer who sent the payment. Only if it is an onus transaction	String
payerMobileNumber	Payer mobile number	12 digits mobile number string
payerVpa	Vpa on which collect request was triggered	As passed in request.
purpose	Defines the purpose code of the transaction	Refer Request Structure section
refId optional	referenceId as shared by merchant	String
refUrl	Invoice as sent by merchant or reference to the transaction in the form of url.
transactionTimestamp	Timestamp of when the transaction was attempted	YYYY-MM-DDTHH:MM:SS+05:30
type	CUSTOMER_DEBITED_VIA_DELEGATE, CUSTOMER_DEBITED_FOR_MERCHANT_VIA_DELEGATE	CUSTOMER_DEBITED_VIA_DELEGATE, CUSTOMER_DEBITED_FOR_MERCHANT_VIA_DELEGATE
umn optional	Vpa used for execution of mandate.	something@handle
udfParameters optional	Udf parameters as passed in the request	JSON string

List Pending Links

This will be used to fetch all the links pending at the delegatee end.

Endpoint - merchant/customer/delegates/listPendingLinks

#Request

curl --location '{host}/api/{uri}/merchants/customer/delegates/listPendingLinks' \
--header 'Content-Type: application/json' \
--header 'x-merchant-id: TEST' \
--header 'x-merchant-channel-id: TESTAPP' \
--header 'x-timestamp: 1549040555000' \
--data '{
    "merchantCustomerId": "P7870468342262"
}'

# Response: HTTP 200 OK

{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload": {
        "merchantChannelId": "TESTAPP",
        "merchantId": "TEST",
        "customerMobileNumber": "919205337736",
        "merchantCustomerId": "P7870468342262",
        "pendingLinkRequest": [
            {
                "delegateeVpa": "p8991@yapl",
                "gatewayTransactionId": "YAP0a679fc",
                "linkedMobileNumber": "915344449869",
                "linkType": "PARTIAL",
                "delegatorVpa": "p3116@yapl",
                "linkedName": "KARAN",
                "expiryTimestamp": "2024-11-25T18:55:14.143477",
                "userType": "DELEGATOR"
            },
            {
                "delegateeVpa": "p8991@yapl",
                "gatewayTransactionId": "YAPf1dac21",
                "linkedMobileNumber": "918739111821",
                "linkType": "PARTIAL",
                "delegatorVpa": "p9913@yapl",
                "linkedName": "KARAN",
                "expiryTimestamp": "2024-11-25T19:02:14.192654",
                "userType": "DELEGATOR"
            }
        ]
    }
}

Request Body

Parameter	Description	Values
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response Body [WIP]

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
customerMobileNumber optional	Customer mobile number	12 digits mobile number string
delegatorVpa	Delegatee Vpa	something@handle
delegateeVpa	Delegatee Vpa	something@handle
userType	user Type i.e Delegator Delegatee	DELEGATOR & DELEGATEE
expiryTimestamp	Timestamp of when the link request will expire	YYYY-MM-DDTHH:MM:SS+05:30
gatewayTransactionId	Transaction id returned by gateway for the request	String
umn optional	umn in case of FULL DELEGATE	string
ifsc optional	Ifsc for the bank account as returned by NPCI	String
bankCode optional	IIN of the bank for the account	String
maskedAccountNumber optional	Masked account number as returned by NPCI	String
limit optional	limit amount in case of FULL DELEGATE	String
validityEnd optional	Date befor which FULL DELEGATE can be execute	String with proper date format YYYY/MM/DD
linkType	type of linking	FULL or PARTIAL
linkedName optional	Linked Name of that delegate Link	String
linkedMobileNumber optional	Moblile Number of the Delegator	String
udfParameters optional	Udf parameters as passed in the request	JSON string

List Pending Payment

This will be used to fetch all the pending payment request at the delegator end. Endpoint - /merchants/transactions/delegates/listPending

#Request

curl --location '{host}/api/{uri}/merchants/transactions/delegates/listPending' \
--header 'Content-Type: application/json' \
--header 'x-merchant-id: TEST' \
--header 'x-merchant-channel-id: TESTAPP' \
--header 'x-timestamp: 1549040555000' \
--header 'x-merhant-signature: 342AE54CEC......' \
--header 'x-api-version: 1' \
--data '{
    "merchantCustomerId": "P7870468342262"
}'

# Response: HTTP 200 OK

{
  "status": "SUCCESS",
  "responseMessage": "SUCCESS",
  "responseCode": "SUCCESS",
  "payload" : {
     "merchantChannelId": "TESTAPP",
      "merchantId": "TEST",
      "customerMobileNumber": "919205337736",
      "merchantCustomerId": "P7870468342262",
      "pendingDelegatePayments" : [
        {
          "amount" : "10.00",
          "expiry": "2024-11-25T18:55:14.143477",
          "gatewayTransactionId": "YAP0a679fc",
          "isVerifiedPayee" : "True",
          "isMarkedSpam" : "False",
          "payeeMcc" : "0000",
          "payeeName" : "ALICE",
          "payeeVpa" : "something@handle",
          "payerVpa" : "something@handle",
          "refUrl": "https://www.juspay.com/",
          "refCategory" : "00",
          "remarks" : "Testing Delegate Payments",
          "delegateeVpa" : "something@handle",
          "collectType" : "DELEGATE"
        }
      ]
    }
}

Request Body

Parameter	Description	Values
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response Body [WIP]

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
collectType	Differentiates between a transaction collect request (TRANSACTION) or a mandate execution collect request (MANDATE).
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
customerMobileNumber	Customer mobile number	12 digits mobile number string
amount	Amount for the payment	String
expiry	Timestamp of when the link request will expire	YYYY-MM-DDTHH:MM:SS+05:30
gatewayTransactionId	Transaction id returned by gateway for the request	String
isVerifiedPayee	Flag if the payee is a verified vpa	True or False
isMarkedSpam	Flag if the payee is marked as spam	True or False
payeeMcc	Merchant Category Code of the payee merchant. If Payee is a customer it will be "0000" else it will be a 4 digit numeric string.	String
payeeName	Name of the upi user who receives the payment. Only if payment is done to a non A/C+IFSC vpa.	String
payeeVpa	Vpa of the upi user who receives the payment	something@handle
payerVpa	VPA of the customer to be used for payment (Delegator in this case)	something@handle
refUrl	Invoice as sent by merchant or reference to the transaction in the form of url.
refCategory optional	Details for refUrl, whether it is 01 (advertisement), 02(Invoice). If nothing is passed, a default value of "00" is set up and same
remarks	Any transaction summary	50 characters, alphanumeric, space and hyphen
delegateeVpa	secondary vpa which added as delegatee vpa	something@handle
udfParameters optional	Udf parameters as passed in the request	JSON string

Fetch Customer Info

#Request

curl --location '{host}/api/{uri}/merchants/customer/info' \
--header 'Content-Type: application/json' \
--header 'x-merchant-id: TEST' \
--header 'x-merchant-channel-id: TESTAPP' \
--header 'x-timestamp: 1549040555000' \
--header 'x-merhant-signature: 342AE54CEC...' \
--header 'x-api-version: 4' \
--data '{
    "merchantCustomerId": "test-merchantcustomer-1",
    "udfParameters": null
}'

# Response: HTTP 200 OK

{
    "status": "SUCCESS",
    "responseMessage": "SUCCESS",
    "responseCode": "SUCCESS",
    "payload": {
        "merchantChannelId": "AMAZONAPP",
        "merchantId": "AMAZON",
        "vpaAccounts": [
            {
                "vpa": "p886@ypay",
                "account": {
                    "maskedAccountNumber": "XXXXX0100008508",
                    "otpLength": "6",
                    "mpinSet": "false",
                    "atmPinLength": "4",
                    "referenceId": "A7a23cbf09e94d038ea7ee188ac678",
                    "name": "RENU  JAIN",
                    "ifsc": "BankIFSC",
                    "type": "SAVINGS",
                    "bankCode": "BankCode",
                    "mpinLength": "6",
                    "bankAccountUniqueId": "c8c04dcd1893cceb0f34b579574626e4265e409e742099b1a1088dc77e88fff9",
                    "bankName": "BankName"
                },
                "isDefault": true
            }
        ],
        "delegateInfo": {
            "delegateLinks": [
                {
                    "vpa": "p886@ypay",
                    "fullDelegationDetails": {
                        "maskedAccountNumber": "XXXXX0100008508",
                        "cycleEnd": "CycleEnd TimeStamp",
                        "validityEnd": "ValidityEnd TimeStamp",
                        "amountUsed": "0",
                        "umn": "45aaf8fe375241d5a6dc14912342a4eb@ypay",
                        "ifsc": "BankIFSC",
                        "limit": "1000.00",
                        "bankCode": "BankCode",
                        "bankName": "BankName"
                    },
                    "linkedMobileNumber": "913774505112",
                    "linkType": "FULL",
                    "linkedName": "KARAN",
                    "linkedVpa": "p0893@ypay",
                    "userType": "DELEGATOR"
                }
            ],
            "delegateVpas": [
                "p8086@ypay"
            ]
        },
        "upiNumbers": [],
        "customerMobileNumber": "919817925632",
        "deviceDetails": {
            "manufacturer": "Samsu",
            "packageName": "com.amazon.AmazonIN",
            "ssid": "2336592311",
            "deviceFingerPrint": "abc71bd8d7094bf55d1259c97c2899f2d6f0cfd4fe50417c02704a2b1f99f6b5",
            "os": "ANDROID",
            "model": "Galaxy",
            "version": "11",
            "deviceId": "test-device-763229"
        },
        "primaryVpa": "p8086@ypay",
        "merchantCustomerId": "P7874256651163"
    }
}

This api returns the registration and account information maintained at the PSP for the customer along with the Delegate Info which contains the Delegate Vpas and Delegate Links. Merchants can use this api to periodically sync data with the PSP.

Note You can add --header 'x-api-version: 4' to get UpiNumbers along with the DelegateInfo linked with the merchantCustomer.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
udfParameters optional	Stringified JSON for udf parameters	JSON string

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number as per device binding	12 digits mobile number string
deviceFingerPrint	Fingerprint of the customer device	String
deviceId	Unique identifier for the customer device	String
manufacturer	Manufacturer of the customer device	String
model	Model of the customer device	String
version	Version of the operating system on the customer device	String
os	Operating system running on the customer device	String
ssid	Identifier of the SIM used to send the SMS	String
packageName	Package name of the UPI application	String
vpaAccounts	Vpa account mapping of the customer	Array of vpa accounts
delegateInfo optional	DelegateInfo of the Customer	array of DelegateLinks and DelegateVpas
DelegateLinks	Contains the link info of that DelegateLink	array of Objects with the DelegateLink info
DelegateVpas	Contains All the Vpas which are active for Delegate Payments	Array of Vpas
udfParameters optional	Udf parameters as passed in the request	JSON string
Primary Vpa optional	Vpa in case of User is a Delegator	String
Upi Numbers	Upi Numbers Active for that merchantCustomerId	array of Strings

Mobile Number Revocation List Deactivation Callbacks

Revoke Active Mandates

• Since the merchantCustomer is inactive, any execution or update will fail with QS (PAYER PROFILE DOES NOT EXIST).
• Notify merchant with MANDATE_STATUS_UPDATE callback.

{
  "amount": "100.00",
  "amountRule": "EXACT",
  "gatewayMandateId": "APL71f7d43bdf64d72d9saddfded",
  "gatewayResponseCode" : "00",
  "gatewayResponseMessage": "Mandate Validity End is Over",
  "gatewayResponseStatus": "SUCCESS",
  "initiatedBy": "PAYER",
  "mandateName": "merchant mandate",
  "merchantChannelId": "APL",
  "merchantCustomerId": "DEMO-CUST-1234",
  "merchantId": "APL",
  "orgMandateId": "APLMsleiuryufhuhsoisdjfadb48003sdaa0",
  "payeeVpa": "test@apl",
  "payerRevocable": "true",
  "payerVpa": "9962463212@apl",
  "purpose": "UNKNOWN",
  "recurrencePattern": "MONTHLY",
  "role": "PAYER",
  "shareToPayee": "true",
  "status": "DORMANT",
  "subMerchantChannelId" : "<SubMerchantId>",
  "subMerchantId" : "<SubMerchantId>",
  "transactionType": "UPI_MANDATE",
  "type": "MANDATE_STATUS_UPDATE",
  "umn": "uniqueMandateNumber@apl",
  "validityEnd": "2020/06/05",
  "validityStart": "2020/06/04"
}

Parameter	Description
amount	Amount of Mandate. Numeric string with two decimals.
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount. If amountRule is EXACT, then mandate should always be executed for the same amount.
gatewayMandateId	Refers to the upiRequestId used during creation of the mandate.
gatewayResponseCode	Response code returned by gateway
gatewayResponseMessage	Response message returned by the gateway for the mandate.
gatewayResponseStatus	Response status returned by the gateway for the mandate.
initiatedBy	Describes whether PAYER or PAYEE initiated the mandate.
mandateName	Name of the mandate as provided by the initiator.
merchantChannelId	Unique ID for the channel via which the mandate request is made.
merchantCustomerId	Merchant-generated unique ID for the customer.
merchantId	Unique identifier for the merchant.
orgMandateId	Refers to the original upiRequestId used during creation of the mandate.
payeeVpa	Virtual Payment Address (VPA) of the payee involved in the mandate.
payerRevocable	Indicates whether the mandate can be revoked by the payer. If set to true, the payer can revoke the mandate. Default is true for recurring mandates.
payerVpa	Virtual Payment Address (VPA) of the payer involved in the mandate.
purpose	Purpose code associated with the mandate, indicating the reason for the transaction.
recurrencePattern	Recurrence pattern for the mandate. Possible values include ONETIME, DAILY, WEEKLY, etc.
role	Role of the customer in the mandate. Either PAYER or PAYEE.
shareToPayee	Indicates whether the mandate should be shared with the payee. Default is true.
status	Current status of the mandate. Possible values include DORMANT.
subMerchantChannelId	Unique ID for the channel via which the mandate request is made.
subMerchantId	Unique identifier for the merchant.
transactionType	Type of transaction. For mandate creation and updates, this will be UPI_MANDATE.
type	Callback event type. For status updates, this will be MANDATE_STATUS_UPDATE.
umn	VPA used for execution of the mandate.
validityEnd	Date until which the mandate can be executed.
validityStart	Date after which the mandate can be executed.

Deregister UPI Lite Account

• Since merchantCustomer wont be active so any execution and updation will fail with PAYER PROFILE DOES NOT EXIST
• Notify the merchant with a UPI_LITE_STATUS_UPDATE callback

{
  "lrn": "0000000123435874397974928758",
  "merchantChannelId": "APL",
  "merchantCustomerId": "DEMO-CUST-1234",
  "merchantId": "AMAZON",
  "remarks" : "Account marked as dormant",
  "status": "DORMANT",
  "type": "UPI_LITE_STATUS_UPDATE"
}

Parameter	Description
lrn	Lite Reference Number associated with the wallet linked to the account number.
merchantChannelId	Unique ID for the merchant channel, as passed in the request headers.
merchantCustomerId	Merchant-generated unique profile ID for the customer, as passed in the request.
merchantId	Unique ID for the merchant, as passed in the request headers.
remarks	Any remarks or summary related to the status update.
status	Current status of the Lite account. Possible values include ACTIVE, DORMANT, etc.
type	Callback event type. For Lite account status updates, this will be UPI_LITE_STATUS_UPDATE.

Send Callback to Merchant

• Notify the merchant with a BLOCKED callback event.

{
  "merchantId": "APL12345",
  "subMerchantId": "APL_SUB6789",
  "merchantChannelId": "APL_CHANNEL_01",
  "subMerchantChannelId": "APL_SUB_CHANNEL_02",
  "merchantCustomerId": "DEMO-CUST-1234",
  "customerMobileNumber": "9876543210",
  "customerVpas": ["john.doe@apl"],
  "dateOfDisconnection": "2025-07-15",
  "disconnectionReason": "User requested account deactivation",
  "type": "MNRL",
  "action": "BLOCKED"
}

Parameter	Description
merchantId	Unique ID for the merchant, as passed in the request headers.
subMerchantId	Unique ID for the sub-merchant under the primary merchant.
merchantChannelId	Unique ID for the channel through which the merchant is registered, as passed in the request headers.
subMerchantChannelId	Unique ID for the channel through which the sub-merchant is registered.
merchantCustomerId	Unique customer profile ID generated by the merchant.
customerMobileNumber	Mobile number associated with the customer being deregistered.
customerVpas	List of Virtual Payment Addresses (VPAs) linked to the customer that are being deregistered.
dateOfDisconnection	Date on which the customer was disconnected from the mandate or recurring Lite setup. Format: YYYY-MM-DD.
disconnectionReason	Reason for which the customer was deregistered.
type	Callback event type. For mandate/Lite deregistration updates, this will be MNRL.
action	BLOCKED

Mapper Callback - UPI_NUMBER_MAPPER

{
  "customerMobileNumber": "9876543210",
  "merchantChannelId": "APL_CHANNEL_01",
  "merchantCustomerId": "DEMO-CUST-1234",
  "merchantId": "APL12345",
  "status" : "SUCCESS",
  "type" : "UPI_NUMBER_MAPPER",
  "upiNumber" : "987654321",
  "upiNumberStatus" : "DORMANT",
  "vpa" : "john.doe@apl",
  "customResponse" : "{}"
}

Parameter	Description
customerMobileNumber	Mobile number associated with the customer being deregistered.
merchantChannelId	Unique ID for the channel through which the merchant is registered, as passed in the request headers.
merchantCustomerId	Unique customer profile ID generated by the merchant.
merchantId	Unique ID for the merchant, as passed in the request headers.
status	Status of the mapper reactication
type	Callback event type. For upi number mapper updates, this will be UPI_NUMBER_MAPPER.
upiNumber	Number mapped to a customer's VPA that is unique to the customer across the UPI ecosystem
upiNumberStatus	Status of the Upi Number
vpa	Vpa linked/to be linked with the provided Upi Number
customResponse	Stringified JSON parameter for future use.

Mobile Number Revocation List Reactivation Callbacks

Mandate Callback - MANDATE_STATUS_UPDATE

{
  "amount" : "500" ,
  "amountRule": "EXACT",
  "gatewayMandateId": "APL71f7d43bdf64d72d9saddfded",
  "gatewayResponseMessage": "Mandate Validity End is Over",
  "gatewayResponseCode": "00",
  "gatewayResponseStatus": "SUCCESS",
  "initiatedBy": "PAYER",
  "mandateName": "merchant mandate",
  "merchantChannelId": "APL",
  "merchantCustomerId": "DEMO-CUST-1234",
  "merchantId": "APL",
  "orgMandateId": "APLMsleiuryufhuhsoisdjfadb48003sdaa0",
  "payeeVpa": "test@apl",
  "payerRevocable": "true",
  "payerVpa": "9962463212@apl",
  "purpose": "UNKNOWN",
  "recurrencePattern": "MONTHLY",
  "role": "PAYER",
  "shareToPayee": "true",
  "status": "SUCCESS",
  "subMerchantChannelId" : "<Sub-MerchantChannelId>",
  "subMerchantId" : "<Sub-MerchantId>",
  "transactionType": "UPI_MANDATE",
  "type": "MANDATE_STATUS_UPDATE",
  "umn": "uniqueMandateNumber@apl",
  "validityEnd": "2020-06-05",
  "validityStart": "2020-06-04"
}

Parameter	Description
amount	Amount of Mandate. Numeric string with two decimals.
amountRule	Rule on Mandate Amount. If amountRule is MAX, then mandate can be executed for amount less than or equal to the passed amount. If amountRule is EXACT, then mandate should always be executed for the same amount.
gatewayMandateId	Refers to the upiRequestId used during creation of the mandate.
gatewayResponseCode	Response code returned by gateway
gatewayResponseMessage	Response message returned by the gateway for the mandate.
gatewayResponseStatus	Response status returned by the gateway for the mandate.
initiatedBy	Describes whether PAYER or PAYEE initiated the mandate.
mandateName	Name of the mandate as provided by the initiator.
merchantChannelId	Unique ID for the channel via which the mandate request is made.
merchantCustomerId	Merchant-generated unique ID for the customer.
merchantId	Unique identifier for the merchant.
orgMandateId	Refers to the original upiRequestId used during creation of the mandate.
payeeVpa	Virtual Payment Address (VPA) of the payee involved in the mandate.
payerRevocable	Indicates whether the mandate can be revoked by the payer. If set to true, the payer can revoke the mandate. Default is true for recurring mandates.
payerVpa	Virtual Payment Address (VPA) of the payer involved in the mandate.
purpose	Purpose code associated with the mandate, indicating the reason for the transaction.
recurrencePattern	Recurrence pattern for the mandate. Possible values include ONETIME, DAILY, WEEKLY, etc.
role	Role of the customer in the mandate. Either PAYER or PAYEE.
shareToPayee	Indicates whether the mandate should be shared with the payee. Default is true.
status	Current status of the mandate. Possible values include ACTIVE, EXPIRED, etc.
subMerchantChannelId	Unique ID for the channel via which the mandate request is made.
subMerchantId	Unique identifier for the merchant.
transactionType	Type of transaction. For mandate creation and updates, this will be UPI_MANDATE.
type	Callback event type. For status updates, this will be MANDATE_STATUS_UPDATE.
umn	VPA used for execution of the mandate.
validityEnd	Date until which the mandate can be executed.
validityStart	Date after which the mandate can be executed.

gatewayResponseCode	gatewayResponseStatus	Description
JPMUP	UNPAUSE	Mandate is Unpaused.
JPMP	PAUSED	Mandate is paused.
JPMC	COMPLETED	Mandate is completed.
JPMS	SUCCESS	Mandate is active.
JPMD	DORMANT	Mandate is dormant.
JPMR	REVOKED	Mandate is revoked.
Else	FAILURE	Any other reason.

LiteAccount Callback - UPI_LITE_STATUS_UPDATE

{
  "lrn": "0000000123435874397974928758"
  "merchantChannelId": "APL",
  "merchantCustomerId": "DEMO-CUST-1234",
  "merchantId": "AMAZON"
  "remarks" : "Account marked as dormant"
  "status": "ACTIVE"
  "type": "UPI_LITE_STATUS_UPDATE"
}

Parameter	Description
active	Indicates whether the Lite account is currently active. Possible values are true or false.
lrn	Lite Reference Number associated with the wallet linked to the account number.
merchantChannelId	Unique ID for the merchant channel, as passed in the request headers.
merchantCustomerId	Merchant-generated unique profile ID for the customer, as passed in the request.
merchantId	Unique ID for the merchant, as passed in the request headers.
remarks	Any remarks or summary related to the status update.
status	Current status of the Lite account. Possible values include ACTIVE, DORMANT, etc.
type	Callback event type. For Lite account status updates, this will be UPI_LITE_STATUS_UPDATE.

CustomerReRegistered Callback - UNBLOCKED

{
  "merchantId": "APL12345",
  "subMerchantId": "APL_SUB6789",
  "merchantChannelId": "APL_CHANNEL_01",
  "subMerchantChannelId": "APL_SUB_CHANNEL_02",
  "merchantCustomerId": "DEMO-CUST-1234",
  "customerMobileNumber": "9876543210",
  "customerVpas": ["john.doe@apl"],
  "dateOfDisconnection": "2025-07-15",
  "reactivationReason": "User requested account reactivation"
  "type": "MNRL",
  "action": "UNBLOCKED",
  "initiatedBy": "MNRL"
}

Parameter	Description
merchantId	Unique ID for the merchant, as passed in the request headers.
subMerchantId	Unique ID for the sub-merchant under the primary merchant.
merchantChannelId	Unique ID for the channel through which the merchant is registered, as passed in the request headers.
subMerchantChannelId	Unique ID for the channel through which the sub-merchant is registered.
merchantCustomerId	Unique customer profile ID generated by the merchant.
customerMobileNumber	Mobile number associated with the customer being deregistered.
customerVpas	List of Virtual Payment Addresses (VPAs) linked to the customer that are being deregistered.
dateOfDisconnection	Date on which the customer was disconnected from the mandate or recurring Lite setup. Format: YYYY-MM-DD.
reactivationReason	Reason for which the customer is reregistering.
type	Callback event type. For customer registration updates, this will be MNRL.
initiatedBy	Entity that initiated the reactivation request , this will be MNRL
action.	UNBLOCKED

Mapper Callback - UPI_NUMBER_MAPPER

{
  "customerMobileNumber": "9876543210",
  "merchantChannelId": "APL_CHANNEL_01",
  "merchantCustomerId": "DEMO-CUST-1234",
  "merchantId": "APL12345",
  "status" : "SUCCESS",
  "type" : "UPI_NUMBER_MAPPER",
  "upiNumber" : "987654321",
  "upiNumberStatus" : "ACTIVE",
  "vpa" : "john.doe@apl",
  "customResponse" : "{}"
}

Parameter	Description
customerMobileNumber	Mobile number associated with the customer being deregistered.
merchantChannelId	Unique ID for the channel through which the merchant is registered, as passed in the request headers.
merchantCustomerId	Unique customer profile ID generated by the merchant.
merchantId	Unique ID for the merchant, as passed in the request headers.
status	Status of the mapper reactication
type	Callback event type. For upi number mapper updates, this will be UPI_NUMBER_MAPPER.
upiNumber	Number mapped to a customer's VPA that is unique to the customer across the UPI ecosystem
upiNumberStatus	Status of the Upi Number
vpa	Vpa linked/to be linked with the provided Upi Number
customResponse	Stringified JSON parameter for future use.

Multi-Signatory Accounts

The below APIs should be called post the Device Binding is completed.

Fetch Accounts

curl -L -X POST '{{host}}/api/n2/merchants/accounts/fetch' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "bankCode": "607153",
  "purpose" : "AV",
  "initiator" "MAKER",
  "udfParameters": "{}",
  "packageName" : "in.amazon.mShop.android.shopping"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "919988776655",
    "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Accounts fetched successfully",
    "accounts": [{
      "bankCode": "607153",
      "bankName": "BankName",
      "maskedAccountNumber": "XXXX8796",
      "mpinLength": "6",
      "mpinSet": "true",
      "otpLength": "6",
      "atmPinLength": "4",
      "type": "SAVINGS",
      "ifsc": "BankIFSC",
      "name": "Ram Singh",
      "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf"
    }],
    "vpaSuggestions": ["vpa@handle", "vpa2@handle"]
  },
  "udfParameters": "{}"
}

This api fetches customer accounts from NPCI. accounts will be present in the response only if gatewayResponseCode = "00". In case there are one or more accounts fetched, vpaSuggestions will be sent in response.

Note: In case merchant retries this api, the accounts will be fetched from NPCI again.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
deviceFingerPrint	Device fingerprint of the customer	String
bankCode	Bank code (IIN) of selected bank	String
purpose	Defines the purpose code of the transaction	AV in this case
initiator	User who initiates the request	MAKER/ CHECKER in this case
udfParameters optional	Stringified JSON for udf parameters	JSON string
accountType optional	Account Type(In CC TPAP should send accountType as CREDIT, in other cases they can skip sending this field)	String
packageName optional	Package name of the UPI application	String

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Mobile number of the customer	12 digits mobile number string
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
accounts optional	Bank accounts as returned by NPCI for the customer mobile number	Array of accounts
vpaSuggestions optional	Vpa suggestions for the bank accounts fetched	Array of strings
udfParameters optional	Udf parameters as passed in the request	JSON string

Set/Reset MPIN

curl -L -X POST '{{host}}/api/n2/merchants/accounts/setMpin' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "bankAccountUniqueId": "6adc62db0fcb2d2b8950cc0b4925d1f145df58c3e374e1c3e155b57c12a5c0bf",
  "customerVpa": "vpa@handle",
  "credBlock": "{\"otpcred\":{\"type\":\"OTP\",\"subType\":\"SMS\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|IMQQwH6pcsw/cXNOWy...9gnNkA/o8CWGOQ==\",\"code\":\"NPCI\"}},\"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|qhRJ...d9Be7AQg2IFg==\",\"code\":\"NPCI\"}}}",
  "card": "123456",
  "expiry": "0122",
  "udfParameters": "{}",
  "purpose": "AV",
  "clVersion" : "2.0",
  "initiator" : "MAKER",
  "customerId": "3123123"
  "packageName": "in.amazon.mShop.android.shopping"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "SUCCESS",
  "responseMessage": "SUCCESS",
  "payload": {
    "merchantId": "TEST",
    "merchantChannelId": "TESTAPP",
    "merchantCustomerId": "test-merchantcustomer-1",
    "customerMobileNumber": "919988776655",
    "bankAccountUniqueId": "fb96f8b2b1ab0c070d0d894fd2e577a3d6129882c874e3700505eebfb8070",
    "bankCode": "123456",
    "customerVpa": "vpa@handle",
    "maskedAccountNumber": "XXXX123456",
    "gatewayTransactionId": "AUTef1a2908395239df56663244f8c7deaa",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Set/Reset MPIN successful"
  },
  "udfParameters": "{}"
}

This api can be used to set/reset mpin for a customer bank account. Set/reset mpin is successful only when gatewayResponseCode = "00".

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
deviceFingerPrint	Device fingerprint of the customer	String
purpose	Purpose code to be passed in case of Multi-Signatory accounts	AV
clVersion	ClVersion - use GetCLVersion for exact value of the field clVersion	String
initiator	User who initiates the request	MAKER/ CHECKER in this case
customerId	for CHECKER - "First4DigitsofUserID+NumericValuesOfPAN+First4DigitsOfA/Cnum", for Maker - First 4 characters of User ID to be added	String
upiRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
bankAccountUniqueId	Unique id for the selected bank account	bankAccountUniqueId in the response of Fetch Accounts api call.
customerVpa	VPA of the customer linked to the account	something@handle
credBlock	Encrypted credblock for containing user otp and mpin	As returned by Common Library
card	Last 6 digits of the debit card	String
expiry	Expiry of the debit card	String in format MMYY (pass 0149 for Maestro cards)
udfParameters optional	Stringified JSON for udf parameters	JSON string
packageName optional	Package name of the UPI application	String

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
bankAccountUniqueId	Unique id for the selected bank account	As passed in the request
bankCode	Bank code of the account which was used	Valid bank IIN
customerVpa	Vpa of the customer linked to this account	As passed in the request
maskedAccountNumber	Masked account number of the account which was used	XXXX123456
gatewayTransactionId	Transaction id returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseMessage	Response message for code returned by gateway	String
udfParameters optional	Udf parameters as passed in the request	JSON string

gatewayResponseCode	Description
00	Success.
XN	Failure. No Card Record found.
XL	Failure. Expired Card Details.
ZR	Failure. Invalid / Incorrect OTP.
ZS	Failure. OTP Time expired.
G74	Incorrect mobile registration format used.
Else	Failure. Any other reason.

Signatory Pay (Maker)

curl -L -X POST '{{host}}/api/n2/merchants/multiSigPay' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "merchantRequestId": "REQ123456789",
  "payeeVpa": "payee123@upi",
  "payerVpa": "payer456@upi",
  "payerName": "Rohit Sharma",
  "payeeName": "Virat Kohli",
  "amount": "1500.00",
  "action": "PAY",
  "bankAccountUniqueId": "ACC123456789",
  "accountReferenceId": "REF987654321",
  "initiator": "MAKER",
  "ifsc": "HDFC0001234",
  "credBlock": "{\"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|j+dtxs...1ca1o0CrjnUw==\",\"code\":\"NPCI\"}}}",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "remarks": "Payment towards invoice 12345",
  "expiry": "2025-12-31T23:59:59",
  "currency": "INR",
  "refUrl": "https://merchant.com/ref123",
  "refCategory": "02",
  "mcc": "6012",
  "initiationMode": "MOBILE",
  "purpose": "AV",
  "udfParameters": "{}",
  "iat": "1755524778",
  "featureTags": ["01","05","11"],
  "clVersion" : "2.0",
  "location": "Bangalore",
  "geocode": "12.9716,77.5946",
  "ip": "192.168.1.25",
  "capability": "5200000200010004000639292929292"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "00",
  "responseMessage": "Transaction completed successfully",
  "udfParameters": null,
  "payload": [{
    "merchantId": "MERCHANT123",
    "merchantChannelId": "CHANNEL001",
    "merchantCustomerId": "CUST98765",
    "merchantRequestId": "REQ123456789",
    "customerMobileNumber": "9876543210",
    "amount": "500.00",
    "initiator": "MAKER",
    "expiryTimestamp": "2025-08-18T18:30:00+05:30",
    "payeeVpa": "test@upi",
    "payerVpa": "payer@upi",
    "mcc": "1234",
    "payeeName": "Test Payee",
    "refUrl": "https://merchant.example.com/callback",
    "remarks": "Payment for order#1234",
    "purpose": "AV",
    "action": "PAY",
    "transactionTimestamp": "2025-08-18T15:00:00+05:30",
    "gatewayTransactionId": "AXISUPI123456789",
    "gatewayReferenceId": "REF987654321",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Successful"
  }]
}

This API is used to perform a Pay transaction, where the initiator is MAKER.

Note: In case merchant retries this api, the accounts will be fetched from NPCI again.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256.
merchantRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric. Should always start with merchant prefix provided.
payeeVpa	Vpa of the upi user who received the payment	something@handle
payerVpa	Vpa of the upi user who sent the payment	something@handle
payerName	Name of the payer	String
payeeName	Name of the payee	String
amount	Amount for transaction	Numeric string with two decimals
bankAccountUniqueId	Unique id for the bank account (does not change incase customer deregisters)	sha256(accountNumber + ifsc.substr(0,4))
accountReferenceId	Unique reference ID for the selected Account.	Reference id provided in the response of Get Bank Account api call
initiator	who initiates the payment	MAKER
ifsc	Ifsc for the bank account as returned by NPCI	String
clVersion	ClVersion - use GetCLVersion for exact value of the field clVersion	String
credBlock	Encrypted credblock containing user mpin	As returned by Common Library
upiRequestId	Unique request id passed to UPI switch	35 character alphanumeric. Should always start with merchant prefix provided
remarks	Any transaction summary	50 characters alphanumeric with space and hyphen
expiry	Expiry timestamp for the request	YYYY-MM-DDTHH:MM:SS+05:30
currency	Currency code	String - INR
deviceFingerPrint	Device fingerprint of the customer	String
purpose	Purpose code to be passed in case of Multi-Signatory Accounts	AV
action	This tells the action to be performed	PAY
udfParameters optional	Stringified JSON for udf parameters	JSON string
iat	Current Epoch Unix timestamp string. Has to be of 13 digit in Milliseconds	Example: 1496918882000
featureTags	This will be an array of feature values, each having it's own significance as decided by NPCI	Array of strings
location	Location of the payer	String with a maximum length of 40
geocode	Geocode of the payer	Numeric string
ip	iP address of the customer device	IPv4 or IPv6 string
capability	Hardware capability string representing device features	String with a maximum length of 99

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
udfParameters optional	Udf parameters as passed in the request	JSON string or null
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer as passed in the request	String
merchantRequestId	Unique request id generated by the merchant for tracking the transaction	String
customerMobileNumber	Customer mobile number as per device binding	12 digits mobile number string
amount	Transaction amount requested by the merchant	Decimal String (e.g., 500.00)
initiator	Identifies who initiated the transaction	String (e.g., MAKER, CHECKER)
expiryTimestamp	Expiry time of the transaction	YYYY-MM-DDTHH:MM:SS+05:30
payeeVpa	Virtual Payment Address (VPA) of the payee	something\@upi
payerVpa	Virtual Payment Address (VPA) of the payer	something\@upi
mcc	Merchant Category Code for the payee business	Numeric string
payeeName	Name of the payee merchant or beneficiary	String
refUrl	Callback URL or additional info URL provided by the merchant	HTTPS URL
remarks	Remarks or description attached to the transaction	String
purpose	Purpose code of the transaction	Refer Purpose code section (e.g., AV, 00–92)
action	The action to be performed for this transaction	PAY, COLLECT, etc.
transactionTimestamp	Timestamp when the transaction was initiated	YYYY-MM-DDTHH:MM:SS+05:30
gatewayTransactionId	Transaction id returned by gateway (internal reference)	String
gatewayReferenceId	Reference id generated by gateway for reconciliation	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code returned by gateway	String (e.g., 00)
gatewayResponseMessage	Response message for the code returned by gateway	String

Checker Callback - MULTI_SIG_PAYMENT

{
    "amount": "1000.00",
    "collectType": "MULTI_SIGNATORY",
    "expiry": "2025-08-25T00:00:00",
    "featureTags": [1, 2, 3],
    "gatewayTransactionId": "TXN-98765",
    "orgTxnId": "ORG-54321",
    "isVerifiedPayee": "YES",
    "initiationMode": "API",
    "merchantChannelId": "APL_CHANNEL_01",
    "merchantCustomerId": "DEMO-CUST-1234",
    "merchantId": "APL12345",
    "payeeMcc": "6011",
    "payeeName": "John Doe",
    "payeeVpa": "john.doe@apl",
    "makerName": null,
    "makerVpa": null,
    "purpose": "Subscription Payment",
    "refCategory": null,
    "refUrl": null,
    "remarks": null,
    "transactionTimestamp": "2025-08-18T10:00:00",
    "action": "REQUEST_RECEIVED",
    "type": "MULTI_SIG_PAYMENT"
}

Parameter	Description
amount	Transaction amount in text format.
collectType	Type of collection, e.g., MULTI_SIGNATORY.
expiry	Expiry timestamp for the request, with format YYYY-MM-DDT00:00:00.
featureTags	Array of numeric feature tags associated with the request.
gatewayTransactionId	Transaction ID generated from reqAuthValCust.
orgTxnId	Original transaction ID from reqAuthValCust.
isVerifiedPayee	Indicates if the payee is verified (YES/NO).
initiationMode	Mode of initiation for the request, e.g., API.
merchantChannelId	Unique ID for the channel through which the merchant is registered.
merchantCustomerId	Unique customer profile ID generated by the merchant.
merchantId	Unique ID for the merchant, as passed in the request headers.
payeeMcc	Merchant Category Code of the payee.
payeeName	Name of the payee (optional).
payeeVpa	VPA of the payee.
makerName	Name of the maker, if applicable (optional).
makerVpa	VPA of the maker, if applicable (optional).
purpose	Purpose of the transaction.
refCategory	Optional reference category.
refUrl	Optional reference URL.
remarks	Optional remarks.
transactionTimestamp	Timestamp of the transaction in ISO format.
action	Action type of the callback, e.g., REQUEST_RECEIVED.
type	Type of object, always MULTI_SIG_PAYMENT.

Signatory Pay (Checker)

curl -L -X POST '{{host}}/api/n2/merchants/multiSigPay' \
-H 'content-type: application/json' \
  'accept: application/json' \
  'x-merchant-id': 'TEST', \
  'x-merchant-channel-id': 'TESTAPP', \
  'x-timestamp': '1496918882000', \
  'x-merchant-signature': '26b339a48db62a...'
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "merchantRequestId": "REQ123456789",
  "payeeVpa": "payee123@upi",
  "payerVpa": "checker456@upi",
  "payeeName": "Virat Kohli",
  "amount": "1500.00",
  "action": "APPROVE",
  "bankAccountUniqueId": "ACC123456789",
  "accountReferenceId": "REF987654321",
  "ifsc": "HDFC0001234",
  "credBlock": "{\"mpincred\":{\"type\":\"PIN\",\"subType\":\"MPIN\",\"data\":{\"type\":\"\",\"skey\":\"\",\"pid\":\"\",\"ki\":\"20150822\",\"hmac\":\"\",\"encryptedBase64String\":\"2.0|j+dtxs...1ca1o0CrjnUw==\",\"code\":\"NPCI\"}}}",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "initiator": "CHECKER",
  "remarks": "Approving Maker initiated payment",
  "expiry": "2025-12-31T23:59:59",
  "currency": "INR",
  "refUrl": "https://merchant.com/ref123",
  "refCategory": "02",
  "mcc": "6012",
  "initiationMode": "MOBILE",
  "purpose": "AV",
  "udfParameters": "{}",
  "iat": "1755524778",
  "featureTags": ["01","05","11"],
  "location": "Bangalore",
  "geocode": "12.9716,77.5946",
  "ip": "192.168.1.25",
  "capability": "5200000200010004000639292929292"
}'

# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "00",
  "responseMessage": "Checker approved transaction successfully",
  "udfParameters": null,
  "payload": {
    "merchantId": "MERCHANT123",
    "merchantChannelId": "CHANNEL001",
    "merchantCustomerId": "CUST98765",
    "merchantRequestId": "REQ123456789",
    "customerMobileNumber": "9876543210",
    "amount": "1500.00",
    "expiryTimestamp": "2025-08-18T18:30:00+05:30",
    "payeeVpa": "payee123@upi",
    "payerVpa": "checker456@upi",
    "mcc": "6012",
    "payeeName": "Virat Kohli",
    "initiator": "CHECKER",
    "refUrl": "https://merchant.com/ref123",
    "remarks": "Approving Maker initiated payment",
    "purpose": "AV",
    "transactionTimestamp": "2025-08-18T15:00:00+05:30",
    "gatewayTransactionId": "AXISUPI123456789",
    "gatewayReferenceId": "REF987654321",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Successful"
  }
}

This API is used to perform a Checker approval or decline action on a Pay transaction, where the initiator is CHECKER. The checker either approves (APPROVE) or rejects (DECLINE) the payment request initially created by a maker.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric string with dot(.). Maximum length is 256
deviceFingerPrint	Device fingerprint of the customer	String
merchantRequestId	Unique id sent to UPI switch for the request	35 character alphanumeric
payeeVpa	VPA of the payee	something\@handle
payerVpa	VPA of the checker approving/declining the transaction	something\@handle
payeeName	Name of the payee	String
amount	Amount for transaction	Numeric string with two decimals
action	Action to be taken by the checker	APPROVE, DECLINE
bankAccountUniqueId	Unique id for the bank account	sha256(accountNumber + ifsc.substr(0,4))
accountReferenceId	Reference ID for the selected account	String
ifsc	IFSC for the bank account	String
credBlock	Encrypted credblock containing user mpin	As returned by Common Library
upiRequestId	Original UPI request id from the Maker’s transaction	35 character alphanumeric
initiator	Who initiates the approval/decline	CHECKER
remarks	Any comments or notes added by the checker	50 characters max
expiry	Expiry timestamp for the approval request	YYYY-MM-DDTHH:MM:SS+05:30
currency	Currency code	INR
refUrl	Callback URL or additional info URL provided by the merchant	HTTPS URL
refCategory	Reference category to indicate invoice/bill/ad type	00–02 etc.
mcc	Merchant Category Code for the payee	Numeric string
initiationMode	Mode of initiation	MOBILE, QR, etc.
purpose	Purpose code of the transaction	Refer Purpose code section
udfParameters optional	Stringified JSON for udf parameters	JSON string
iat	Current Epoch Unix timestamp in milliseconds	13 digits
featureTags	Array of feature values as decided by NPCI	Array of strings
location	Location of the checker	String (max 40)
geocode	Geocode of the checker	Numeric string
ip	IP address of the checker device	IPv4/IPv6 string
capability	Hardware capability string representing device features	String (max 99)

Response parameters

Parameter	Description	Values
status	PSP status of the API	SUCCESS, FAILURE
responseCode	PSP response code for the API	Refer error code section
responseMessage	PSP response message for the API	Refer error code section
udfParameters optional	Udf parameters as passed in the request	JSON string or null
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
merchantCustomerId	Merchant generated unique profile id for customer	String
merchantRequestId	Request id associated with the Maker’s transaction	String
customerMobileNumber	Customer mobile number (if available)	12 digit string
amount	Transaction amount	Decimal string
expiryTimestamp	Expiry time of the transaction	YYYY-MM-DDTHH:MM:SS+05:30
payeeVpa	VPA of the payee	something\@upi
payerVpa	VPA of the checker	something\@upi
mcc	Merchant Category Code	Numeric string
payeeName	Name of the payee	String
initiator	Who initiated this action	CHECKER
refUrl	Callback URL provided by merchant	HTTPS URL
remarks	Remarks or notes provided by the checker	String
purpose	Purpose code of the transaction	AV, 00–92
transactionTimestamp	Timestamp when checker action was taken	YYYY-MM-DDTHH:MM:SS+05:30
gatewayTransactionId	Transaction id returned by gateway	String
gatewayReferenceId	Reference id generated by gateway	String
gatewayResponseStatus	Response status from gateway	SUCCESS, FAILURE
gatewayResponseCode	Response code from gateway	String (e.g., 00)
gatewayResponseMessage	Gateway response message	String

Multisignatory Pay – Status Check

curl -L -X POST '{{host}}/api/n2/merchants/multiSigPay' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'x-merchant-id: TEST' \
-H 'x-merchant-channel-id: TESTAPP' \
-H 'x-timestamp: 1496918882000' \
-H 'x-merchant-signature: 26b339a48db62a...' \
--data-raw '{
  "merchantCustomerId": "test-merchantcustomer-1",
  "deviceFingerPrint": "d925f3dbcfac7f4531fc0b606cebb7950dac2f0464fe51b53167c4c7a7b5231e",
  "merchantRequestId": "REQ123456789",
  "payeeVpa": "payee123@upi",
  "payerVpa": "checker456@upi",
  "payeeName": "Virat Kohli",
  "amount": "1500.00",
  "action": "CHECK",
  "upiRequestId": "AUTef1a2908395239df56663244f8c7deaa",
  "initiator": "MAKER/CHECKER",
  "udfParameters": "{}",
  "iat": "1755524778",
  "featureTags": ["01","05","11"],
  "location": "Bangalore",
  "geocode": "12.9716,77.5946",
  "ip": "192.168.1.25",
  "capability": "5200000200010004000639292929292"
}'


# Response: HTTP 200 OK
{
  "status": "SUCCESS",
  "responseCode": "00",
  "responseMessage": "Name Signatory Check successful",
  "udfParameters": null,
  "payload": {
    "merchantId": "MERCHANT123",
    "merchantChannelId": "CHANNEL001",
    "merchantCustomerId": "CUST98765",
    "merchantRequestId": "REQ123456789",
    "customerMobileNumber": "9876543210",
    "amount": "1500.00",
    "expiryTimestamp": "2025-08-18T18:30:00+05:30",
    "payeeVpa": "payee123@upi",
    "payerVpa": "checker456@upi",
    "mcc": "6012",
    "payeeName": "Virat Kohli",
    "refUrl": "https://merchant.com/ref123",
    "remarks": "Name check completed",
    "purpose": "Subscription Payment",
    "transactionStatus": "PENDING",
    "checker": {
      "vpa": "checker456@upi",
      "approvalNum": "APR123456",
      "respCode": "00",
      "name": "Checker User",
      "accNum": "XXXXXXXXXXXX1234",
      "ifsc": "HDFC0001234",
      "code": "NPCI",
      "acType": "SAVINGS" },
    "maker": {
      "vpa": "maker111@upi",
      "approvalNum": "APR111111",
      "respCode": "00",
      "name": "Maker User",
      "accNum": "XXXXXXXXXXXX4321",
      "ifsc": "ICIC0005678",
      "code": "NPCI",
      "acType": "CURRENT" }
    "transactionTimestamp": "2025-08-18T15:00:00+05:30",
    "gatewayTransactionId": "AXISUPI123456789",
    "gatewayReferenceId": "REF987654321",
    "gatewayResponseStatus": "SUCCESS",
    "gatewayResponseCode": "00",
    "gatewayResponseMessage": "Successful" }
  }
}

The Multisignatory Pay – Status Check API is used to perform a status check of a Maker–Checker transaction flow. Depending on the initiator value in the request (MAKER or CHECKER), the corresponding object (maker or checker) is returned inside the payload along with transaction details.

Request parameters

Parameter	Description	Constraints
merchantCustomerId	Merchant generated unique profile id for customer	Alphanumeric, max 256
deviceFingerPrint	Device fingerprint of the customer	String
merchantRequestId	Unique id for the request	35 character alphanumeric
payeeVpa	VPA of the payee	something\@handle
payerVpa	VPA of the other party (maker/checker)	something\@handle
payeeName	Name of the payee	String
amount	Amount for transaction	Numeric string with two decimals
action	Action to be taken	Always CHECK
upiRequestId	Original UPI request id of Maker’s transaction	35 character alphanumeric
initiator	Identifies who is checking status	MAKER or CHECKER
udfParameters optional	Custom UDF parameters as stringified JSON	JSON string
iat	Current Epoch Unix timestamp (ms)	13 digits
featureTags	Array of feature values	Array of strings
location	Location of the initiator	String (max 40)
geocode	Geocode of the initiator	Numeric string
ip	IP address of the initiator’s device	IPv4/IPv6 string
capability	Hardware capability string representing device features	String (max 99)

Response parameters

Parameter	Description	Values/Type
status	API status	SUCCESS, FAILURE
responseCode	PSP response code	String (e.g., 00)
responseMessage	PSP response message	String
udfParameters	Udf parameters as passed in request	JSON or null
merchantId	Unique id for merchant	String
merchantChannelId	Merchant channel id	String
merchantCustomerId	Customer profile id	String
merchantRequestId	Unique request id	String
customerMobileNumber	Customer’s mobile number (if available)	12 digit string
amount	Transaction amount	Decimal string
expiryTimestamp	Expiry time of transaction	YYYY-MM-DDTHH:MM:SS+05:30
payeeVpa	VPA of payee	something\@upi
payerVpa	VPA of payer	something\@upi
mcc	Merchant Category Code	String
payeeName	Name of payee	String
refUrl	Reference URL	HTTPS URL
remarks	Remarks added by initiator	String
purpose	Purpose code of transaction	String
transactionStatus	Current status of transaction	PENDING, APPROVED, DECLINED
transactionTimestamp	Timestamp of transaction	YYYY-MM-DDTHH:MM:SS+05:30
gatewayTransactionId	Transaction id returned by gateway	String
gatewayReferenceId	Reference id from gateway	String
gatewayResponseStatus	Gateway status	SUCCESS, FAILURE
gatewayResponseCode	Gateway code	String
gatewayResponseMessage	Gateway message	String
maker	Maker object (if applicable, when initiator=MAKER)	See Maker object
checker	Checker object (if applicable, when initiator=CHECKER)	See Checker object

Deregister Callback - MULTI_SIG_PAYMENT

{
    "gatewayTransactionId": "GTX-123456789",
    "initiationMode": "API",
    "merchantChannelId": "CHN-APL-001",
    "merchantCustomerId": "CUST-APL-98765",
    "merchantId": "APL12345",
    "payerVpa": "payer123@upi",
    "payerName": "Rohit Sharma",
    "purpose": "AV",
    "refCategory": 02,
    "refUrl": null,
    "remarks": "Existing account deregistered from TPAP A",
    "transactionTimestamp": "2025-08-18T12:30:00",
    "action": "DEREGISTERED",
    "type": "MULTI_SIG_PAYMENT"
}

The Deregistration Callback is triggered by the Issuer Bank when a customer who is already linked with TPAP A attempts to register the same corporate account with TPAP B. During the ReqRegMob call from TPAP B, the issuer bank validates if the merchantCustomerId and account details are already linked with another TPAP/PSP. If so, the issuer fires a DEREGISTERED callback to the previously linked TPAP to remove the old mapping.

This ensures that a customer’s account remains linked to only one TPAP/PSP at a time, avoiding duplicate bindings.

Parameter	Description
gatewayTransactionId	Unique transaction ID generated for the deregistration event.
initiationMode	Mode of initiation (API / MOBILE_APP / etc.).
merchantChannelId	Unique ID for the merchant’s channel.
merchantCustomerId	Unique customer profile ID generated by the merchant.
merchantId	Unique merchant identifier (as passed in request headers).
payerVpa	VPA of the payer whose account is being deregistered.
payerName	Name of the payer (optional).
purpose	Purpose for deregistration (e.g., "Duplicate TPAP linking").
refCategory	Optional reference category, if any.
refUrl	Optional reference URL.
remarks	Additional comments provided by the issuer bank.
transactionTimestamp	Timestamp of deregistration in ISO 8601 format.
action	Always DEREGISTERED for this callback type.
type	Type of object, always MULTI_SIG_PAYMENT.

UDIR Refunds Overview

NPCI has introduced a new category as part of UDIR ReqComplaint API : ReqComplaint - Refund for online refunds. This refund is processed through NPCI via backoffice. TPAPs have to make necessary changes in order to consume PSP initiated UDIR Refund callbacks. TPAP is also expected to show the mapping of this refund against the original transaction. Adding below the changes

UDIR_STATUS_UPDATE

{
 "adjAmount": "100.00",
 "adjCode": "502",
 "adjFlag": "RRC",
 "currCycle": "Y",
 "customerMobileNumber": "9199999199",
 "gatewayComplaintId": "MUL8ec68a6c630b41478f8b343",
 "gatewayReferenceId": "420424951413",
 "gatewayResponseCode": "00",
 "gatewayResponseStatus": "SUCCESS",
 "gatewayResponseMessage": "Transaction is successful",
 "merchantChannelId": "ECYBUPITESTAPP",
 "merchantCustomerId": "707249",
 "merchantId": "A5471e57bff592b59fea728daa98ca9",
 "merchantRequestId": "MUL3614b6d527e146d78624b2b",
 "orgRespCode": "00",
 "orgSettRespCode": "00",
 "originalUpiRequestId": "MULf818ae645f5841259c0f38e",
 "originalTransactionTimestamp": "2024-07-22T15:13:31+05:30",
 "payeeVpa": "9199999199@ypay",
 "payerVpa": "ecybupitest@ypay",
 "remarks": "UDIR-REFUND",
 "reqAdjAmount": "1.00",
 "reqAdjCode": "1064",
 "reqAdjFlag": "REF",
 "transactionAmount": "100.00",
 "type": "UDIR_STATUS_UPDATE",
 "udirType": "REFUND"
}

Parameter	Description	Values
merchantId	Unique id for the merchant as passed in request headers	String
merchantChannelId	Unique id for the merchant channel as passed in request headers	String
subMerchantChannelId	Unique id for the sub-merchant channel	String
merchantCustomerId	Merchant generated unique profile id for customer	String
adjAmount	Adjusted amount for the refund transaction	Numeric string with decimals
adjFlag	Adjustment flag indicating the type of adjustment	String (e.g., RRC)
adjCode	Adjustment code for the refund	Numeric string (e.g., 502)
reqAdjFlag	Requested adjustment flag from the complaint	String (e.g., REF)
reqAdjCode	Requested adjustment code from the complaint	Numeric string (e.g., 1064)
reqAdjAmount	Requested adjustment amount	Numeric string with decimals
currCycle	Current cycle indicator for the refund	String (Y/N)
crn	Customer Reference Number for the complaint	String
customerMobileNumber	Customer mobile number	12 digits mobile number string
gatewayComplaintId	Complaint id generated by the gateway	String
gatewayReferenceId	Reference id returned by the gateway	String
gatewayResponseCode	Response code returned by gateway	String
gatewayResponseStatus	Response status returned by gateway	SUCCESS, FAILURE
gatewayResponseMessage	Response message for code returned by gateway	String
originalUpiRequestId	Original UPI request id of the transaction being refunded	String
orgSettRespCode	Original settlement response code	String
originalTransactionTimestamp	Timestamp of the original transaction	YYYY-MM-DDTHH:MM:SS+05:30
payeeVpa	VPA of the payee in the original transaction	something@handle
payerVpa	VPA of the payer in the original transaction	something@handle
remarks	Remarks for the refund transaction	String
payerMobileNumber	Mobile number of the payer	12 digits mobile number string
type	Callback event type for UDIR status updates	UDIR_STATUS_UPDATE
transactionAmount	Original transaction amount	Numeric string with decimals
merchantRequestId	Merchant generated request id for the complaint	String
orgRespCode	Original response code of the transaction	String
udirType	Type of UDIR complaint	REFUND, COMPLAINT